feat: add warn for headless: true (#10039)

Co-authored-by: Mathias Bynens <mathias@qiwi.be>

README.md

@@ -11,7 +11,7 @@
 > Chrome/Chromium over the
 > [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
 > Puppeteer runs in
-> [headless](https://developers.google.com/web/updates/2017/04/headless-chrome)
+> [headless](https://developer.chrome.com/articles/new-headless/)
 > mode by default, but can be configured to run in full (non-headless)
 > Chrome/Chromium.
 
@@ -176,14 +176,29 @@ import puppeteer from 'puppeteer';
 
 **1. Uses Headless mode**
 
-Puppeteer launches Chromium in
+By default Puppeteer launches Chromium in
-[headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome).
+[old Headless mode](https://developer.chrome.com/articles/new-headless/).
+
+```ts
+const browser = await puppeteer.launch();
+// Equivalent to
+const browser = await puppeteer.launch({headless: true});
+```
+
+[Chrome 112 launched a new Headless mode](https://developer.chrome.com/articles/new-headless/) that might cause some differences in behavior compared to the old Headless implementation.
+In the future Puppeteer will start defaulting to new implementation.
+We recommend you try it out before the switch:
+
+```ts
+const browser = await puppeteer.launch({headless: 'new'});
+```
+
 To launch a full version of Chromium, set the
-[`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions)
+[`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions) to `true`
 option when launching a browser:
 
 ```ts
-const browser = await puppeteer.launch({headless: false}); // default is true
+const browser = await puppeteer.launch({headless: false});
 ```
 
 **2. Runs a bundled version of Chromium**

docs/index.md

@@ -11,7 +11,7 @@
 > Chrome/Chromium over the
 > [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
 > Puppeteer runs in
-> [headless](https://developers.google.com/web/updates/2017/04/headless-chrome)
+> [headless](https://developer.chrome.com/articles/new-headless/)
 > mode by default, but can be configured to run in full (non-headless)
 > Chrome/Chromium.
 
@@ -176,14 +176,29 @@ import puppeteer from 'puppeteer';
 
 **1. Uses Headless mode**
 
-Puppeteer launches Chromium in
+By default Puppeteer launches Chromium in
-[headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome).
+[old Headless mode](https://developer.chrome.com/articles/new-headless/).
+
+```ts
+const browser = await puppeteer.launch();
+// Equivalent to
+const browser = await puppeteer.launch({headless: true});
+```
+
+[Chrome 112 launched a new Headless mode](https://developer.chrome.com/articles/new-headless/) that might cause some differences in behavior compared to the old Headless implementation.
+In the future Puppeteer will start defaulting to new implementation.
+We recommend you try it out before the switch:
+
+```ts
+const browser = await puppeteer.launch({headless: 'new'});
+```
+
 To launch a full version of Chromium, set the
-[`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions)
+[`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions) to `true`
 option when launching a browser:
 
 ```ts
-const browser = await puppeteer.launch({headless: false}); // default is true
+const browser = await puppeteer.launch({headless: false});
 ```
 
 **2. Runs a bundled version of Chromium**

packages/puppeteer-core/src/node/ChromeLauncher.ts

@@ -24,6 +24,7 @@ import {
 } from '@puppeteer/browsers';
 
 import {debugError} from '../common/util.js';
+import {Browser} from '../puppeteer-core.js';
 import {assert} from '../util/assert.js';
 
 import {
@@ -43,6 +44,28 @@ export class ChromeLauncher extends ProductLauncher {
     super(puppeteer, 'chrome');
   }
 
+  override launch(options: PuppeteerNodeLaunchOptions = {}): Promise<Browser> {
+    const headless = options.headless ?? true;
+    if (
+      headless === true &&
+      this.puppeteer.configuration.logLevel !== 'silent'
+    ) {
+      console.warn(
+        [
+          '\x1B[1m\x1B[43m\x1B[30m',
+          'Puppeteer old Headless deprecation warning:\x1B[0m\x1B[33m',
+          '  In the near feature `headless: true` will default to the new Headless mode',
+          '  for Chrome instead of the old Headless implementation. For more',
+          '  information, please see https://developer.chrome.com/articles/new-headless/.',
+          '  Consider opting in early by passing `headless: "new"` to `puppeteer.launch()`',
+          '  If you encounter any bugs, please report them to https://github.com/puppeteer/puppeteer/issues/new/choose.\x1B[0m\n',
+        ].join('\n  ')
+      );
+    }
+
+    return super.launch(options);
+  }
+
   /**
    * @internal
    */

packages/puppeteer-core/src/node/LaunchOptions.ts

@@ -25,6 +25,12 @@ import {Product} from '../common/Product.js';
 export interface BrowserLaunchArgumentOptions {
   /**
    * Whether to run the browser in headless mode.
+   *
+   * @remarks
+   * In the future `headless: true` will be equivalent to `headless: 'new'`.
+   * You can read more about the change {@link https://developer.chrome.com/articles/new-headless/ | here}.
+   * Consider opting in early by setting the value to `"new"`.
+   *
    * @defaultValue `true`
    */
   headless?: boolean | 'new';