docs: document --no-shell option (#34120)

docs/src/api/params.md

@@ -1003,7 +1003,7 @@ Additional arguments to pass to the browser instance. The list of Chromium flags
 
 Browser distribution channel.
 
-Use "chromium" to [opt in to new headless mode](../browsers.md#opt-in-to-new-headless-mode).
+Use "chromium" to [opt in to new headless mode](../browsers.md#chromium-new-headless-mode).
 
 Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or "msedge-canary" to use branded [Google Chrome and Microsoft Edge](../browsers.md#google-chrome--microsoft-edge).
 

docs/src/browsers.md

@@ -338,11 +338,11 @@ 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. See [issue #33566](https://github.com/microsoft/playwright/issues/33566) for details.
+### Chromium: headless shell
 
-#### Optimize download size on CI
+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.
 
-If you are only running tests in headless shell (i.e. the `channel` option is not specified), for example on CI, you can avoid downloading the full Chromium browser by passing `--only-shell` during installation.
+If you are only running tests in headless shell (i.e. the `channel` option is **not** specified), for example on CI, you can avoid downloading the full Chromium browser by passing `--only-shell` during installation.
 
 ```bash js
 # only running tests headlessly
@@ -364,7 +364,7 @@ playwright install --with-deps --only-shell
 pwsh bin/Debug/netX/playwright.ps1 install --with-deps --only-shell
 ```
 
-#### Opt-in to new headless mode
+### Chromium: 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):
 
@@ -419,6 +419,28 @@ pytest test_login.py --browser-channel chromium
 dotnet test -- Playwright.BrowserName=chromium Playwright.LaunchOptions.Channel=chromium
 ```
 
+With the new headless mode, you can skip downloading the headless shell during browser installation by using the `--no-shell` option:
+
+```bash js
+# only running tests headlessly
+npx playwright install --with-deps --no-shell
+```
+
+```bash java
+# only running tests headlessly
+mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps --no-shell"
+```
+
+```bash python
+# only running tests headlessly
+playwright install --with-deps --no-shell
+```
+
+```bash csharp
+# only running tests headlessly
+pwsh bin/Debug/netX/playwright.ps1 install --with-deps --no-shell
+```
+
 ### Google Chrome & Microsoft Edge
 
 While Playwright can download and use the recent Chromium build, it can operate against the branded Google Chrome and Microsoft Edge browsers available on the machine (note that Playwright doesn't install them by default). In particular, the current Playwright version will support Stable and Beta channels of these browsers.

docs/src/chrome-extensions-js-python.md

@@ -214,7 +214,7 @@ def test_popup_page(page: Page, extension_id: str) -> None:
 
 ## Headless mode
 
-By default, Chrome's headless mode in Playwright does not support Chrome extensions. To overcome this limitation, you can run Chrome's persistent context with a new headless mode by using [channel `chromium`](./browsers.md#opt-in-to-new-headless-mode):
+By default, Chrome's headless mode in Playwright does not support Chrome extensions. To overcome this limitation, you can run Chrome's persistent context with a new headless mode by using [channel `chromium`](./browsers.md#chromium-new-headless-mode):
 
 ```js title="fixtures.ts"
 // ...

packages/playwright-core/types/types.d.ts

@@ -14716,7 +14716,7 @@ export interface BrowserType<Unused = {}> {
     /**
      * Browser distribution channel.
      *
-     * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#opt-in-to-new-headless-mode).
+     * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
      *
      * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or
      * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).
@@ -15215,7 +15215,7 @@ export interface BrowserType<Unused = {}> {
     /**
      * Browser distribution channel.
      *
-     * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#opt-in-to-new-headless-mode).
+     * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
      *
      * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or
      * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).
@@ -21566,7 +21566,7 @@ export interface LaunchOptions {
   /**
    * Browser distribution channel.
    *
-   * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#opt-in-to-new-headless-mode).
+   * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
    *
    * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or
    * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).

packages/playwright/types/test.d.ts

@@ -6002,7 +6002,7 @@ export interface PlaywrightWorkerOptions {
   /**
    * Browser distribution channel.
    *
-   * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#opt-in-to-new-headless-mode).
+   * Use "chromium" to [opt in to new headless mode](https://playwright.dev/docs/browsers#chromium-new-headless-mode).
    *
    * Use "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", or
    * "msedge-canary" to use branded [Google Chrome and Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge).