docs: update installation guide for @playwright/test (#7491)

This forks installation guide for library vs test.
Also updated various mentions of installation.
Also updated the test annotations guide.

docs/src/ci.md

@@ -16,9 +16,13 @@ configurations for common CI providers.
    in Linux agents or install your dependencies using the [CLI](./cli.md#install-system-dependencies). Windows and macOS agents do not require any additional dependencies.
 1. **Install Playwright**:
    ```bash js
+   # Install NPM packages
    npm ci
    # or
    npm install
+
+   # Install Playwright browsers
+   npx playwright install
    ```
    ```bash python
    pip install playwright

docs/src/cli.md

@@ -101,6 +101,8 @@ playwright install --help
 playwright install --help
 ```
 
+Learn more about managing browser binaries with [Playwright Library](./installation.md) or [Playwright Test](./test-install.md).
+
 ## Generate code
 
 ```bash js

docs/src/installation.md

@@ -3,6 +3,8 @@ id: installation
 title: "Installation"
 ---
 
+This is a browser installation guide for Playwright Library. If you are using Playwright Test, please refer to [installing browsers](./test-install.md) test guide.
+
 <!-- TOC -->
 
 ## Managing browser binaries
@@ -247,8 +249,6 @@ mvn test
 It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that
 take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
 
-It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
-
 ```bash js
 # Linux/macOS
 PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm i -D playwright

docs/src/intro-js.md

@@ -34,7 +34,7 @@ Unlike Playwright Library, Playwright Test does not bundle browsers by default,
 npx playwright install
 ```
 
-You can optionally install only selected browsers, see [Playwright CLI](./cli.md) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
+You can optionally install only selected browsers, see [installing browsers](./test-install.md) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
 
 ## First test
 

docs/src/test-annotations.md

@@ -13,6 +13,8 @@ Playwright Test supports test annotations to deal with failures, flakiness, skip
 - `fixme` marks the test as failing. Playwright Test will not run this test, as opposite to the `fail` annotation. Use `fixme` when running the test is slow or crashy.
 - `slow` marks the test as slow and triples the test timeout.
 
+Annotations can be used on a single test or a group of tests. Annotations can be conditional, in which case they apply when the condition is truthy. Annotations may depend on test fixtures. There could be multiple annotations on the same test, possibly in different configurations.
+
 ## Focus a test
 
 You can focus some tests. When there are focused tests, only these tests run.
@@ -77,14 +79,6 @@ test.describe('two tests', () => {
 });
 ```
 
-Annotations apply when the condition is truthy, or always when no condition is passed, and may include a description. Annotations may depend on test fixtures. There could be multiple annotations on the same test, possibly in different configurations.
-
-Available annotations:
-- `skip` marks the test as irrelevant. Playwright Test does not run such a test. Use this annotation when the test is not applicable in some configuration.
-- `fail` marks the test as failing. Playwright Test will run this test and ensure it does indeed fail. If the test does not fail, Playwright Test will complain.
-- `fixme` marks the test as failing. Playwright Test will not run this test, as opposite to the `fail` annotation. Use `fixme` when running the test is slow or crashy.
-- `slow` marks the test as slow and triples the test timeout.
-
 ## Tag tests
 
 Sometimes you want to tag your tests as `@fast` or `@slow` and only run the tests that have the certain tag. We recommend that you use the `--grep` and `--grep-invert` command line flags for that:
@@ -124,3 +118,81 @@ Or if you want the opposite, you can skip the tests with a certain tag:
 ```bash
 npx playwright test --grep-invert @slow
 ```
+
+## Conditionally skip a group of tests
+
+For example, you can run a group of tests just in Chromium by passing a callback.
+
+```js js-flavor=js
+// example.spec.js
+
+test.describe('chromium only', () => {
+  test.skip(({ browserName }) => browserName !== 'chromium', 'Chromium only!');
+
+  test.beforeAll(async () => {
+    // This hook is only run in Chromium.
+  });
+
+  test('test 1', async ({ page }) => {
+    // This test is only run in Chromium.
+  });
+
+  test('test 2', async ({ page }) => {
+    // This test is only run in Chromium.
+  });
+});
+```
+
+```js js-flavor=ts
+// example.spec.ts
+
+test.describe('chromium only', () => {
+  test.skip(({ browserName }) => browserName !== 'chromium', 'Chromium only!');
+
+  test.beforeAll(async () => {
+    // This hook is only run in Chromium.
+  });
+
+  test('test 1', async ({ page }) => {
+    // This test is only run in Chromium.
+  });
+
+  test('test 2', async ({ page }) => {
+    // This test is only run in Chromium.
+  });
+});
+```
+
+## Use fixme in `beforeEach` hook
+
+To avoid running `beforeEach` hooks, you can put annotations in the hook itself.
+
+```js js-flavor=js
+// example.spec.js
+
+test.beforeEach(async ({ page, isMobile }) => {
+  test.fixme(isMobile, 'Settings page does not work in mobile yet');
+
+  await page.goto('http://localhost:3000/settings');
+});
+
+test('user profile', async ({ page }) => {
+  await page.click('text=My Profile');
+  // ...
+});
+```
+
+```js js-flavor=ts
+// example.spec.ts
+
+test.beforeEach(async ({ page }) => {
+  test.fixme(isMobile, 'Settings page does not work in mobile yet');
+
+  await page.goto('http://localhost:3000/settings');
+});
+
+test('user profile', async ({ page }) => {
+  await page.click('text=My Profile');
+  // ...
+});
+```

docs/src/test-install.md

@@ -0,0 +1,144 @@
+---
+id: test-install
+title: "Advanced: installing browsers"
+---
+
+This is a browser installation guide for Playwright Test. If you are using Playwright Library, please refer to [Library Installation](./installation.md) guide.
+
+<!-- TOC -->
+
+## Installing browser binaries
+
+Each version of Playwright Test needs specific versions of browser binaries to operate. Playwright Test includes [Command Line Interface](./cli.md) that can download these binaries. By default, Playwright Test downloads Chromium, WebKit and Firefox browsers into the OS-specific cache folders:
+
+- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
+- `~/Library/Caches/ms-playwright` on MacOS
+- `~/.cache/ms-playwright` on Linux
+
+```bash
+# Add dependency
+npm i -D @playwright/test
+# Download browser binaries
+npx playwright install
+```
+
+These browsers will take a few hundred megabytes of disk space when installed:
+
+```bash
+du -hs ~/Library/Caches/ms-playwright/*
+281M  chromium-XXXXXX
+187M  firefox-XXXX
+180M  webkit-XXXX
+```
+
+## Installing a single browser binary
+
+Playwright Test downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument.
+
+```bash
+npx playwright install webkit
+```
+
+## Managing browser binaries
+
+You can override default installation behavior using environment variables. When installing browsers, ask Playwright Test to download them into a specific location.
+
+```bash
+# Linux/macOS
+PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
+
+# Windows with cmd.exe
+set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
+npx playwright install
+
+# Windows with PowerShell
+$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
+npx playwright install
+```
+
+When running tests, ask it to search for browsers in a shared location.
+
+```bash
+# Linux/macOS
+PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test
+
+# Windows with cmd.exe
+set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
+npx playwright test
+
+# Windows with PowerShell
+$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
+npx playwright test
+```
+
+Or you can opt into the hermetic install and place binaries in the local folder:
+
+```bash
+# Linux/macOS
+# Places binaries to node_modules/@playwright/test
+PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install
+
+# Windows with cmd.exe
+# Places binaries to node_modules\@playwright\test
+set PLAYWRIGHT_BROWSERS_PATH=0
+npx playwright install
+
+# Windows with PowerShell
+# Places binaries to node_modules\@playwright\test
+$env:PLAYWRIGHT_BROWSERS_PATH=0
+npx playwright install
+```
+
+Playwright Test keeps track of packages that need those browsers and will garbage collect them as you update Playwright Test to the newer versions.
+
+## Install behind a firewall or a proxy
+
+By default, Playwright Test downloads browsers from Microsoft CDN.
+
+Sometimes companies maintain an internal proxy that blocks direct access to the public
+resources. In this case, Playwright can be configured to download browsers via a proxy server.
+
+```bash
+# Linux/macOS
+HTTPS_PROXY=https://192.0.2.1 npx playwright install
+
+# Windows with cmd.exe
+set HTTPS_PROXY=https://192.0.2.1
+npx playwright install
+
+# Windows with PowerShell
+$env:HTTPS_PROXY="https://192.0.2.1"
+npx playwright install
+```
+
+## Download from artifact repository
+
+By default, Playwright downloads browsers from Microsoft CDN.
+
+Sometimes companies maintain an internal artifact repository to host browser
+binaries. In this case, Playwright can be configured to download from a custom
+location using the `PLAYWRIGHT_DOWNLOAD_HOST` env variable.
+
+```bash
+# Linux/macOS
+PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install
+
+# Windows with cmd.exe
+set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
+npx playwright install
+
+# Windows with PowerShell
+$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
+npx playwright install
+```
+
+It is also possible to choose a per-browser download host using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that
+take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
+
+## Stale browser removal
+
+Playwright Test keeps track of the clients that use its browsers. When there are no more clients that require particular
+version of the browser, that version is deleted from the system. That way you can safely use Playwright Test instances of
+different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.
+
+To opt-out from the unused browser removal, you can set the `PLAYWRIGHT_SKIP_BROWSER_GC=1` environment variable.