cherry-pick(#33604): docs: update docs about headless shell

Author: dgozman

docs/src/browsers.md

@@ -338,30 +338,85 @@ dotnet test --settings:webkit.runsettings
 
 For Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds. Since the Chromium project is ahead of the branded browsers, when the world is on Google Chrome N, Playwright already supports Chromium N+1 that will be released in Google Chrome and Microsoft Edge a few weeks later.
 
-Playwright ships a regular Chromium build for headed operations and a separate [Chromium headless shell](https://developer.chrome.com/blog/chrome-headless-shell) for headless mode. These two behave differently in some edge cases, but the majority of testing scenarios are not affected. Note this behavior has changed in Playwright version 1.49, see [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
+Playwright ships a regular Chromium build for headed operations and a separate [chromium headless shell](https://developer.chrome.com/blog/chrome-headless-shell) for headless mode. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
 
-#### Save on download size
+#### Optimize download size on CI
 
-If you are only running tests in headless, for example on CI, you can avoid downloading a headed version of Chromium by specifying `chromium-headless-shell` during installation.
+If you are only running tests in headless mode, for example on CI, you can avoid downloading a regular version of Chromium by passing `--only-shell` during installation.
 
 ```bash js
-# When only running tests headlessly
-npx playwright install chromium-headless-shell firefox webkit
+# only running tests headlessly
+npx playwright install --with-deps --only-shell
 ```
 
 ```bash java
-# When only running tests headlessly
-mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install chromium-headless-shell firefox webkit"
+# only running tests headlessly
+mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --only-shell"
 ```
 
 ```bash python
-# When only running tests headlessly
-playwright install chromium-headless-shell firefox webkit
+# only running tests headlessly
+playwright install --with-deps --only-shell
 ```
 
 ```bash csharp
-# When only running tests headlessly
-pwsh bin/Debug/netX/playwright.ps1 install chromium-headless-shell firefox webkit
+# only running tests headlessly
+pwsh bin/Debug/netX/playwright.ps1 install --with-deps --only-shell
+```
+
+#### Opt-in to new headless mode
+
+You can opt into the new headless mode by using `'chromium'` channel. As [official Chrome documentation puts it](https://developer.chrome.com/blog/chrome-headless-shell):
+
+> New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.
+
+See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
+
+```js
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], channel: 'chromium' },
+    },
+  ],
+});
+```
+
+```java
+import com.microsoft.playwright.*;
+
+public class Example {
+  public static void main(String[] args) {
+    try (Playwright playwright = Playwright.create()) {
+      Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setChannel("chromium"));
+      Page page = browser.newPage();
+      // ...
+    }
+  }
+}
+```
+
+```bash python
+pytest test_login.py --browser-channel chromium
+```
+
+```xml csharp
+<?xml version="1.0" encoding="utf-8"?>
+<RunSettings>
+  <Playwright>
+    <BrowserName>chromium</BrowserName>
+    <LaunchOptions>
+      <Channel>chromium</Channel>
+    </LaunchOptions>
+  </Playwright>
+</RunSettings>
+```
+
+```bash csharp
+dotnet test -- Playwright.BrowserName=chromium Playwright.LaunchOptions.Channel=chromium
 ```
 
 ### Google Chrome & Microsoft Edge

docs/src/release-notes-js.md

@@ -40,58 +40,41 @@ Learn more in the [aria snapshots guide](./aria-snapshots).
 
 ### Breaking: channels `chrome`, `msedge` and similar switch to new headless
 
-Prior to this release, Playwright was running the old established implementation of [Chromium headless mode](https://developer.chrome.com/docs/chromium/headless). However, Chromium had entirely **switched to the new headless mode**, and **removed the old one**.
+This change affects you if you're using one of the following channels in your `playwright.config.ts`:
+- `chrome`, `chrome-dev`, `chrome-beta`, or `chrome-canary`
+- `msedge`, `msedge-dev`, `msedge-beta`, or `msedge-canary`
 
-![Chromium Headless](https://github.com/user-attachments/assets/2829e86a-dfe2-4743-a6d4-2aa65beea890)
+#### What do I need to do?
 
-If you are using a browser channel, for example `'chrome'` or `'msedge'`, the headless mode switch **will affect you**. Most likely, you will have to update some of your tests and all of your screenshot expectations. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for more details.
+After updating to Playwright v1.49, run your test suite. If it still passes, you're good to go. If not, you will probably need to update your snapshots, and adapt some of your test code around PDF viewers and extensions. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for more details.
 
-#### Chromium headless shell
-
-Starting with this release, Playwright downloads and runs two different browser builds - one is a regular headed chromium and the other is a chromium headless shell. This should be transparent to you, **no action is needed**. You can learn more in [issue #33566](https://github.com/microsoft/playwright/issues/33566).
-
-If you are only running tests in headless, for example on CI, you can avoid downloading a headed version of Chromium by specifying `chromium-headless-shell` during installation.
-
-```bash
-# only running tests headlessly
-npx playwright install chromium-headless-shell firefox webkit
-```
+### Other breaking changes
 
-Playwright will skip downloading headed chromium build, and will use `chromium-headless-shell` when running headless.
+- There will be no more updates for WebKit on Ubuntu 20.04 and Debian 11. We recommend updating your OS to a later version.
+- Package `@playwright/experimental-ct-vue2` will no longer be updated.
+- Package `@playwright/experimental-ct-solid` will no longer be updated.
 
-#### Opt-in to new headless
+### Try new Chromium headless
 
-We encourage everyone to try and switch to the new headless by using the `chromium-next` channel.
+You can opt into the new headless mode by using `'chromium'` channel. As [official Chrome documentation puts it](https://developer.chrome.com/blog/chrome-headless-shell):
 
-First, install this channel prior to running tests. Make sure to list all the browsers that you use.
+> New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.
 
-```bash
-npx playwright install chromium-next firefox webkit
-```
-
-Then update your config file to specify `'chromium-next'` channel.
+See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for the list of possible breakages you could encounter and more details on Chromium headless. Please file an issue if you see any problems after opting in.
 
 ```js
 import { defineConfig, devices } from '@playwright/test';
+
 export default defineConfig({
   projects: [
     {
       name: 'chromium',
-      use: {
-        ...devices['Desktop Chrome'],
-        channel: 'chromium-next',
-      },
+      use: { ...devices['Desktop Chrome'], channel: 'chromium' },
     },
   ],
 });
 ```
 
-### Other breaking changes
-
-- There will be no more updates for WebKit on Ubuntu 20.04 and Debian 11. We recommend updating your OS to a later version.
-- Package `@playwright/experimental-ct-vue2` will no longer be updated.
-- Package `@playwright/experimental-ct-solid` will no longer be updated.
-
 ### Miscellaneous
 
 - `<canvas>` elements inside a snapshot now draw a preview.