ci

199 notes in this subject, read out of this brain and free to use. This is page 2 of 4.

Install system dependencies for browsers

Run `npx playwright install-deps` to automatically install system dependencies required for running browsers. You can target a specific browser: `npx playwright install-deps chromium`. Combine both commands with `npx playwright install --with-deps chromium` to install browsers and OS dependencies in one command.

Playwright version update cycle

Each version of Playwright requires specific versions of browser binaries. With every Playwright release, browser versions are updated. This means re-running the install CLI command is often necessary after updating Playwright to fetch new browser versions.

Projects configuration for multi-browser testing

Define projects in the Playwright config to run tests on multiple browsers and configurations. Each project specifies a name and use options that can include device settings and browser channel. All projects run by default when executing tests.

Run specific project with --project flag

Use `npx playwright test --project=firefox` to run tests only on a specific project. The project name is defined in the Playwright config.

Chromium headless shell installation

Playwright ships a regular Chromium build for headed operations and a separate chromium headless shell for headless mode. If only running tests headlessly (without channel option specified), use `npx playwright install --only-shell` to avoid downloading the full Chromium browser.

Chromium new headless mode with channel option

Opt into the new headless mode by using channel: 'chromium'. The new headless mode is the real Chrome browser, offering more authenticity and features suitable for high-accuracy end-to-end web app testing or browser extension testing.

Skip chromium headless shell download with --no-shell

When using the new headless mode (channel: 'chromium'), skip downloading the headless shell during browser installation by using `npx playwright install --with-deps --no-shell`.

Google Chrome and Microsoft Edge available channels

Available channels for branded browsers are: 'chrome', 'msedge', 'chrome-beta', 'msedge-beta', 'chrome-dev', 'msedge-dev', 'chrome-canary', 'msedge-canary'. Playwright supports the Stable and Beta channels of these browsers.

Google Chrome and Microsoft Edge configuration example

Example of configuring projects for branded browsers: ```js import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ projects: [ { name: 'Google Chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' }, }, { name: 'Microsoft Edge', use: { ...devices['Desktop Edge'], channel: 'msedge' }, }, ], }); ```

Install Google Chrome or Microsoft Edge

If Google Chrome or Microsoft Edge is not available on your machine, install them using the Playwright CLI: `npx playwright install msedge`. This installs them at the default global location for your operating system, potentially overriding the current browser installation.

Firefox version matching

Playwright's Firefox version matches the recent Firefox Stable build. Playwright does not work with branded versions of Firefox since it relies on patches.

WebKit version and platform considerations

Playwright's WebKit is derived from the latest WebKit main branch sources, often before these updates are incorporated into Apple Safari. Playwright does not work with branded Safari since it relies on patches. WebKit feature availability varies by operating system; for closest-to-Safari experience, run WebKit on macOS, particularly for video playback.

HTTPS_PROXY environment variable for proxy downloads

Configure Playwright to download browsers through a proxy server by setting the HTTPS_PROXY environment variable: `HTTPS_PROXY=https://192.0.2.1 npx playwright install`.

NODE_EXTRA_CA_CERTS for custom certificate authority

When proxy requests are intercepted with a custom untrusted certificate authority and yield 'Error: self signed certificate in certificate chain', set NODE_EXTRA_CA_CERTS environment variable before installing browsers: `export NODE_EXTRA_CA_CERTS="/path/to/cert.pem"`.

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT for slow networks

Increase the connection timeout (in milliseconds) for slow network connections to Playwright browser archive using the PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT environment variable: `PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install`.

PLAYWRIGHT_DOWNLOAD_HOST for custom artifact repository

Configure Playwright to download browsers from a custom artifact repository by setting PLAYWRIGHT_DOWNLOAD_HOST environment variable: `PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install`.

Per-browser download hosts with environment variables

Use per-browser download hosts with PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST, PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST, and PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST environment variables. These take precedence over the general PLAYWRIGHT_DOWNLOAD_HOST variable.

Update Playwright and browsers regularly

Keep Playwright up to date to use new features and test on latest browser versions. Update with `npm install -D @playwright/test@latest`, then run `npx playwright install` to fetch new browser versions. Check release notes and version with `npx playwright --version`.

Uninstall browsers

Remove browsers (chromium, firefox, webkit) of the current Playwright installation using `npx playwright uninstall`. Use `npx playwright uninstall --all` to remove browsers of other Playwright installations as well.

List installed browsers

Print list of all browsers from all Playwright installations on the machine using `npx playwright install --list`.

PLAYWRIGHT_NODEJS_PATH for pre-installed Node.js

Specify a pre-installed Node.js binary using the PLAYWRIGHT_NODEJS_PATH environment variable instead of Playwright's bundled runtime: `PLAYWRIGHT_NODEJS_PATH="/usr/local/bin/node" npx playwright install`. This is useful when you need a specific Node.js version or when the bundled runtime is incompatible.

Default browser installation locations

Playwright downloads browsers into OS-specific cache folders: %USERPROFILE%\AppData\Local\ms-playwright on Windows, ~/Library/Caches/ms-playwright on macOS, and ~/.cache/ms-playwright on Linux. Browser installations take several hundred megabytes of disk space.

PLAYWRIGHT_BROWSERS_PATH for custom browser installation location

Override the default browser installation location using the PLAYWRIGHT_BROWSERS_PATH environment variable: `PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install`. This applies when installing and running Playwright scripts.

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD for managed browser binaries

Set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 to avoid browser downloads when browser binaries are managed separately: `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test`.

Hermetic install with PLAYWRIGHT_BROWSERS_PATH=0

Place browser binaries in the local node_modules folder using hermetic install: `PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install`. This places binaries to node_modules/playwright-core/.local-browsers. Note: This does not change installation path for Google Chrome and Microsoft Edge.

Install canary release with npm install @playwright/test@next

To use a canary release, run npm install -D @playwright/test@next

Canary releases pass all automated tests

Canary releases pass all automated tests and are used to test features like the HTML report, Trace Viewer, and Playwright Inspector with end-to-end tests.

Canary releases published daily on @next NPM tag

Playwright for Node.js publishes canary releases daily on the @next NPM dist tag. These releases allow you to test new unreleased features before a full release is available.

NPM dist tags for Playwright releases

Playwright has three NPM dist tags: latest (stable releases), next (canary releases published daily), and beta (published after a release-branch is cut, usually a week before a stable release, with each commit getting published under this tag).

View next documentation on playwright.dev

The next documentation is published on playwright.dev alongside stable documentation. To view the next documentation, press Shift 5 times on the keyboard.

Playwright browser helper packages auto-install

Alternatively to manual browser installation, you can add package helpers that automatically download browsers during npm install: `npm install -D @playwright/browser-chromium @playwright/browser-firefox @playwright/browser-webkit`.

Install Playwright Library browsers

To download and install Playwright browsers, run `npx playwright install`. This downloads Chromium, Firefox, and WebKit. You can also install specific browsers individually, e.g., `npx playwright install chromium`.

Skip Playwright browser downloads

To avoid browser downloads altogether when browser binaries are managed separately, set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` before installing packages. For example: `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install`.

Download Playwright browsers from artifact repository

To download Playwright browsers from an internal artifact repository instead of Microsoft's CDN, set the `PLAYWRIGHT_DOWNLOAD_HOST` environment variable. For example: `PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install`.

Download Playwright browsers behind a firewall or proxy

To download Playwright browsers through a proxy, set the `HTTPS_PROXY` environment variable before installing. For example: `HTTPS_PROXY=https://192.0.2.1 npx playwright install` or `HTTPS_PROXY=https://192.0.2.1 npm install` when using helper packages.

Run tests on CI frequently

Setup CI/CD and run tests frequently. Ideally run tests on each commit and pull request. Playwright comes with a GitHub actions workflow so tests will run on CI with no setup required. Playwright can also be set up on any CI environment. Use Linux when running tests on CI as it is cheaper.

Optimize browser downloads on CI

Only install the browsers that you actually need, especially on CI. For example, if testing only with Chromium, install just Chromium instead of all browsers. This saves both download time and disk space on CI machines.

Install only Chromium on CI example

# Instead of installing all browsers npx playwright install --with-deps # Install only Chromium npx playwright install chromium --with-deps

Lint tests with TypeScript and ESLint

Use TypeScript and linting with ESLint for tests to catch errors early. Use the @typescript-eslint/no-floating-promises ESLint rule to ensure there are no missing awaits before asynchronous calls to the Playwright API. On CI, run 'tsc --noEmit' to ensure functions are called with the right signature.

Run only last failed tests with --last-failed flag

Use `npx playwright test --last-failed` to run only the tests that failed in the last test run. Playwright stores the list of failed tests from the previous run in `<outputDir>/.last-run.json`. To use a different file path, pass `--last-failed-file=<path>` or set the `PLAYWRIGHT_LAST_RUN_OUTPUT_FILE` environment variable.

Run tests from VS Code extension

Tests can be run from VS Code using the VS Code Playwright extension. Once installed, you can click the green triangle next to the test you want to run or run all tests from the testing sidebar.

Tests run in parallel by default

Tests run in parallel by default and in headless mode, meaning no browser window opens while running the tests and results appear in the terminal.

Open HTML test report with show-report command

Use `npx playwright show-report` to open the HTML Reporter. The HTML Report shows a full report of your tests allowing you to filter by browsers, passed tests, failed tests, skipped tests, and flaky tests. By default, the HTML report opens automatically if some tests failed.

Run all tests with playwright test command

Tests are run with the command `npx playwright test`. This runs tests on all browsers configured in the playwright.config file. Tests run in headless mode by default, meaning no browser window opens while running the tests.

Run tests in UI mode with --ui flag

Use `npx playwright test --ui` to run tests in UI Mode. UI Mode provides a better developer experience where you can walk through each step of the test and visually see what happened before, during, and after each step. It includes features such as the locator picker, watch mode, and more.

Run tests in headed mode with --headed flag

Use `npx playwright test --headed` to run tests in headed mode. This gives the ability to visually see how Playwright interacts with the website as tests execute.

Run tests on specific browser with --project flag

Use `npx playwright test --project webkit` to run tests on a specific browser. To run on multiple browsers, use the --project flag multiple times: `npx playwright test --project webkit --project firefox`.

Run specific test file

To run a single test file, pass the test file name to the command: `npx playwright test landing-page.spec.ts`. To run test files from different directories, pass in the directory names: `npx playwright test tests/todo-page/ tests/landing-page/`.

Run tests matching keywords

To run files that have certain keywords in the file name, pass those keywords to the CLI: `npx playwright test landing login` will run files containing 'landing' or 'login'.

Run test with specific title using -g flag

Use the `-g` flag followed by the title of the test to run a test with a specific title: `npx playwright test -g "add a todo item"`.

Selenium Grid nodes must register with accessible address via SE_NODE_GRID_URL

When running distributed Selenium Grid, Playwright needs selenium nodes to be registered with an accessible address so it can connect to the browsers. Set the SE_NODE_GRID_URL environment variable pointing to the hub when running selenium nodes. Example: SE_NODE_GRID_URL="http://<selenium-hub-ip>:4444" java -jar selenium-server-<version>.jar node

Selenium Grid experimental feature status and risk

Playwright can connect to Selenium Grid Hub running Selenium 4 to launch Google Chrome or Microsoft Edge browsers instead of running browsers locally. This feature is experimental and prioritized accordingly. There is a risk that Playwright integration with Selenium Grid Hub may break in the future because Playwright internally connects to browsers using the Chrome DevTools Protocol websocket, which Selenium 4 currently exposes but may not in future versions.

Connect Playwright to Selenium Grid 4 with SELENIUM_REMOTE_URL

To connect Playwright to Selenium Grid 4, set the SELENIUM_REMOTE_URL environment variable pointing to your Selenium Grid Hub. This only works for Google Chrome and Microsoft Edge. No code changes are required; use your testing harness or BrowserType.launch as usual. Example: SELENIUM_REMOTE_URL=http://<selenium-hub-ip>:4444 npx playwright test

Pass additional capabilities to Selenium Grid via SELENIUM_REMOTE_CAPABILITIES

If your grid requires additional capabilities to be set (for example, when using an external service), set the SELENIUM_REMOTE_CAPABILITIES environment variable to provide JSON-serialized capabilities. Example: SELENIUM_REMOTE_CAPABILITIES="{'mygrid:options':{os:'windows',username:'John',password:'secure'}}"

Pass additional headers to Selenium Grid via SELENIUM_REMOTE_HEADERS

If your grid requires additional headers to be set (for example, to provide an authorization token for accessing browsers in your cloud), set the SELENIUM_REMOTE_HEADERS environment variable to provide JSON-serialized headers. Example: SELENIUM_REMOTE_HEADERS="{'Authorization':'Basic b64enc'}"

Selenium Grid standalone mode with Docker

To run Selenium Grid in standalone mode using Docker, start the standalone container with: docker run -d -p 4444:4444 --shm-size="2g" -e SE_NODE_GRID_URL="http://localhost:4444" selenium/standalone-chromium:latest. Then connect Playwright with: SELENIUM_REMOTE_URL=http://localhost:4444 npx playwright test

Selenium Grid hub and nodes mode with Docker

To run Selenium Grid in hub and nodes mode using Docker, first start the hub container: docker run -d -p 4442-4444:4442-4444 --name selenium-hub selenium/hub:4.25.0. Then start node containers with SE_NODE_GRID_URL pointing to the hub IP, for example: docker run -d -p 5555:5555 --shm-size="2g" -e SE_EVENT_BUS_HOST=<selenium-hub-ip> -e SE_EVENT_BUS_PUBLISH_PORT=4442 -e SE_EVENT_BUS_SUBSCRIBE_PORT=4443 -e SE_NODE_GRID_URL="http://<selenium-hub-ip>:4444" selenium/node-chromium:4.25.0. Then connect Playwright with: SELENIUM_REMOTE_URL=http://<selenium-hub-ip>:4444 npx playwright test

Selenium 3 support with Playwright is best-effort

Selenium 3 does not expose the Chrome DevTools Protocol websocket capability that Playwright requires. Selenium 3 is supported in a best-effort manner where Playwright tries to connect to the grid node directly. Grid nodes must be directly accessible from the machine that runs Playwright.

Verify Selenium Grid setup with Selenium WebDriver before using Playwright

Before connecting Playwright to your Selenium Grid, ensure the grid works with Selenium WebDriver. Run one of the Selenium WebDriver examples and pass the SELENIUM_REMOTE_URL environment variable. If the webdriver example does not work, check for errors at your Selenium hub/node/standalone output and search Selenium issues for a possible solution.

Run tests with either tag using logical OR

To run tests containing either tag (logical OR operator), use --grep with pipe syntax: npx playwright test --grep "@fast|@slow". On PowerShell use --grep --% "@fast^|@slow", on batch use --grep "@fast^|@slow".

Give your agent this brain