# THIS DOCUMENT CONTAINS THE COMPLETE DOCUMENTATION FOR PLAYWRIGHT NODEJS.
# Getting started - VS Code
Getting started - VS Code
=========================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
The Playwright VS Code extension brings the power of Playwright Test directly into your editor, allowing you to run, debug, and generate tests with a seamless UI-driven experience. This guide will walk you through setting up the extension and using its core features to supercharge your end-to-end testing workflow.
Prerequisites[](#prerequisites "Direct link to Prerequisites")
---------------------------------------------------------------
Before you begin, make sure you have the following installed:
* [Node.js](https://nodejs.org/) (LTS version recommended)
* [Visual Studio Code](https://code.visualstudio.com/)
Getting Started[](#getting-started "Direct link to Getting Started")
---------------------------------------------------------------------
### Installation & Setup[](#installation--setup "Direct link to Installation & Setup")
1. **Install the Extension**: Open the Extensions view in VS Code (`Ctrl+Shift+X` or `Cmd+Shift+X`) and search for "Playwright". [Install the official extension from Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
1. **Install Playwright**: Once the extension is installed, open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) and run the **Test: Install Playwright** command.
3. **Select Browsers**: Choose the browsers you want for your tests (e.g., Chromium, Firefox, WebKit). You can also add a GitHub Actions workflow to run tests in CI. These settings can be changed later in your `playwright.config.ts` file.
### Opening the Testing Sidebar[](#opening-the-testing-sidebar "Direct link to Opening the Testing Sidebar")
Click the **Testing icon** in the VS Code Activity Bar to open the Test Explorer. Here, you'll find your tests, as well as the Playwright sidebar for managing projects, tools, and settings.
Core Features[](#core-features "Direct link to Core Features")
---------------------------------------------------------------
### Running Your Tests[](#running-your-tests "Direct link to Running Your Tests")
* **Run a Single Test**: Click the green "play" icon next to any test to run it. The play button will change to a green checkmark if the test passes or a red X if the test fails. You'll be able to see how long the test took to run displayed next to the test name. Additionally, the Test Results panel will automatically open at the bottom of VS Code, showing a summary of the test execution including how many tests ran, how many passed, failed, or were skipped, along with the total execution time.
* **Run All Tests**: You can run all tests at different levels. Click the play icon next to a specific test file to run all tests within that file, or click the play icon at the very top of the Test Explorer to run all tests across your entire project.
* **Run on Multiple Browsers**: In the Playwright sidebar, check the boxes for the projects (browsers) you want to test against. Projects in Playwright represent different browser configurations - each project typically corresponds to a specific browser (like Chromium, Firefox, or WebKit) with its own settings such as viewport size, device emulation, or other browser-specific options. When you run a test, it will execute across all selected projects, allowing you to verify your application works consistently across different browsers and configurations.
* **Show Browser**: To watch your tests execute in a live browser window, enable the **Show Browser** option in the sidebar. Disable it to run in headless mode (where tests run in the background without opening a visible browser window).
### Debugging Your Tests[](#debugging-your-tests "Direct link to Debugging Your Tests")
The VS Code extension provides powerful debugging tools to help you identify and fix issues in your tests. You can set breakpoints, inspect variables, view detailed error messages, get AI-powered suggestions to resolve test failures, and use the comprehensive trace viewer to analyze test execution step-by-step.
* **Using Breakpoints**: Set a breakpoint by clicking in the gutter next to a line number. Right-click the test and select **Debug Test**. The test will pause at your breakpoint, allowing you to inspect variables and step through the code.
* **Live Debugging**: With **Show Browsers** enabled, click on a locator in your code. Playwright will highlight the corresponding element in the browser, making it easy to verify locators.
* **Viewing Error Messages**: If a test fails, the extension displays detailed error messages, including the expected vs. received values and a full call log, directly in the editor.
* **Fix with AI**: When a test fails, click the sparkle icon next to the error to get an AI-powered fix suggestion from Copilot. Copilot analyzes the error and suggests a code change to resolve the issue.
* **Debugging with Trace Viewer**: For comprehensive debugging, enable the **Show Trace Viewer** option in the Playwright sidebar. When your test finishes, a detailed trace will automatically open, providing you with a complete timeline of your test execution. The trace viewer is particularly useful for:
* **Step-by-step analysis**: Navigate through each action your test performed with precise timestamps
* **DOM inspection**: View DOM snapshots at any point during test execution to see exactly what the page looked like
* **Network monitoring**: Examine all network requests and responses that occurred during the test
* **Console logs**: Access all console messages and errors from the browser
* **Source mapping**: Jump directly to the source code that executed each action
* **Visual debugging**: See screenshots and understand what the user would have seen at each step
The trace viewer is especially valuable when debugging flaky tests or understanding complex user interactions.
To learn more, see our [Trace Viewer guide](/docs/trace-viewer).
### Generating Tests with CodeGen[](#generating-tests-with-codegen "Direct link to Generating Tests with CodeGen")
CodeGen is Playwright's powerful test generation tool that automatically creates test code by recording your interactions with a web page. Instead of writing tests from scratch, you can simply navigate through your application while CodeGen captures your actions and converts them into reliable test code with proper locators and assertions.
* **Record a New Test**: Click **Record new** in the sidebar. A browser window will open. As you interact with the page, Playwright will automatically generate the test code. You can also generate assertions from the recording toolbar.
* **Record at Cursor**: Place your cursor inside an existing test and click **Record at cursor** to add new actions at that specific point. 
* **Pick a Locator**: Use the **Pick locator** tool to click on any element in the opened browser. Playwright will determine the best locator and copy it to your clipboard, ready to be pasted into your code.
To learn more, see our [CodeGen guide](/docs/codegen).
Advanced Features[](#advanced-features "Direct link to Advanced Features")
---------------------------------------------------------------------------
### Project Dependencies[](#project-dependencies "Direct link to Project Dependencies")
Use [project dependencies](/docs/test-projects) to define setup tests that run before other tests. For example, you can create a login test that runs first, then reuse that authenticated state across multiple tests without having to log in again for each test. In VS Code, you can see these setup tests in the Test Explorer and run them independently when needed.
To learn more, see our [Project Dependencies guide](/docs/test-projects).
### Global Setup[](#global-setup "Direct link to Global Setup")
For tasks that need to run only once before all tests (like seeding a database), use **Global Setup**. You can trigger the global setup and teardown manually from the Playwright sidebar.
### Multiple Configurations[](#multiple-configurations "Direct link to Multiple Configurations")
If you have multiple `playwright.config.ts` files, you can switch between them using the gear icon in the Playwright sidebar. This allows you to easily work with different test suites or environments.
Quick Reference[](#quick-reference "Direct link to Quick Reference")
---------------------------------------------------------------------
Action
How to do it in VS Code
**Install Playwright**
Command Palette → `Test: Install Playwright`
**Run a Test**
Click the "play" icon next to the test
**Debug a Test**
Set a breakpoint, right-click the test → `Debug Test`
**Show Live Browser**
Enable `Show Browsers` in the Playwright sidebar
**Record a New Test**
Click `Record new` in the Playwright sidebar
**Pick a Locator**
Click `Pick locator` in the Playwright sidebar
**View Test Trace**
Enable `Show Trace Viewer` in the Playwright sidebar
What's Next[](#whats-next "Direct link to What's Next")
--------------------------------------------------------
* [Write tests using web-first assertions, page fixtures, and locators](/docs/writing-tests)
* [Run your tests on CI](/docs/ci-intro)
* [Learn more about the Trace Viewer](/docs/trace-viewer)
# Release notes
Release notes
=============
Version 1.56[](#version-156 "Direct link to Version 1.56")
-----------------------------------------------------------
### Playwright Test Agents[](#playwright-test-agents "Direct link to Playwright Test Agents")
Introducing Playwright Test Agents, three custom agent definitions designed to guide LLMs through the core process of building a Playwright test:
* **🎭 planner** explores the app and produces a Markdown test plan
* **🎭 generator** transforms the Markdown plan into the Playwright Test files
* **🎭 healer** executes the test suite and automatically repairs failing tests
Run `npx playwright init-agents` with your client of choice to generate the latest agent definitions:
# Generate agent files for each agentic loop# Visual Studio Codenpx playwright init-agents --loop=vscode# Claude Codenpx playwright init-agents --loop=claude# opencodenpx playwright init-agents --loop=opencode
[Learn more about Playwright Test Agents](/docs/test-agents)
### New APIs[](#new-apis "Direct link to New APIs")
* New methods [page.consoleMessages()](/docs/api/class-page#page-console-messages) and [page.pageErrors()](/docs/api/class-page#page-page-errors) for retrieving the most recent console messages from the page
* New method [page.requests()](/docs/api/class-page#page-requests) for retrieving the most recent network requests from the page
* Added [`--test-list` and `--test-list-invert`](/docs/test-cli#test-list) to allow manual specification of specific tests from a file
### UI Mode and HTML Reporter[](#ui-mode-and-html-reporter "Direct link to UI Mode and HTML Reporter")
* Added option to `'html'` reporter to disable the "Copy prompt" button
* Added option to `'html'` reporter and UI Mode to merge files, collapsing test and describe blocks into a single unified list
* Added option to UI Mode mirroring the `--update-snapshots` options
* Added option to UI Mode to run only a single worker at a time
### Breaking Changes[](#breaking-changes "Direct link to Breaking Changes")
* Event [browserContext.on('backgroundpage')](/docs/api/class-browsercontext#browser-context-event-background-page) has been deprecated and will not be emitted. Method [browserContext.backgroundPages()](/docs/api/class-browsercontext#browser-context-background-pages) will return an empty list
### Miscellaneous[](#miscellaneous "Direct link to Miscellaneous")
* Aria snapshots render and compare `input` `placeholder`
* Added environment variable `PLAYWRIGHT_TEST` to Playwright worker processes to allow discriminating on testing status
### Browser Versions[](#browser-versions "Direct link to Browser Versions")
* Chromium 141.0.7390.37
* Mozilla Firefox 142.0.1
* WebKit 26.0
Version 1.55[](#version-155 "Direct link to Version 1.55")
-----------------------------------------------------------
### New APIs[](#new-apis-1 "Direct link to New APIs")
* New Property [testStepInfo.titlePath](/docs/api/class-teststepinfo#test-step-info-title-path) Returns the full title path starting from the test file, including test and step titles.
### Codegen[](#codegen "Direct link to Codegen")
* Automatic `toBeVisible()` assertions: Codegen can now generate automatic `toBeVisible()` assertions for common UI interactions. This feature can be enabled in the Codegen settings UI.
### Breaking Changes[](#breaking-changes-1 "Direct link to Breaking Changes")
* ⚠️ Dropped support for Chromium extension manifest v2.
### Miscellaneous[](#miscellaneous-1 "Direct link to Miscellaneous")
* Added support for Debian 13 "Trixie".
### Browser Versions[](#browser-versions-1 "Direct link to Browser Versions")
* Chromium 140.0.7339.16
* Mozilla Firefox 141.0
* WebKit 26.0
This version was also tested against the following stable channels:
* Google Chrome 139
* Microsoft Edge 139
Version 1.54[](#version-154 "Direct link to Version 1.54")
-----------------------------------------------------------
### Highlights[](#highlights "Direct link to Highlights")
* New cookie property `partitionKey` in [browserContext.cookies()](/docs/api/class-browsercontext#browser-context-cookies) and [browserContext.addCookies()](/docs/api/class-browsercontext#browser-context-add-cookies). This property allows to save and restore partitioned cookies. See [CHIPS MDN article](https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies) for more information. Note that browsers have different support and defaults for cookie partitioning.
* New option `noSnippets` to disable code snippets in the html report.
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { noSnippets: true }]]});
* New property `location` in test annotations, for example in [testResult.annotations](/docs/api/class-testresult#test-result-annotations) and [testInfo.annotations](/docs/api/class-testinfo#test-info-annotations). It shows where the annotation like `test.skip` or `test.fixme` was added.
### Command Line[](#command-line "Direct link to Command Line")
* New option `--user-data-dir` in multiple commands. You can specify the same user data dir to reuse browsing state, like authentication, between sessions.
npx playwright codegen --user-data-dir=./user-data
* Option `-gv` has been removed from the `npx playwright test` command. Use `--grep-invert` instead.
* `npx playwright open` does not open the test recorder anymore. Use `npx playwright codegen` instead.
### Miscellaneous[](#miscellaneous-2 "Direct link to Miscellaneous")
* Support for Node.js 16 has been removed.
* Support for Node.js 18 has been deprecated, and will be removed in the future.
### Browser Versions[](#browser-versions-2 "Direct link to Browser Versions")
* Chromium 139.0.7258.5
* Mozilla Firefox 140.0.2
* WebKit 26.0
This version was also tested against the following stable channels:
* Google Chrome 140
* Microsoft Edge 140
Version 1.53[](#version-153 "Direct link to Version 1.53")
-----------------------------------------------------------
### Trace Viewer and HTML Reporter Updates[](#trace-viewer-and-html-reporter-updates "Direct link to Trace Viewer and HTML Reporter Updates")
* New Steps in Trace Viewer and HTML reporter: 
* New option in `'html'` reporter to set the title of a specific test run:
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { title: 'Custom test run #1028' }]]});
### Miscellaneous[](#miscellaneous-3 "Direct link to Miscellaneous")
* New option [kind](/docs/api/class-testinfo#test-info-snapshot-path-option-kind) in [testInfo.snapshotPath()](/docs/api/class-testinfo#test-info-snapshot-path) controls which snapshot path template is used.
* New method [locator.describe()](/docs/api/class-locator#locator-describe) to describe a locator. Used for trace viewer and reports.
const button = page.getByTestId('btn-sub').describe('Subscribe button');await button.click();
* `npx playwright install --list` will now list all installed browsers, versions and locations.
### Browser Versions[](#browser-versions-3 "Direct link to Browser Versions")
* Chromium 138.0.7204.4
* Mozilla Firefox 139.0
* WebKit 18.5
This version was also tested against the following stable channels:
* Google Chrome 137
* Microsoft Edge 137
Version 1.52[](#version-152 "Direct link to Version 1.52")
-----------------------------------------------------------
### Highlights[](#highlights-1 "Direct link to Highlights")
* New method [expect(locator).toContainClass()](/docs/api/class-locatorassertions#locator-assertions-to-contain-class) to ergonomically assert individual class names on the element.
await expect(page.getByRole('listitem', { name: 'Ship v1.52' })).toContainClass('done');
* [Aria Snapshots](/docs/aria-snapshots) got two new properties: [`/children`](/docs/aria-snapshots#strict-matching) for strict matching and `/url` for links.
await expect(locator).toMatchAriaSnapshot(` - list - /children: equal - listitem: Feature A - listitem: - link "Feature B": - /url: "https://playwright.dev"`);
### Test Runner[](#test-runner "Direct link to Test Runner")
* New property [testProject.workers](/docs/api/class-testproject#test-project-workers) allows to specify the number of concurrent worker processes to use for a test project. The global limit of property [testConfig.workers](/docs/api/class-testconfig#test-config-workers) still applies.
* New [testConfig.failOnFlakyTests](/docs/api/class-testconfig#test-config-fail-on-flaky-tests) option to fail the test run if any flaky tests are detected, similarly to `--fail-on-flaky-tests`. This is useful for CI/CD environments where you want to ensure that all tests are stable before deploying.
* New property [testResult.annotations](/docs/api/class-testresult#test-result-annotations) contains annotations for each test retry.
### Miscellaneous[](#miscellaneous-4 "Direct link to Miscellaneous")
* New option [maxRedirects](/docs/api/class-apirequest#api-request-new-context-option-max-redirects) in [apiRequest.newContext()](/docs/api/class-apirequest#api-request-new-context) to control the maximum number of redirects.
* HTML reporter now supports _NOT filtering_ via `!@my-tag` or `!my-file.spec.ts` or `!p:my-project`.
### Breaking Changes[](#breaking-changes-2 "Direct link to Breaking Changes")
* Glob URL patterns in methods like [page.route()](/docs/api/class-page#page-route) do not support `?` and `[]` anymore. We recommend using regular expressions instead.
* Method [route.continue()](/docs/api/class-route#route-continue) does not allow to override the `Cookie` header anymore. If a `Cookie` header is provided, it will be ignored, and the cookie will be loaded from the browser's cookie store. To set custom cookies, use [browserContext.addCookies()](/docs/api/class-browsercontext#browser-context-add-cookies).
* macOS 13 is now deprecated and will no longer receive WebKit updates. Please upgrade to a more recent macOS version to continue benefiting from the latest WebKit improvements.
### Browser Versions[](#browser-versions-4 "Direct link to Browser Versions")
* Chromium 136.0.7103.25
* Mozilla Firefox 137.0
* WebKit 18.4
This version was also tested against the following stable channels:
* Google Chrome 135
* Microsoft Edge 135
Version 1.51[](#version-151 "Direct link to Version 1.51")
-----------------------------------------------------------
### StorageState for indexedDB[](#storagestate-for-indexeddb "Direct link to StorageState for indexedDB")
* New option [indexedDB](/docs/api/class-browsercontext#browser-context-storage-state-option-indexed-db) for [browserContext.storageState()](/docs/api/class-browsercontext#browser-context-storage-state) allows to save and restore IndexedDB contents. Useful when your application uses [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) to store authentication tokens, like Firebase Authentication.
Here is an example following the [authentication guide](/docs/auth#basic-shared-account-in-all-tests):
tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';import path from 'path';const authFile = path.join(__dirname, '../playwright/.auth/user.json');setup('authenticate', async ({ page }) => { await page.goto('/'); // ... perform authentication steps ... // make sure to save indexedDB await page.context().storageState({ path: authFile, indexedDB: true });});
### Copy as prompt[](#copy-as-prompt "Direct link to Copy as prompt")
New "Copy prompt" button on errors in the HTML report, trace viewer and UI mode. Click to copy a pre-filled LLM prompt that contains the error message and useful context for fixing the error.
### Filter visible elements[](#filter-visible-elements "Direct link to Filter visible elements")
New option [visible](/docs/api/class-locator#locator-filter-option-visible) for [locator.filter()](/docs/api/class-locator#locator-filter) allows matching only visible elements.
example.spec.ts
test('some test', async ({ page }) => { // Ignore invisible todo items. const todoItems = page.getByTestId('todo-item').filter({ visible: true }); // Check there are exactly 3 visible ones. await expect(todoItems).toHaveCount(3);});
### Git information in HTML report[](#git-information-in-html-report "Direct link to Git information in HTML report")
Set option [testConfig.captureGitInfo](/docs/api/class-testconfig#test-config-capture-git-info) to capture git information into [testConfig.metadata](/docs/api/class-testconfig#test-config-metadata).
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ captureGitInfo: { commit: true, diff: true }});
HTML report will show this information when available:
### Test Step improvements[](#test-step-improvements "Direct link to Test Step improvements")
A new [TestStepInfo](/docs/api/class-teststepinfo "TestStepInfo") object is now available in test steps. You can add step attachments or skip the step under some conditions.
test('some test', async ({ page, isMobile }) => { // Note the new "step" argument: await test.step('here is my step', async step => { step.skip(isMobile, 'not relevant on mobile layouts'); // ... await step.attach('my attachment', { body: 'some text' }); // ... });});
### Miscellaneous[](#miscellaneous-5 "Direct link to Miscellaneous")
* New option `contrast` for methods [page.emulateMedia()](/docs/api/class-page#page-emulate-media) and [browser.newContext()](/docs/api/class-browser#browser-new-context) allows to emulate the `prefers-contrast` media feature.
* New option [failOnStatusCode](/docs/api/class-apirequest#api-request-new-context-option-fail-on-status-code) makes all fetch requests made through the [APIRequestContext](/docs/api/class-apirequestcontext "APIRequestContext") throw on response codes other than 2xx and 3xx.
* Assertion [expect(page).toHaveURL()](/docs/api/class-pageassertions#page-assertions-to-have-url) now supports a predicate.
### Browser Versions[](#browser-versions-5 "Direct link to Browser Versions")
* Chromium 134.0.6998.35
* Mozilla Firefox 135.0
* WebKit 18.4
This version was also tested against the following stable channels:
* Google Chrome 133
* Microsoft Edge 133
Version 1.50[](#version-150 "Direct link to Version 1.50")
-----------------------------------------------------------
### Test runner[](#test-runner-1 "Direct link to Test runner")
* New option [timeout](/docs/api/class-test#test-step-option-timeout) allows specifying a maximum run time for an individual test step. A timed-out step will fail the execution of the test.
test('some test', async ({ page }) => { await test.step('a step', async () => { // This step can time out separately from the test }, { timeout: 1000 });});
* New method [test.step.skip()](/docs/api/class-test#test-step-skip) to disable execution of a test step.
test('some test', async ({ page }) => { await test.step('before running step', async () => { // Normal step }); await test.step.skip('not yet ready', async () => { // This step is skipped }); await test.step('after running step', async () => { // This step still runs even though the previous one was skipped });});
* Expanded [expect(locator).toMatchAriaSnapshot()](/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot-2) to allow storing of aria snapshots in separate YAML files.
* Added method [expect(locator).toHaveAccessibleErrorMessage()](/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message) to assert the Locator points to an element with a given [aria errormessage](https://w3c.github.io/aria/#aria-errormessage).
* Option [testConfig.updateSnapshots](/docs/api/class-testconfig#test-config-update-snapshots) added the configuration enum `changed`. `changed` updates only the snapshots that have changed, whereas `all` now updates all snapshots, regardless of whether there are any differences.
* New option [testConfig.updateSourceMethod](/docs/api/class-testconfig#test-config-update-source-method) defines the way source code is updated when [testConfig.updateSnapshots](/docs/api/class-testconfig#test-config-update-snapshots) is configured. Added `overwrite` and `3-way` modes that write the changes into source code, on top of existing `patch` mode that creates a patch file.
npx playwright test --update-snapshots=changed --update-source-method=3way
* Option [testConfig.webServer](/docs/api/class-testconfig#test-config-web-server) added a `gracefulShutdown` field for specifying a process kill signal other than the default `SIGKILL`.
* Exposed [testStep.attachments](/docs/api/class-teststep#test-step-attachments) from the reporter API to allow retrieval of all attachments created by that step.
* New option `pathTemplate` for `toHaveScreenshot` and `toMatchAriaSnapshot` assertions in the [testConfig.expect](/docs/api/class-testconfig#test-config-expect) configuration.
### UI updates[](#ui-updates "Direct link to UI updates")
* Updated default HTML reporter to improve display of attachments.
* New button in Codegen for picking elements to produce aria snapshots.
* Additional details (such as keys pressed) are now displayed alongside action API calls in traces.
* Display of `canvas` content in traces is error-prone. Display is now disabled by default, and can be enabled via the `Display canvas content` UI setting.
* `Call` and `Network` panels now display additional time information.
### Breaking[](#breaking "Direct link to Breaking")
* [expect(locator).toBeEditable()](/docs/api/class-locatorassertions#locator-assertions-to-be-editable) and [locator.isEditable()](/docs/api/class-locator#locator-is-editable) now throw if the target element is not ``, or a number of other editable elements.
* Option [testConfig.updateSnapshots](/docs/api/class-testconfig#test-config-update-snapshots) now updates all snapshots when set to `all`, rather than only the failed/changed snapshots. Use the new enum `changed` to keep the old functionality of only updating the changed snapshots.
### Browser Versions[](#browser-versions-6 "Direct link to Browser Versions")
* Chromium 133.0.6943.16
* Mozilla Firefox 134.0
* WebKit 18.2
This version was also tested against the following stable channels:
* Google Chrome 132
* Microsoft Edge 132
Version 1.49[](#version-149 "Direct link to Version 1.49")
-----------------------------------------------------------
### Aria snapshots[](#aria-snapshots "Direct link to Aria snapshots")
New assertion [expect(locator).toMatchAriaSnapshot()](/docs/api/class-locatorassertions#locator-assertions-to-match-aria-snapshot) verifies page structure by comparing to an expected accessibility tree, represented as YAML.
await page.goto('https://playwright.dev');await expect(page.locator('body')).toMatchAriaSnapshot(` - banner: - heading /Playwright enables reliable/ [level=1] - link "Get started" - link "Star microsoft/playwright on GitHub" - main: - img "Browsers (Chromium, Firefox, WebKit)" - heading "Any browser • Any platform • One API"`);
You can generate this assertion with [Test Generator](/docs/codegen) and update the expected snapshot with `--update-snapshots` command line flag.
Learn more in the [aria snapshots guide](/docs/aria-snapshots).
### Test runner[](#test-runner-2 "Direct link to Test runner")
* New option [testConfig.tsconfig](/docs/api/class-testconfig#test-config-tsconfig) allows to specify a single `tsconfig` to be used for all tests.
* New method [test.fail.only()](/docs/api/class-test#test-fail-only) to focus on a failing test.
* Options [testConfig.globalSetup](/docs/api/class-testconfig#test-config-global-setup) and [testConfig.globalTeardown](/docs/api/class-testconfig#test-config-global-teardown) now support multiple setups/teardowns.
* New value `'on-first-failure'` for [testOptions.screenshot](/docs/api/class-testoptions#test-options-screenshot).
* Added "previous" and "next" buttons to the HTML report to quickly switch between test cases.
* New properties [testInfoError.cause](/docs/api/class-testinfoerror#test-info-error-cause) and [testError.cause](/docs/api/class-testerror#test-error-cause) mirroring [`Error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause).
### Breaking: `chrome` and `msedge` channels switch to new headless mode[](#breaking-chrome-and-msedge-channels-switch-to-new-headless-mode "Direct link to breaking-chrome-and-msedge-channels-switch-to-new-headless-mode")
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`
#### What do I need to do?[](#what-do-i-need-to-do "Direct link to What do I need to do?")
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.
### Other breaking changes[](#other-breaking-changes "Direct link to 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.
### Try new Chromium headless[](#try-new-chromium-headless "Direct link to Try new Chromium headless")
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 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.
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'], channel: 'chromium' }, }, ],});
### Miscellaneous[](#miscellaneous-6 "Direct link to Miscellaneous")
* `` elements inside a snapshot now draw a preview.
* New method [tracing.group()](/docs/api/class-tracing#tracing-group) to visually group actions in the trace.
* Playwright docker images switched from Node.js v20 to Node.js v22 LTS.
### Browser Versions[](#browser-versions-7 "Direct link to Browser Versions")
* Chromium 131.0.6778.33
* Mozilla Firefox 132.0
* WebKit 18.2
This version was also tested against the following stable channels:
* Google Chrome 130
* Microsoft Edge 130
Version 1.48[](#version-148 "Direct link to Version 1.48")
-----------------------------------------------------------
### WebSocket routing[](#websocket-routing "Direct link to WebSocket routing")
New methods [page.routeWebSocket()](/docs/api/class-page#page-route-web-socket) and [browserContext.routeWebSocket()](/docs/api/class-browsercontext#browser-context-route-web-socket) allow to intercept, modify and mock WebSocket connections initiated in the page. Below is a simple example that mocks WebSocket communication by responding to a `"request"` with a `"response"`.
await page.routeWebSocket('/ws', ws => { ws.onMessage(message => { if (message === 'request') ws.send('response'); });});
See [WebSocketRoute](/docs/api/class-websocketroute "WebSocketRoute") for more details.
### UI updates[](#ui-updates-1 "Direct link to UI updates")
* New "copy" buttons for annotations and test location in the HTML report.
* Route method calls like [route.fulfill()](/docs/api/class-route#route-fulfill) are not shown in the report and trace viewer anymore. You can see which network requests were routed in the network tab instead.
* New "Copy as cURL" and "Copy as fetch" buttons for requests in the network tab.
### Miscellaneous[](#miscellaneous-7 "Direct link to Miscellaneous")
* Option [form](/docs/api/class-apirequestcontext#api-request-context-fetch-option-form) and similar ones now accept [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
* New method [page.requestGC()](/docs/api/class-page#page-request-gc) may help detect memory leaks.
* New option [location](/docs/api/class-test#test-step-option-location) to pass custom step location.
* Requests made by [APIRequestContext](/docs/api/class-apirequestcontext "APIRequestContext") now record detailed timing and security information in the HAR.
### Browser Versions[](#browser-versions-8 "Direct link to Browser Versions")
* Chromium 130.0.6723.19
* Mozilla Firefox 130.0
* WebKit 18.0
This version was also tested against the following stable channels:
* Google Chrome 129
* Microsoft Edge 129
Version 1.47[](#version-147 "Direct link to Version 1.47")
-----------------------------------------------------------
### Network Tab improvements[](#network-tab-improvements "Direct link to Network Tab improvements")
The Network tab in the UI mode and trace viewer has several nice improvements:
* filtering by asset type and URL
* better display of query string parameters
* preview of font assets
### `--tsconfig` CLI option[](#--tsconfig-cli-option "Direct link to --tsconfig-cli-option")
By default, Playwright will look up the closest tsconfig for each imported file using a heuristic. You can now specify a single tsconfig file in the command line, and Playwright will use it for all imported files, not only test files:
# Pass a specific tsconfignpx playwright test --tsconfig tsconfig.test.json
### [APIRequestContext](/docs/api/class-apirequestcontext "APIRequestContext") now accepts [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) and `string` as query parameters[](#apirequestcontext-now-accepts-urlsearchparams-and-string-as-query-parameters "Direct link to apirequestcontext-now-accepts-urlsearchparams-and-string-as-query-parameters")
You can now pass [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) and `string` as query parameters to [APIRequestContext](/docs/api/class-apirequestcontext "APIRequestContext"):
test('query params', async ({ request }) => { const searchParams = new URLSearchParams(); searchParams.set('userId', 1); const response = await request.get( 'https://jsonplaceholder.typicode.com/posts', { params: searchParams // or as a string: 'userId=1' } ); // ...});
### Miscellaneous[](#miscellaneous-8 "Direct link to Miscellaneous")
* The `mcr.microsoft.com/playwright:v1.47.0` now serves a Playwright image based on Ubuntu 24.04 Noble. To use the 22.04 jammy-based image, please use `mcr.microsoft.com/playwright:v1.47.0-jammy` instead.
* New options [behavior](/docs/api/class-page#page-remove-all-listeners-option-behavior), [behavior](/docs/api/class-browser#browser-remove-all-listeners-option-behavior) and [behavior](/docs/api/class-browsercontext#browser-context-remove-all-listeners-option-behavior) to wait for ongoing listeners to complete.
* TLS client certificates can now be passed from memory by passing [clientCertificates.cert](/docs/api/class-browser#browser-new-context-option-client-certificates) and [clientCertificates.key](/docs/api/class-browser#browser-new-context-option-client-certificates) as buffers instead of file paths.
* Attachments with a `text/html` content type can now be opened in a new tab in the HTML report. This is useful for including third-party reports or other HTML content in the Playwright test report and distributing it to your team.
* [noWaitAfter](/docs/api/class-locator#locator-select-option-option-no-wait-after) option in [locator.selectOption()](/docs/api/class-locator#locator-select-option) was deprecated.
* We've seen reports of WebGL in Webkit misbehaving on GitHub Actions `macos-13`. We recommend upgrading GitHub Actions to `macos-14`.
### Browser Versions[](#browser-versions-9 "Direct link to Browser Versions")
* Chromium 129.0.6668.29
* Mozilla Firefox 130.0
* WebKit 18.0
This version was also tested against the following stable channels:
* Google Chrome 128
* Microsoft Edge 128
Version 1.46[](#version-146 "Direct link to Version 1.46")
-----------------------------------------------------------
### TLS Client Certificates[](#tls-client-certificates "Direct link to TLS Client Certificates")
Playwright now allows you to supply client-side certificates, so that server can verify them, as specified by TLS Client Authentication.
The following snippet sets up a client certificate for `https://example.com`:
import { defineConfig } from '@playwright/test';export default defineConfig({ // ... use: { clientCertificates: [{ origin: 'https://example.com', certPath: './cert.pem', keyPath: './key.pem', passphrase: 'mysecretpassword', }], }, // ...});
You can also provide client certificates to a particular [test project](/docs/api/class-testproject#test-project-use) or as a parameter of [browser.newContext()](/docs/api/class-browser#browser-new-context) and [apiRequest.newContext()](/docs/api/class-apirequest#api-request-new-context).
### `--only-changed` cli option[](#--only-changed-cli-option "Direct link to --only-changed-cli-option")
New CLI option `--only-changed` will only run test files that have been changed since the last git commit or from a specific git "ref". This will also run all test files that import any changed files.
# Only run test files with uncommitted changesnpx playwright test --only-changed# Only run test files changed relative to the "main" branchnpx playwright test --only-changed=main
### Component Testing: New `router` fixture[](#component-testing-new-router-fixture "Direct link to component-testing-new-router-fixture")
This release introduces an experimental `router` fixture to intercept and handle network requests in component testing. There are two ways to use the router fixture:
* Call `router.route(url, handler)` that behaves similarly to [page.route()](/docs/api/class-page#page-route).
* Call `router.use(handlers)` and pass [MSW library](https://mswjs.io) request handlers to it.
Here is an example of reusing your existing MSW handlers in the test.
import { handlers } from '@src/mocks/handlers';test.beforeEach(async ({ router }) => { // install common handlers before each test await router.use(...handlers);});test('example test', async ({ mount }) => { // test as usual, your handlers are active // ...});
This fixture is only available in [component tests](/docs/test-components#handling-network-requests).
### UI Mode / Trace Viewer Updates[](#ui-mode--trace-viewer-updates "Direct link to UI Mode / Trace Viewer Updates")
* Test annotations are now shown in UI mode.
* Content of text attachments is now rendered inline in the attachments pane.
* New setting to show/hide routing actions like [route.continue()](/docs/api/class-route#route-continue).
* Request method and status are shown in the network details tab.
* New button to copy source file location to clipboard.
* Metadata pane now displays the `baseURL`.
### Miscellaneous[](#miscellaneous-9 "Direct link to Miscellaneous")
* New `maxRetries` option in [apiRequestContext.fetch()](/docs/api/class-apirequestcontext#api-request-context-fetch) which retries on the `ECONNRESET` network error.
* New option to [box a fixture](/docs/test-fixtures#box-fixtures) to minimize the fixture exposure in test reports and error messages.
* New option to provide a [custom fixture title](/docs/test-fixtures#custom-fixture-title) to be used in test reports and error messages.
### Browser Versions[](#browser-versions-10 "Direct link to Browser Versions")
* Chromium 128.0.6613.18
* Mozilla Firefox 128.0
* WebKit 18.0
This version was also tested against the following stable channels:
* Google Chrome 127
* Microsoft Edge 127
Version 1.45[](#version-145 "Direct link to Version 1.45")
-----------------------------------------------------------
### Clock[](#clock "Direct link to Clock")
Utilizing the new [Clock](/docs/api/class-clock "Clock") API allows to manipulate and control time within tests to verify time-related behavior. This API covers many common scenarios, including:
* testing with predefined time;
* keeping consistent time and timers;
* monitoring inactivity;
* ticking through time manually.
// Initialize clock and let the page load naturally.await page.clock.install({ time: new Date('2024-02-02T08:00:00') });await page.goto('http://localhost:3333');// Pretend that the user closed the laptop lid and opened it again at 10am,// Pause the time once reached that point.await page.clock.pauseAt(new Date('2024-02-02T10:00:00'));// Assert the page state.await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:00:00 AM');// Close the laptop lid again and open it at 10:30am.await page.clock.fastForward('30:00');await expect(page.getByTestId('current-time')).toHaveText('2/2/2024, 10:30:00 AM');
See [the clock guide](/docs/clock) for more details.
### Test runner[](#test-runner-3 "Direct link to Test runner")
* New CLI option `--fail-on-flaky-tests` that sets exit code to `1` upon any flaky tests. Note that by default, the test runner exits with code `0` when all failed tests recovered upon a retry. With this option, the test run will fail in such case.
* New environment variable `PLAYWRIGHT_FORCE_TTY` controls whether built-in `list`, `line` and `dot` reporters assume a live terminal. For example, this could be useful to disable tty behavior when your CI environment does not handle ANSI control sequences well. Alternatively, you can enable tty behavior even when to live terminal is present, if you plan to post-process the output and handle control sequences.
# Avoid TTY features that output ANSI control sequencesPLAYWRIGHT_FORCE_TTY=0 npx playwright test# Enable TTY features, assuming a terminal width 80PLAYWRIGHT_FORCE_TTY=80 npx playwright test
* New options [testConfig.respectGitIgnore](/docs/api/class-testconfig#test-config-respect-git-ignore) and [testProject.respectGitIgnore](/docs/api/class-testproject#test-project-respect-git-ignore) control whether files matching `.gitignore` patterns are excluded when searching for tests.
* New property `timeout` is now available for custom expect matchers. This property takes into account `playwright.config.ts` and `expect.configure()`.
import { expect as baseExpect } from '@playwright/test';export const expect = baseExpect.extend({ async toHaveAmount(locator: Locator, expected: number, options?: { timeout?: number }) { // When no timeout option is specified, use the config timeout. const timeout = options?.timeout ?? this.timeout; // ... implement the assertion ... },});
### Miscellaneous[](#miscellaneous-10 "Direct link to Miscellaneous")
* Method [locator.setInputFiles()](/docs/api/class-locator#locator-set-input-files) now supports uploading a directory for ` Red Green Blue
await element.selectOption('Red');
* Retry blocks of code until all assertions pass:
await expect(async () => { const response = await page.request.get('https://api.example.com'); await expect(response).toBeOK();}).toPass();
Read more in [our documentation](/docs/test-assertions#expecttopass).
* Automatically capture **full page screenshot** on test failure:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { screenshot: { mode: 'only-on-failure', fullPage: true, } }});
### Miscellaneous[](#miscellaneous-12 "Direct link to Miscellaneous")
* Playwright Test now respects [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig).
* New options `args` and `proxy` for [androidDevice.launchBrowser()](/docs/api/class-androiddevice#android-device-launch-browser).
* Option `postData` in method [route.continue()](/docs/api/class-route#route-continue) now supports [Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable") values.
### Browser Versions[](#browser-versions-27 "Direct link to Browser Versions")
* Chromium 109.0.5414.46
* Mozilla Firefox 107.0
* WebKit 16.4
This version was also tested against the following stable channels:
* Google Chrome 108
* Microsoft Edge 108
Version 1.28[](#version-128 "Direct link to Version 1.28")
-----------------------------------------------------------
### Playwright Tools[](#playwright-tools "Direct link to Playwright Tools")
* **Record at Cursor in VSCode.** You can run the test, position the cursor at the end of the test and continue generating the test.
* **Live Locators in VSCode.** You can hover and edit locators in VSCode to get them highlighted in the opened browser.
* **Live Locators in CodeGen.** Generate a locator for any element on the page using "Explore" tool.
* **Codegen and Trace Viewer Dark Theme.** Automatically picked up from operating system settings.
### Test Runner[](#test-runner-4 "Direct link to Test Runner")
* Configure retries and test timeout for a file or a test with [test.describe.configure()](/docs/api/class-test#test-describe-configure).
// Each test in the file will be retried twice and have a timeout of 20 seconds.test.describe.configure({ retries: 2, timeout: 20_000 });test('runs first', async ({ page }) => {});test('runs second', async ({ page }) => {});
* Use [testProject.snapshotPathTemplate](/docs/api/class-testproject#test-project-snapshot-path-template) and [testConfig.snapshotPathTemplate](/docs/api/class-testconfig#test-config-snapshot-path-template) to configure a template controlling location of snapshots generated by [expect(page).toHaveScreenshot()](/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) and [expect(value).toMatchSnapshot()](/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1).
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ testDir: './tests', snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',});
### New APIs[](#new-apis-13 "Direct link to New APIs")
* [locator.blur()](/docs/api/class-locator#locator-blur)
* [locator.clear()](/docs/api/class-locator#locator-clear)
* [android.launchServer()](/docs/api/class-android#android-launch-server) and [android.connect()](/docs/api/class-android#android-connect)
* [androidDevice.on('close')](/docs/api/class-androiddevice#android-device-event-close)
### Browser Versions[](#browser-versions-28 "Direct link to Browser Versions")
* Chromium 108.0.5359.29
* Mozilla Firefox 106.0
* WebKit 16.4
This version was also tested against the following stable channels:
* Google Chrome 107
* Microsoft Edge 107
Version 1.27[](#version-127 "Direct link to Version 1.27")
-----------------------------------------------------------
### Locators[](#locators "Direct link to Locators")
With these new APIs writing locators is a joy:
* [page.getByText()](/docs/api/class-page#page-get-by-text) to locate by text content.
* [page.getByRole()](/docs/api/class-page#page-get-by-role) to locate by [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
* [page.getByLabel()](/docs/api/class-page#page-get-by-label) to locate a form control by associated label's text.
* [page.getByTestId()](/docs/api/class-page#page-get-by-test-id) to locate an element based on its `data-testid` attribute (other attribute can be configured).
* [page.getByPlaceholder()](/docs/api/class-page#page-get-by-placeholder) to locate an input by placeholder.
* [page.getByAltText()](/docs/api/class-page#page-get-by-alt-text) to locate an element, usually image, by its text alternative.
* [page.getByTitle()](/docs/api/class-page#page-get-by-title) to locate an element by its title.
await page.getByLabel('User Name').fill('John');await page.getByLabel('Password').fill('secret-password');await page.getByRole('button', { name: 'Sign in' }).click();await expect(page.getByText('Welcome, John!')).toBeVisible();
All the same methods are also available on [Locator](/docs/api/class-locator "Locator"), [FrameLocator](/docs/api/class-framelocator "FrameLocator") and [Frame](/docs/api/class-frame "Frame") classes.
### Other highlights[](#other-highlights "Direct link to Other highlights")
* `workers` option in the `playwright.config.ts` now accepts a percentage string to use some of the available CPUs. You can also pass it in the command line:
npx playwright test --workers=20%
* New options `host` and `port` for the html reporter.
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { host: 'localhost', port: '9223' }]],});
* New field `FullConfig.configFile` is available to test reporters, specifying the path to the config file if any.
* As announced in v1.25, Ubuntu 18 will not be supported as of Dec 2022. In addition to that, there will be no WebKit updates on Ubuntu 18 starting from the next Playwright release.
### Behavior Changes[](#behavior-changes "Direct link to Behavior Changes")
* [expect(locator).toHaveAttribute()](/docs/api/class-locatorassertions#locator-assertions-to-have-attribute) with an empty value does not match missing attribute anymore. For example, the following snippet will succeed when `button` **does not** have a `disabled` attribute.
await expect(page.getByRole('button')).toHaveAttribute('disabled', '');
* Command line options `--grep` and `--grep-invert` previously incorrectly ignored `grep` and `grepInvert` options specified in the config. Now all of them are applied together.
### Browser Versions[](#browser-versions-29 "Direct link to Browser Versions")
* Chromium 107.0.5304.18
* Mozilla Firefox 105.0.1
* WebKit 16.0
This version was also tested against the following stable channels:
* Google Chrome 106
* Microsoft Edge 106
Version 1.26[](#version-126 "Direct link to Version 1.26")
-----------------------------------------------------------
### Assertions[](#assertions "Direct link to Assertions")
* New option `enabled` for [expect(locator).toBeEnabled()](/docs/api/class-locatorassertions#locator-assertions-to-be-enabled).
* [expect(locator).toHaveText()](/docs/api/class-locatorassertions#locator-assertions-to-have-text) now pierces open shadow roots.
* New option `editable` for [expect(locator).toBeEditable()](/docs/api/class-locatorassertions#locator-assertions-to-be-editable).
* New option `visible` for [expect(locator).toBeVisible()](/docs/api/class-locatorassertions#locator-assertions-to-be-visible).
### Other highlights[](#other-highlights-1 "Direct link to Other highlights")
* New option `maxRedirects` for [apiRequestContext.get()](/docs/api/class-apirequestcontext#api-request-context-get) and others to limit redirect count.
* New command-line flag `--pass-with-no-tests` that allows the test suite to pass when no files are found.
* New command-line flag `--ignore-snapshots` to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `expect(page).toHaveScreenshot()`.
### Behavior Change[](#behavior-change "Direct link to Behavior Change")
A bunch of Playwright APIs already support the `waitUntil: 'domcontentloaded'` option. For example:
await page.goto('https://playwright.dev', { waitUntil: 'domcontentloaded',});
Prior to 1.26, this would wait for all iframes to fire the `DOMContentLoaded` event.
To align with web specification, the `'domcontentloaded'` value only waits for the target frame to fire the `'DOMContentLoaded'` event. Use `waitUntil: 'load'` to wait for all iframes.
### Browser Versions[](#browser-versions-30 "Direct link to Browser Versions")
* Chromium 106.0.5249.30
* Mozilla Firefox 104.0
* WebKit 16.0
This version was also tested against the following stable channels:
* Google Chrome 105
* Microsoft Edge 105
Version 1.25[](#version-125 "Direct link to Version 1.25")
-----------------------------------------------------------
### VSCode Extension[](#vscode-extension "Direct link to VSCode Extension")
* Watch your tests running live & keep devtools open.
* Pick selector.
* Record new test from current page state.
### Test Runner[](#test-runner-5 "Direct link to Test Runner")
* [test.step()](/docs/api/class-test#test-step) now returns the value of the step function:
test('should work', async ({ page }) => { const pageTitle = await test.step('get title', async () => { await page.goto('https://playwright.dev'); return await page.title(); }); console.log(pageTitle);});
* Added [test.describe.fixme()](/docs/api/class-test#test-describe-fixme).
* New `'interrupted'` test status.
* Enable tracing via CLI flag: `npx playwright test --trace=on`.
### Announcements[](#announcements-1 "Direct link to Announcements")
* 🎁 We now ship Ubuntu 22.04 Jammy Jellyfish docker image: `mcr.microsoft.com/playwright:v1.34.0-jammy`.
* 🪦 This is the last release with macOS 10.15 support (deprecated as of 1.21).
* 🪦 This is the last release with Node.js 12 support, we recommend upgrading to Node.js LTS (16).
* ⚠️ Ubuntu 18 is now deprecated and will not be supported as of Dec 2022.
### Browser Versions[](#browser-versions-31 "Direct link to Browser Versions")
* Chromium 105.0.5195.19
* Mozilla Firefox 103.0
* WebKit 16.0
This version was also tested against the following stable channels:
* Google Chrome 104
* Microsoft Edge 104
Version 1.24[](#version-124 "Direct link to Version 1.24")
-----------------------------------------------------------
### 🌍 Multiple Web Servers in `playwright.config.ts`[](#-multiple-web-servers-in-playwrightconfigts "Direct link to -multiple-web-servers-in-playwrightconfigts")
Launch multiple web servers, databases, or other processes by passing an array of configurations:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ webServer: [ { command: 'npm run start', url: 'http://127.0.0.1:3000', timeout: 120 * 1000, reuseExistingServer: !process.env.CI, }, { command: 'npm run backend', url: 'http://127.0.0.1:3333', timeout: 120 * 1000, reuseExistingServer: !process.env.CI, } ], use: { baseURL: 'http://localhost:3000/', },});
### 🐂 Debian 11 Bullseye Support[](#-debian-11-bullseye-support "Direct link to 🐂 Debian 11 Bullseye Support")
Playwright now supports Debian 11 Bullseye on x86\_64 for Chromium, Firefox and WebKit. Let us know if you encounter any issues!
Linux support looks like this:
| | Ubuntu 20.04 | Ubuntu 22.04 | Debian 11 | :--- | :---: | :---: | :---: | :---: | | Chromium | ✅ | ✅ | ✅ | | WebKit | ✅ | ✅ | ✅ | | Firefox | ✅ | ✅ | ✅ |
### 🕵️ Anonymous Describe[](#️-anonymous-describe "Direct link to 🕵️ Anonymous Describe")
It is now possible to call [test.describe()](/docs/api/class-test#test-describe) to create suites without a title. This is useful for giving a group of tests a common option with [test.use()](/docs/api/class-test#test-use).
test.describe(() => { test.use({ colorScheme: 'dark' }); test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... });});
### 🧩 Component Tests Update[](#-component-tests-update "Direct link to 🧩 Component Tests Update")
Playwright 1.24 Component Tests introduce `beforeMount` and `afterMount` hooks. Use these to configure your app for tests.
For example, this could be used to setup App router in Vue.js:
src/component.spec.ts
import { test } from '@playwright/experimental-ct-vue';import { Component } from './mycomponent';test('should work', async ({ mount }) => { const component = await mount(Component, { hooksConfig: { /* anything to configure your app */ } });});
playwright/index.ts
import { router } from '../router';import { beforeMount } from '@playwright/experimental-ct-vue/hooks';beforeMount(async ({ app, hooksConfig }) => { app.use(router);});
A similar configuration in Next.js would look like this:
src/component.spec.jsx
import { test } from '@playwright/experimental-ct-react';import { Component } from './mycomponent';test('should work', async ({ mount }) => { const component = await mount(` element.
* Methods [expect(locator).toContainText()](/docs/api/class-locatorassertions#locator-assertions-to-contain-text) and [expect(locator).toHaveText()](/docs/api/class-locatorassertions#locator-assertions-to-have-text) now accept `ignoreCase` option.
### Component Tests Update[](#component-tests-update "Direct link to Component Tests Update")
* Support for Vue2 via the [`@playwright/experimental-ct-vue2`](https://www.npmjs.com/package/@playwright/experimental-ct-vue2) package.
* Support for component tests for [create-react-app](https://www.npmjs.com/package/create-react-app) with components in `.js` files.
Read more about [component testing with Playwright](/docs/test-components).
### Miscellaneous[](#miscellaneous-13 "Direct link to Miscellaneous")
* If there's a service worker that's in your way, you can now easily disable it with a new context option `serviceWorkers`:
playwright.config.ts
export default { use: { serviceWorkers: 'block', }};
* Using `.zip` path for `recordHar` context option automatically zips the resulting HAR:
const context = await browser.newContext({ recordHar: { path: 'github.har.zip', }});
* If you intend to edit HAR by hand, consider using the `"minimal"` HAR recording mode that only records information that is essential for replaying:
const context = await browser.newContext({ recordHar: { path: 'github.har', mode: 'minimal', }});
* Playwright now runs on Ubuntu 22 amd64 and Ubuntu 22 arm64. We also publish new docker image `mcr.microsoft.com/playwright:v1.34.0-jammy`.
### ⚠️ Breaking Changes ⚠️[](#️-breaking-changes-️ "Direct link to ⚠️ Breaking Changes ⚠️")
WebServer is now considered "ready" if request to the specified url has any of the following HTTP status codes:
* `200-299`
* `300-399` (new)
* `400`, `401`, `402`, `403` (new)
Version 1.22[](#version-122 "Direct link to Version 1.22")
-----------------------------------------------------------
### Highlights[](#highlights-4 "Direct link to Highlights")
* Components Testing (preview)
Playwright Test can now test your [React](https://reactjs.org/), [Vue.js](https://vuejs.org/) or [Svelte](https://svelte.dev/) components. You can use all the features of Playwright Test (such as parallelization, emulation & debugging) while running components in real browsers.
Here is what a typical component test looks like:
App.spec.tsx
import { test, expect } from '@playwright/experimental-ct-react';import App from './App';// Let's test component in a dark scheme!test.use({ colorScheme: 'dark' });test('should render', async ({ mount }) => { const component = await mount(/resourceGroups//providers/Microsoft.Storage/storageAccounts/
4. Use the credentials from the previous step to set up encrypted secrets in your GitHub repository. Go to your repository's settings, under [GitHub Actions secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository), and add the following secrets:
* `AZCOPY_SPA_APPLICATION_ID`
* `AZCOPY_SPA_CLIENT_SECRET`
* `AZCOPY_TENANT_ID`
For a detailed guide on how to authorize a service principal using a client secret, refer to [this Microsoft documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-authorize-azure-active-directory#authorize-a-service-principal-by-using-a-client-secret).
5. Add a step that uploads the HTML report to Azure Storage.
.github/workflows/playwright.yml
... - name: Upload HTML report to Azure shell: bash run: | REPORT_DIR='run-${{ github.run_id }}-${{ github.run_attempt }}' azcopy cp --recursive "./playwright-report/*" "https://.blob.core.windows.net/\$web/$REPORT_DIR" echo "::notice title=HTML report url::https://.z1.web.core.windows.net/$REPORT_DIR/index.html" env: AZCOPY_AUTO_LOGIN_TYPE: SPN AZCOPY_SPA_APPLICATION_ID: '${{ secrets.AZCOPY_SPA_APPLICATION_ID }}' AZCOPY_SPA_CLIENT_SECRET: '${{ secrets.AZCOPY_SPA_CLIENT_SECRET }}' AZCOPY_TENANT_ID: '${{ secrets.AZCOPY_TENANT_ID }}'
The contents of the `$web` storage container can be accessed from a browser by using the [public URL](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website-how-to?tabs=azure-portal#portal-find-url) of the website.
note
This step will not work for pull requests created from a forked repository because such workflow [doesn't have access to the secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#using-secrets-in-a-workflow).
Properly handling Secrets[](#properly-handling-secrets "Direct link to Properly handling Secrets")
---------------------------------------------------------------------------------------------------
Artifacts like trace files, HTML reports or even the console logs contain information about your test execution. They can contain sensitive data like user credentials for a test user, access tokens to a staging backend, testing source code, or sometimes even your application source code. Treat these files just as carefully as you treat that sensitive data. If you upload reports and traces as part of your CI workflow, make sure that you only upload them to trusted artifact stores, or that you encrypt the files before upload. The same is true for sharing artifacts with team members: Use a trusted file share or encrypt the files before sharing.
What's Next[](#whats-next "Direct link to What's Next")
--------------------------------------------------------
* [Learn how to use Locators](/docs/locators)
* [Learn how to perform Actions](/docs/input)
* [Learn how to write Assertions](/docs/test-assertions)
* [Learn more about the Trace Viewer](/docs/trace-viewer)
* [Learn more ways of running tests on GitHub Actions](/docs/ci#github-actions)
* [Learn more about running tests on other CI providers](/docs/ci)
# Playwright Test Agents
Playwright Test Agents
======================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright comes with three Playwright Test Agents out of the box: **🎭 planner**, **🎭 generator** and **🎭 healer**.
These agents can be used independently, sequentially, or as the chained calls in the agentic loop. Using them sequentially will produce test coverage for your product.
* **🎭 planner** explores the app and produces a Markdown test plan
* **🎭 generator** transforms the Markdown plan into the Playwright Test files
* **🎭 healer** executes the test suite and automatically repairs failing tests
### Getting Started[](#getting-started "Direct link to Getting Started")
Start with adding Playwright Test Agent definitions to your project using the `init-agents` command. These definitions should be regenerated whenever Playwright is updated to pick up new tools and instructions.
* VS Code
* Claude Code
* OpenCode
npx playwright init-agents --loop=vscode
npx playwright init-agents --loop=claude
npx playwright init-agents --loop=opencode
note
VS Code v1.105 (currently on the [VS Code Insiders channel](https://code.visualstudio.com/insiders/)) is needed for the agentic experience in VS Code. It will become stable shortly, we are a bit ahead of the curve with this functionality!
Once the agents have been generated, you can use your AI tool of choice to command these agents to build Playwright Tests.
🎭 Planner[](#-planner "Direct link to 🎭 Planner")
----------------------------------------------------
Planner agent explores your app and produces a test plan for one or many scenarios and user flows.
**Input**
* A clear request to the planner (e.g., “Generate a plan for guest checkout.”)
* A `seed test` that sets up the environment necessary to interact with your app
* _(optional)_ A Product Requirement Document (PRD) for context
**Prompt**
> * Notice how the `seed.spec.ts` is included in the context of the planner.
> * Planner will run this test to execute all the initialization necessary for your test including the global setup, project dependencies and all the necessary fixtures and hooks.
> * Planner will also use this seed test as an example of all the generated tests. Alternatively, you can mention the file name in the prompt.
Example: seed.spec.ts
import { test, expect } from './fixtures';test('seed', async ({ page }) => { // this test uses custom fixtures from ./fixtures});
**Output**
* A Markdown test plan saved as `specs/basic-operations.md`.
* The plan is human-readable but precise enough for test generation.
Example: **specs/basic-operations.md**
# TodoMVC Application - Basic Operations Test Plan## Application OverviewThe TodoMVC application is a React-based todo list manager that demonstrates standard todo application functionality. The application provides comprehensive task management capabilities with a clean, intuitive interface. Key features include:- **Task Management**: Add, edit, complete, and delete individual todos- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos - **Filtering System**: View todos by All, Active, or Completed status with URL routing support- **Real-time Counter**: Display of active (incomplete) todo count- **Interactive UI**: Hover states, edit-in-place functionality, and responsive design- **State Persistence**: Maintains state during session navigation## Test Scenarios### 1. Adding New Todos**Seed:** `tests/seed.spec.ts`#### 1.1 Add Valid Todo**Steps:**1. Click in the "What needs to be done?" input field2. Type "Buy groceries"3. Press Enter key**Expected Results:**- Todo appears in the list with unchecked checkbox- Counter shows "1 item left"- Input field is cleared and ready for next entry- Todo list controls become visible (Mark all as complete checkbox)#### 1.2 Add Multiple Todos...
🎭 Generator[](#-generator "Direct link to 🎭 Generator")
----------------------------------------------------------
Generator agent uses the Markdown plan to produce executable Playwright Tests. It verifies selectors and assertions live as it performs the scenarios. Playwright supports generation hints and provides a catalog of assertions for efficient structural and behavioral validation.
**Input**
* Markdown plan from `specs/`
**Prompt**
> * Notice how the `basic-operations.md` is included in the context of the generator.
> * This is how generator knows where to get the test plan from. Alternatively, you can mention the file name in the prompt.
**Output**
* A test suite under `tests/`
* Generated tests may include initial errors that can be healed automatically by the healer agent
Example: **tests/add-valid-todo.spec.ts**
// spec: specs/basic-operations.md// seed: tests/seed.spec.tsimport { test, expect } from '../fixtures';test.describe('Adding New Todos', () => { test('Add Valid Todo', async ({ page }) => { // 1. Click in the "What needs to be done?" input field const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' }); await todoInput.click(); // 2. Type "Buy groceries" await todoInput.fill('Buy groceries'); // 3. Press Enter key await todoInput.press('Enter'); // Expected Results: // - Todo appears in the list with unchecked checkbox await expect(page.getByText('Buy groceries')).toBeVisible(); const todoCheckbox = page.getByRole('checkbox', { name: 'Toggle Todo' }); await expect(todoCheckbox).toBeVisible(); await expect(todoCheckbox).not.toBeChecked(); // - Counter shows "1 item left" await expect(page.getByText('1 item left')).toBeVisible(); // - Input field is cleared and ready for next entry await expect(todoInput).toHaveValue(''); await expect(todoInput).toBeFocused(); // - Todo list controls become visible (Mark all as complete checkbox) await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible(); });});
🎭 Healer[](#-healer "Direct link to 🎭 Healer")
-------------------------------------------------
When the test fails, the healer agent:
* Replays the failing steps
* Inspects the current UI to locate equivalent elements or flows
* Suggests a patch (e.g., locator update, wait adjustment, data fix)
* Re-runs the test until it passes or until guardrails stop the loop
**Input**
* Failing test name
**Prompt**
**Output**
* A passing test, or a skipped test if the healer believes the that functionality is broken.
Artifacts and Conventions[](#artifacts-and-conventions "Direct link to Artifacts and Conventions")
---------------------------------------------------------------------------------------------------
The static agent definitions and generated files follow a simple, auditable structure:
repo/ .github/ # agent definitions specs/ # human-readable test plans basic-operations.md tests/ # generated Playwright tests seed.spec.ts # seed test for environment tests/create/add-valid-todo.spec.ts playwright.config.ts
### Agent Definitions[](#agent-definitions "Direct link to Agent Definitions")
Under the hood, agent definitions are collections of instructions and MCP tools. They are provided by Playwright and should be regenerated whenever Playwright is updated.
Example for Claude Code subagents:
npx playwright init-agents --loop=vscode
### Specs in `specs/`[](#specs-in-specs "Direct link to specs-in-specs")
Specs are structured plans describing scenarios in human-readable terms. They include steps, expected outcomes, and data. Specs can start from scratch or extend a seed test.
### Tests in `tests/`[](#tests-in-tests "Direct link to tests-in-tests")
Generated Playwright tests, aligned one-to-one with specs wherever feasible.
### Seed tests `seed.spec.ts`[](#seed-tests-seedspects "Direct link to seed-tests-seedspects")
Seed tests provide a ready-to-use `page` context to bootstrap execution.
# Annotations
Annotations
===========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright supports tags and annotations that are displayed in the test report.
You can add your own tags and annotations at any moment, but Playwright comes with a few built-in ones:
* [test.skip()](/docs/api/class-test#test-skip) marks the test as irrelevant. Playwright does not run such a test. Use this annotation when the test is not applicable in some configuration.
* [test.fail()](/docs/api/class-test#test-fail) marks the test as failing. Playwright will run this test and ensure it does indeed fail. If the test does not fail, Playwright will complain.
* [test.fixme()](/docs/api/class-test#test-fixme) marks the test as failing. Playwright will not run this test, as opposed to the `fail` annotation. Use `fixme` when running the test is slow or crashes.
* [test.slow()](/docs/api/class-test#test-slow) marks the test as slow and triples the test timeout.
Annotations can be added to a single test or a group of tests.
Built-in annotations can be conditional, in which case they apply when the condition is truthy, and may depend on test fixtures. There could be multiple annotations on the same test, possibly in different configurations.
Focus a test[](#focus-a-test "Direct link to Focus a test")
------------------------------------------------------------
You can focus some tests. When there are focused tests, only these tests run.
test.only('focus this test', async ({ page }) => { // Run only focused tests in the entire project.});
Skip a test[](#skip-a-test "Direct link to Skip a test")
---------------------------------------------------------
Mark a test as skipped.
test.skip('skip this test', async ({ page }) => { // This test is not run});
Conditionally skip a test[](#conditionally-skip-a-test "Direct link to Conditionally skip a test")
---------------------------------------------------------------------------------------------------
You can skip certain test based on the condition.
test('skip this test', async ({ page, browserName }) => { test.skip(browserName === 'firefox', 'Still working on it');});
Group tests[](#group-tests "Direct link to Group tests")
---------------------------------------------------------
You can group tests to give them a logical name or to scope before/after hooks to the group.
import { test, expect } from '@playwright/test';test.describe('two tests', () => { test('one', async ({ page }) => { // ... }); test('two', async ({ page }) => { // ... });});
Tag tests[](#tag-tests "Direct link to Tag tests")
---------------------------------------------------
Sometimes you want to tag your tests as `@fast` or `@slow`, and then filter by tag in the test report. Or you might want to only run tests that have a certain tag.
To tag a test, either provide an additional details object when declaring a test, or add `@`\-token to the test title. Note that tags must start with `@` symbol.
import { test, expect } from '@playwright/test';test('test login page', { tag: '@fast',}, async ({ page }) => { // ...});test('test full report @slow', async ({ page }) => { // ...});
You can also tag all tests in a group or provide multiple tags:
import { test, expect } from '@playwright/test';test.describe('group', { tag: '@report',}, () => { test('test report header', async ({ page }) => { // ... }); test('test full report', { tag: ['@slow', '@vrt'], }, async ({ page }) => { // ... });});
You can now run tests that have a particular tag with [`--grep`](/docs/test-cli#all-options) command line option.
* Bash
* PowerShell
* Batch
npx playwright test --grep @fast
npx playwright test --grep "@fast"
npx playwright test --grep @fast
Or if you want the opposite, you can skip the tests with a certain tag:
* Bash
* PowerShell
* Batch
npx playwright test --grep-invert @fast
npx playwright test --grep-invert "@fast"
npx playwright test --grep-invert @fast
To run tests containing either tag (logical `OR` operator):
* Bash
* PowerShell
* Batch
npx playwright test --grep "@fast|@slow"
npx playwright test --grep --% "@fast^|@slow"
npx playwright test --grep "@fast^|@slow"
Or run tests containing both tags (logical `AND` operator) using regex lookaheads:
npx playwright test --grep "(?=.*@fast)(?=.*@slow)"
You can also filter tests in the configuration file via [testConfig.grep](/docs/api/class-testconfig#test-config-grep) and [testProject.grep](/docs/api/class-testproject#test-project-grep).
Annotate tests[](#annotate-tests "Direct link to Annotate tests")
------------------------------------------------------------------
If you would like to annotate your tests with something more substantial than a tag, you can do that when declaring a test. Annotations have a `type` and a `description` for more context and available in reporter API. Playwright's built-in HTML reporter shows all annotations, except those where `type` starts with `_` symbol.
For example, to annotate a test with an issue url:
import { test, expect } from '@playwright/test';test('test login page', { annotation: { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180', },}, async ({ page }) => { // ...});
You can also annotate all tests in a group or provide multiple annotations:
import { test, expect } from '@playwright/test';test.describe('report tests', { annotation: { type: 'category', description: 'report' },}, () => { test('test report header', async ({ page }) => { // ... }); test('test full report', { annotation: [ { type: 'issue', description: 'https://github.com/microsoft/playwright/issues/23180' }, { type: 'performance', description: 'very slow test!' }, ], }, async ({ page }) => { // ... });});
Conditionally skip a group of tests[](#conditionally-skip-a-group-of-tests "Direct link to Conditionally skip a group of tests")
---------------------------------------------------------------------------------------------------------------------------------
For example, you can run a group of tests just in Chromium by passing a callback.
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[](#use-fixme-in-beforeeach-hook "Direct link to use-fixme-in-beforeeach-hook")
--------------------------------------------------------------------------------------------------------------
To avoid running `beforeEach` hooks, you can put annotations in the hook itself.
example.spec.ts
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.getByText('My Profile').click(); // ...});
Runtime annotations[](#runtime-annotations "Direct link to Runtime annotations")
---------------------------------------------------------------------------------
While the test is already running, you can add annotations to [`test.info().annotations`](/docs/api/class-testinfo#test-info-annotations).
example.spec.ts
test('example test', async ({ page, browser }) => { test.info().annotations.push({ type: 'browser version', description: browser.version(), }); // ...});
# Command line
Command line
============
Playwright provides a powerful command line interface for running tests, generating code, debugging, and more. The most up to date list of commands and arguments available on the CLI can always be retrieved via `npx playwright --help`.
Essential Commands[](#essential-commands "Direct link to Essential Commands")
------------------------------------------------------------------------------
### Run Tests[](#run-tests "Direct link to Run Tests")
Run your Playwright tests. [Read more about running tests](/docs/running-tests).
#### Syntax[](#syntax "Direct link to Syntax")
npx playwright test [options] [test-filter...]
#### Examples[](#examples "Direct link to Examples")
# Run all testsnpx playwright test# Run a single test filenpx playwright test tests/todo-page.spec.ts# Run a set of test filesnpx playwright test tests/todo-page/ tests/landing-page/# Run tests at a specific linenpx playwright test my-spec.ts:42# Run tests by titlenpx playwright test -g "add a todo item"# Run tests in headed browsersnpx playwright test --headed# Run tests for a specific projectnpx playwright test --project=chromium# Get helpnpx playwright test --help
**Disable [parallelization](/docs/test-parallel)**
npx playwright test --workers=1
**Run in debug mode with [Playwright Inspector](/docs/debug)**
npx playwright test --debug
**Run tests in interactive [UI mode](/docs/test-ui-mode)**
npx playwright test --ui
#### Common Options[](#common-options "Direct link to Common Options")
Option
Description
`--debug`
Run tests with Playwright Inspector. Shortcut for `PWDEBUG=1` environment variable and `--timeout=0 --max-failures=1 --headed --workers=1` options.
`--headed`
Run tests in headed browsers (default: headless).
`-g ` or `--grep `
Only run tests matching this regular expression (default: ".\*").
`--project `
Only run tests from the specified list of projects, supports '\*' wildcard (default: run all projects).
`--ui`
Run tests in interactive UI mode.
`-j ` or `--workers `
Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%).
#### All Options[](#all-options "Direct link to All Options")
Option
Description
Non-option arguments
Each argument is treated as a regular expression matched against the full test file path. Only tests from files matching the pattern will be executed. Special symbols like `$` or `*` should be escaped with `\`. In many shells/terminals you may need to quote the arguments.
`-c ` or `--config `
Configuration file, or a test directory with optional "playwright.config.{m,c}?{js,ts}". Defaults to `playwright.config.ts` or `playwright.config.js` in the current directory.
`--debug`
Run tests with Playwright Inspector. Shortcut for `PWDEBUG=1` environment variable and `--timeout=0 --max-failures=1 --headed --workers=1` options.
`--fail-on-flaky-tests`
Fail if any test is flagged as flaky (default: false).
`--forbid-only`
Fail if `test.only` is called (default: false). Useful on CI.
`--fully-parallel`
Run all tests in parallel (default: false).
`--global-timeout `
Maximum time this test suite can run in milliseconds (default: unlimited).
`-g ` or `--grep `
Only run tests matching this regular expression (default: ".\*").
`--grep-invert `
Only run tests that do not match this regular expression.
`--headed`
Run tests in headed browsers (default: headless).
`--ignore-snapshots`
Ignore screenshot and snapshot expectations.
`-j ` or `--workers `
Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%).
`--last-failed`
Only re-run the failures.
`--list`
Collect all the tests and report them, but do not run.
`--max-failures ` or `-x`
Stop after the first `N` failures. Passing `-x` stops after the first failure.
`--no-deps`
Do not run project dependencies.
`--output `
Folder for output artifacts (default: "test-results").
`--only-changed [ref]`
Only run test files that have been changed between 'HEAD' and 'ref'. Defaults to running all uncommitted changes. Only supports Git.
`--pass-with-no-tests`
Makes test run succeed even if no tests were found.
`--project `
Only run tests from the specified list of projects, supports '\*' wildcard (default: run all projects).
`--quiet`
Suppress stdio.
`--repeat-each `
Run each test `N` times (default: 1).
`--reporter `
Reporter to use, comma-separated, can be "dot", "line", "list", or others (default: "list"). You can also pass a path to a custom reporter file.
`--retries `
Maximum retry count for flaky tests, zero for no retries (default: no retries).
`--shard `
Shard tests and execute only the selected shard, specified in the form "current/all", 1-based, e.g., "3/5".
`--test-list `
Path to a file containing a list of tests to run. See [test list](#test-list) for details.
`--test-list-invert `
Path to a file containing a list of tests to skip. See [test list](#test-list) for details.
`--timeout `
Specify test timeout threshold in milliseconds, zero for unlimited (default: 30 seconds).
`--trace `
Force tracing mode, can be `on`, `off`, `on-first-retry`, `on-all-retries`, `retain-on-failure`, `retain-on-first-failure`.
`--tsconfig `
Path to a single tsconfig applicable to all imported files (default: look up tsconfig for each imported file separately).
`--ui`
Run tests in interactive UI mode.
`--ui-host `
Host to serve UI on; specifying this option opens UI in a browser tab.
`--ui-port `
Port to serve UI on, 0 for any free port; specifying this option opens UI in a browser tab.
`-u` or `--update-snapshots [mode]`
Update snapshots with actual results. Possible values are "all", "changed", "missing", and "none". Running tests without the flag defaults to "missing"; running tests with the flag but without a value defaults to "changed".
`--update-source-method [mode]`
Update snapshots with actual results. Possible values are "patch" (default), "3way" and "overwrite". "Patch" creates a unified diff file that can be used to update the source code later. "3way" generates merge conflict markers in source code. "Overwrite" overwrites the source code with the new snapshot values.
`-x`
Stop after the first failure.
#### Test list[](#test-list "Direct link to Test list")
Options `--test-list` and `--test-list-invert` accept a path to a test list file. This file should list tests in the format similar to the output produced in `--list` mode.
# This is a test list file.# It can include comments and empty lines.# Fully qualified test with a project:[chromium] › path/to/example.spec.ts:3:9 › suite › nested suite › example test# This test is included for all projects:path/to/example.spec.ts:3:9 › example test# Use "›" or ">" as a separator:[firefox] > example.spec.ts > suite > nested suite > example test# Line/column numbers are completely ignored, you can omit them.# Three entries below refer to the same test:example.spec.ts › example testexample.spec.ts:15 › example testexample.spec.ts:42:42 › example test
### Show Report[](#show-report "Direct link to Show Report")
Display HTML report from previous test run. [Read more about the HTML reporter](/docs/test-reporters#html-reporter).
#### Syntax[](#syntax-1 "Direct link to Syntax")
npx playwright show-report [report] [options]
#### Examples[](#examples-1 "Direct link to Examples")
# Show latest test reportnpx playwright show-report# Show a specific reportnpx playwright show-report playwright-report/# Show report on custom portnpx playwright show-report --port 8080
#### Options[](#options "Direct link to Options")
Option
Description
`--host `
Host to serve report on (default: localhost)
`--port `
Port to serve report on (default: 9323)
### Install Browsers[](#install-browsers "Direct link to Install Browsers")
Install browsers required by Playwright. [Read more about Playwright's browser support](/docs/browsers).
#### Syntax[](#syntax-2 "Direct link to Syntax")
npx playwright install [options] [browser...]npx playwright install-deps [options] [browser...]npx playwright uninstall
#### Examples[](#examples-2 "Direct link to Examples")
# Install all browsersnpx playwright install# Install only Chromiumnpx playwright install chromium# Install specific browsersnpx playwright install chromium webkit# Install browsers with dependenciesnpx playwright install --with-deps
#### Install Options[](#install-options "Direct link to Install Options")
Option
Description
`--force`
Force reinstall of stable browser channels
`--with-deps`
Install browser system dependencies
`--dry-run`
Don't perform installation, just print information
`--only-shell`
Only install chromium-headless-shell instead of full Chromium
`--no-shell`
Don't install chromium-headless-shell
#### Install Deps Options[](#install-deps-options "Direct link to Install Deps Options")
Option
Description
`--dry-run`
Don't perform installation, just print information
Generation & Debugging Tools[](#generation--debugging-tools "Direct link to Generation & Debugging Tools")
-----------------------------------------------------------------------------------------------------------
### Code Generation[](#code-generation "Direct link to Code Generation")
Record actions and generate tests for multiple languages. [Read more about Codegen](/docs/codegen-intro).
#### Syntax[](#syntax-3 "Direct link to Syntax")
npx playwright codegen [options] [url]
#### Examples[](#examples-3 "Direct link to Examples")
# Start recording with interactive UInpx playwright codegen# Record on specific sitenpx playwright codegen https://playwright.dev# Generate Python codenpx playwright codegen --target=python
#### Options[](#options-1 "Direct link to Options")
Option
Description
`-b, --browser `
Browser to use: chromium, firefox, or webkit (default: chromium)
`-o, --output `
Output file for the generated script
`--target `
Language to use: javascript, playwright-test, python, etc.
`--test-id-attribute `
Attribute to use for test IDs
### Trace Viewer[](#trace-viewer "Direct link to Trace Viewer")
Analyze and view test traces for debugging. [Read more about Trace Viewer](/docs/trace-viewer).
#### Syntax[](#syntax-4 "Direct link to Syntax")
npx playwright show-trace [options]
#### Examples[](#examples-4 "Direct link to Examples")
# View a trace filenpx playwright show-trace trace.zip# View trace from directorynpx playwright show-trace trace/
#### Options[](#options-2 "Direct link to Options")
Option
Description
`-b, --browser `
Browser to use: chromium, firefox, or webkit (default: chromium)
`-h, --host `
Host to serve trace on
`-p, --port `
Port to serve trace on
Specialized Commands[](#specialized-commands "Direct link to Specialized Commands")
------------------------------------------------------------------------------------
### Merge Reports[](#merge-reports "Direct link to Merge Reports")
Read [blob](/docs/test-reporters#blob-reporter) reports and combine them. [Read more about merge-reports](/docs/test-sharding).
#### Syntax[](#syntax-5 "Direct link to Syntax")
npx playwright merge-reports [options]
#### Examples[](#examples-5 "Direct link to Examples")
# Combine test reportsnpx playwright merge-reports ./reports
#### Options[](#options-3 "Direct link to Options")
Option
Description
`-c, --config `
Configuration file. Can be used to specify additional configuration for the output report
`--reporter `
Reporter to use, comma-separated, can be "list", "line", "dot", "json", "junit", "null", "github", "html", "blob" (default: "list")
### Clear Cache[](#clear-cache "Direct link to Clear Cache")
Clear all Playwright caches.
#### Syntax[](#syntax-6 "Direct link to Syntax")
npx playwright clear-cache
# Configuration
Configuration
=============
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright has many options to configure how your tests are run. You can specify these options in the configuration file. Note that test runner options are **top-level**, do not put them into the `use` section.
Basic Configuration[](#basic-configuration "Direct link to Basic Configuration")
---------------------------------------------------------------------------------
Here are some of the most common configuration options.
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ // Look for test files in the "tests" directory, relative to this configuration file. testDir: 'tests', // Run all tests in parallel. fullyParallel: true, // Fail the build on CI if you accidentally left test.only in the source code. forbidOnly: !!process.env.CI, // Retry on CI only. retries: process.env.CI ? 2 : 0, // Opt out of parallel tests on CI. workers: process.env.CI ? 1 : undefined, // Reporter to use reporter: 'html', use: { // Base URL to use in actions like `await page.goto('/')`. baseURL: 'http://localhost:3000', // Collect trace when retrying the failed test. trace: 'on-first-retry', }, // Configure projects for major browsers. projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, ], // Run your local dev server before starting the tests. webServer: { command: 'npm run start', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, },});
Option
Description
[testConfig.forbidOnly](/docs/api/class-testconfig#test-config-forbid-only)
Whether to exit with an error if any tests are marked as `test.only`. Useful on CI.
[testConfig.fullyParallel](/docs/api/class-testconfig#test-config-fully-parallel)
have all tests in all files to run in parallel. See [Parallelism](/docs/test-parallel) and [Sharding](/docs/test-sharding) for more details.
[testConfig.projects](/docs/api/class-testconfig#test-config-projects)
Run tests in multiple configurations or on multiple browsers
[testConfig.reporter](/docs/api/class-testconfig#test-config-reporter)
Reporter to use. See [Test Reporters](/docs/test-reporters) to learn more about which reporters are available.
[testConfig.retries](/docs/api/class-testconfig#test-config-retries)
The maximum number of retry attempts per test. See [Test Retries](/docs/test-retries) to learn more about retries.
[testConfig.testDir](/docs/api/class-testconfig#test-config-test-dir)
Directory with the test files.
[testConfig.use](/docs/api/class-testconfig#test-config-use)
Options with `use{}`
[testConfig.webServer](/docs/api/class-testconfig#test-config-web-server)
To launch a server during the tests, use the `webServer` option
[testConfig.workers](/docs/api/class-testconfig#test-config-workers)
The maximum number of concurrent worker processes to use for parallelizing tests. Can also be set as percentage of logical CPU cores, e.g. `'50%'.`. See [Parallelism](/docs/test-parallel) and [Sharding](/docs/test-sharding) for more details.
Filtering Tests[](#filtering-tests "Direct link to Filtering Tests")
---------------------------------------------------------------------
Filter tests by glob patterns or regular expressions.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Glob patterns or regular expressions to ignore test files. testIgnore: '*test-assets', // Glob patterns or regular expressions that match test files. testMatch: '*todo-tests/*.spec.ts',});
Option
Description
[testConfig.testIgnore](/docs/api/class-testconfig#test-config-test-ignore)
Glob patterns or regular expressions that should be ignored when looking for the test files. For example, `'*test-assets'`
[testConfig.testMatch](/docs/api/class-testconfig#test-config-test-match)
Glob patterns or regular expressions that match test files. For example, `'*todo-tests/*.spec.ts'`. By default, Playwright runs `.*(test|spec).(js|ts|mjs)` files.
Advanced Configuration[](#advanced-configuration "Direct link to Advanced Configuration")
------------------------------------------------------------------------------------------
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Folder for test artifacts such as screenshots, videos, traces, etc. outputDir: 'test-results', // path to the global setup files. globalSetup: require.resolve('./global-setup'), // path to the global teardown files. globalTeardown: require.resolve('./global-teardown'), // Each test is given 30 seconds. timeout: 30000,});
Option
Description
[testConfig.globalSetup](/docs/api/class-testconfig#test-config-global-setup)
Path to the global setup file. This file will be required and run before all the tests. It must export a single function.
[testConfig.globalTeardown](/docs/api/class-testconfig#test-config-global-teardown)
Path to the global teardown file. This file will be required and run after all the tests. It must export a single function.
[testConfig.outputDir](/docs/api/class-testconfig#test-config-output-dir)
Folder for test artifacts such as screenshots, videos, traces, etc.
[testConfig.timeout](/docs/api/class-testconfig#test-config-timeout)
Playwright enforces a [timeout](/docs/test-timeouts) for each test, 30 seconds by default. Time spent by the test function, test fixtures and beforeEach hooks is included in the test timeout.
Expect Options[](#expect-options "Direct link to Expect Options")
------------------------------------------------------------------
Configuration for the expect assertion library.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ expect: { // Maximum time expect() should wait for the condition to be met. timeout: 5000, toHaveScreenshot: { // An acceptable amount of pixels that could be different, unset by default. maxDiffPixels: 10, }, toMatchSnapshot: { // An acceptable ratio of pixels that are different to the // total amount of pixels, between 0 and 1. maxDiffPixelRatio: 0.1, }, },});
Option
Description
[testConfig.expect](/docs/api/class-testconfig#test-config-expect)
[Web first assertions](/docs/test-assertions) like `expect(locator).toHaveText()` have a separate timeout of 5 seconds by default. This is the maximum time the `expect()` should wait for the condition to be met. Learn more about [test and expect timeouts](/docs/test-timeouts) and how to set them for a single test.
[expect(page).toHaveScreenshot()](/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
Configuration for the `expect(locator).toHaveScreenshot()` method.
[expect(value).toMatchSnapshot()](/docs/api/class-snapshotassertions#snapshot-assertions-to-match-snapshot-1)
Configuration for the `expect(locator).toMatchSnapshot()` method.
# Configuration (use)
Configuration (use)
===================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
In addition to configuring the test runner you can also configure [Emulation](#emulation-options), [Network](#network-options) and [Recording](#recording-options) for the [Browser](/docs/api/class-browser "Browser") or [BrowserContext](/docs/api/class-browsercontext "BrowserContext"). These options are passed to the `use: {}` object in the Playwright config.
### Basic Options[](#basic-options "Direct link to Basic Options")
Set the base URL and storage state for all tests:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Base URL to use in actions like `await page.goto('/')`. baseURL: 'http://localhost:3000', // Populates context with given storage state. storageState: 'state.json', },});
Option
Description
[testOptions.baseURL](/docs/api/class-testoptions#test-options-base-url)
Base URL used for all pages in the context. Allows navigating by using just the path, for example `page.goto('/settings')`.
[testOptions.storageState](/docs/api/class-testoptions#test-options-storage-state)
Populates context with given storage state. Useful for easy authentication, [learn more](/docs/auth).
### Emulation Options[](#emulation-options "Direct link to Emulation Options")
With Playwright you can emulate a real device such as a mobile phone or tablet. See our [guide on projects](/docs/test-projects) for more info on emulating devices. You can also emulate the `"geolocation"`, `"locale"` and `"timezone"` for all tests or for a specific test as well as set the `"permissions"` to show notifications or change the `"colorScheme"`. See our [Emulation](/docs/emulation) guide to learn more.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Emulates `'prefers-colors-scheme'` media feature. colorScheme: 'dark', // Context geolocation. geolocation: { longitude: 12.492507, latitude: 41.889938 }, // Emulates the user locale. locale: 'en-GB', // Grants specified permissions to the browser context. permissions: ['geolocation'], // Emulates the user timezone. timezoneId: 'Europe/Paris', // Viewport used for all pages in the context. viewport: { width: 1280, height: 720 }, },});
Option
Description
[testOptions.colorScheme](/docs/api/class-testoptions#test-options-color-scheme)
[Emulates](/docs/emulation#color-scheme-and-media) `'prefers-colors-scheme'` media feature, supported values are `'light'` and `'dark'`
[testOptions.geolocation](/docs/api/class-testoptions#test-options-geolocation)
Context [geolocation](/docs/emulation#geolocation).
[testOptions.locale](/docs/api/class-testoptions#test-options-locale)
[Emulates](/docs/emulation#locale--timezone) the user locale, for example `en-GB`, `de-DE`, etc.
[testOptions.permissions](/docs/api/class-testoptions#test-options-permissions)
A list of [permissions](/docs/emulation#permissions) to grant to all pages in the context.
[testOptions.timezoneId](/docs/api/class-testoptions#test-options-timezone-id)
Changes the [timezone](/docs/emulation#locale--timezone) of the context.
[testOptions.viewport](/docs/api/class-testoptions#test-options-viewport)
[Viewport](/docs/emulation#viewport) used for all pages in the context.
### Network Options[](#network-options "Direct link to Network Options")
Available options to configure networking:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Whether to automatically download all the attachments. acceptDownloads: false, // An object containing additional HTTP headers to be sent with every request. extraHTTPHeaders: { 'X-My-Header': 'value', }, // Credentials for HTTP authentication. httpCredentials: { username: 'user', password: 'pass', }, // Whether to ignore HTTPS errors during navigation. ignoreHTTPSErrors: true, // Whether to emulate network being offline. offline: true, // Proxy settings used for all pages in the test. proxy: { server: 'http://myproxy.com:3128', bypass: 'localhost', }, },});
Option
Description
[testOptions.acceptDownloads](/docs/api/class-testoptions#test-options-accept-downloads)
Whether to automatically download all the attachments, defaults to `true`. [Learn more](/docs/downloads) about working with downloads.
[testOptions.extraHTTPHeaders](/docs/api/class-testoptions#test-options-extra-http-headers)
An object containing additional HTTP headers to be sent with every request. All header values must be strings.
[testOptions.httpCredentials](/docs/api/class-testoptions#test-options-http-credentials)
Credentials for [HTTP authentication](/docs/network#http-authentication).
[testOptions.ignoreHTTPSErrors](/docs/api/class-testoptions#test-options-ignore-https-errors)
Whether to ignore HTTPS errors during navigation.
[testOptions.offline](/docs/api/class-testoptions#test-options-offline)
Whether to emulate network being offline.
[testOptions.proxy](/docs/api/class-testoptions#test-options-proxy)
[Proxy settings](/docs/network#http-proxy) used for all pages in the test.
note
You don't have to configure anything to mock network requests. Just define a custom [Route](/docs/api/class-route "Route") that mocks the network for a browser context. See our [network mocking guide](/docs/network) to learn more.
### Recording Options[](#recording-options "Direct link to Recording Options")
With Playwright you can capture screenshots, record videos as well as traces of your test. By default these are turned off but you can enable them by setting the `screenshot`, `video` and `trace` options in your `playwright.config.js` file.
Trace files, screenshots and videos will appear in the test output directory, typically `test-results`.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Capture screenshot after each test failure. screenshot: 'only-on-failure', // Record trace only when retrying a test for the first time. trace: 'on-first-retry', // Record video only when retrying a test for the first time. video: 'on-first-retry' },});
Option
Description
[testOptions.screenshot](/docs/api/class-testoptions#test-options-screenshot)
Capture [screenshots](/docs/screenshots) of your test. Options include `'off'`, `'on'` and `'only-on-failure'`
[testOptions.trace](/docs/api/class-testoptions#test-options-trace)
Playwright can produce test traces while running the tests. Later on, you can view the trace and get detailed information about Playwright execution by opening [Trace Viewer](/docs/trace-viewer). Options include: `'off'`, `'on'`, `'retain-on-failure'` and `'on-first-retry'`
[testOptions.video](/docs/api/class-testoptions#test-options-video)
Playwright can record [videos](/docs/videos) for your tests. Options include: `'off'`, `'on'`, `'retain-on-failure'` and `'on-first-retry'`
### Other Options[](#other-options "Direct link to Other Options")
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Maximum time each action such as `click()` can take. Defaults to 0 (no limit). actionTimeout: 0, // Name of the browser that runs tests. For example `chromium`, `firefox`, `webkit`. browserName: 'chromium', // Toggles bypassing Content-Security-Policy. bypassCSP: true, // Channel to use, for example "chrome", "chrome-beta", "msedge", "msedge-beta". channel: 'chrome', // Run browser in headless mode. headless: false, // Change the default data-testid attribute. testIdAttribute: 'pw-test-id', },});
Option
Description
[testOptions.actionTimeout](/docs/api/class-testoptions#test-options-action-timeout)
Timeout for each Playwright action in milliseconds. Defaults to `0` (no timeout). Learn more about [timeouts](/docs/test-timeouts) and how to set them for a single test.
[testOptions.browserName](/docs/api/class-testoptions#test-options-browser-name)
Name of the browser that runs tests. Defaults to 'chromium'. Options include `chromium`, `firefox`, or `webkit`.
[testOptions.bypassCSP](/docs/api/class-testoptions#test-options-bypass-csp)
Toggles bypassing Content-Security-Policy. Useful when CSP includes the production origin. Defaults to `false`.
[testOptions.channel](/docs/api/class-testoptions#test-options-channel)
Browser channel to use. [Learn more](/docs/browsers) about different browsers and channels.
[testOptions.headless](/docs/api/class-testoptions#test-options-headless)
Whether to run the browser in headless mode meaning no browser is shown when running tests. Defaults to `true`.
[testOptions.testIdAttribute](/docs/api/class-testoptions#test-options-test-id-attribute)
Changes the default [`data-testid` attribute](/docs/locators#locate-by-test-id) used by Playwright locators.
### More browser and context options[](#more-browser-and-context-options "Direct link to More browser and context options")
Any options accepted by [browserType.launch()](/docs/api/class-browsertype#browser-type-launch), [browser.newContext()](/docs/api/class-browser#browser-new-context) or [browserType.connect()](/docs/api/class-browsertype#browser-type-connect) can be put into `launchOptions`, `contextOptions` or `connectOptions` respectively in the `use` section.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { launchOptions: { slowMo: 50, }, },});
However, most common ones like `headless` or `viewport` are available directly in the `use` section - see [basic options](#basic-options), [emulation](#emulation-options) or [network](#network-options).
### Explicit Context Creation and Option Inheritance[](#explicit-context-creation-and-option-inheritance "Direct link to Explicit Context Creation and Option Inheritance")
If using the built-in `browser` fixture, calling [browser.newContext()](/docs/api/class-browser#browser-new-context) will create a context with options inherited from the config:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { userAgent: 'some custom ua', viewport: { width: 100, height: 100 }, },});
An example test illustrating the initial context options are set:
test('should inherit use options on context when using built-in browser fixture', async ({ browser,}) => { const context = await browser.newContext(); const page = await context.newPage(); expect(await page.evaluate(() => navigator.userAgent)).toBe('some custom ua'); expect(await page.evaluate(() => window.innerWidth)).toBe(100); await context.close();});
### Configuration Scopes[](#configuration-scopes "Direct link to Configuration Scopes")
You can configure Playwright globally, per project, or per test. For example, you can set the locale to be used globally by adding `locale` to the `use` option of the Playwright config, and then override it for a specific project using the `project` option in the config. You can also override it for a specific test by adding `test.use({})` in the test file and passing in the options.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { locale: 'en-GB' },});
You can override options for a specific project using the `project` option in the Playwright config.
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'], locale: 'de-DE', }, }, ],});
You can override options for a specific test file by using the `test.use()` method and passing in the options. For example to run tests with the French locale for a specific test:
import { test, expect } from '@playwright/test';test.use({ locale: 'fr-FR' });test('example', async ({ page }) => { // ...});
The same works inside a describe block. For example to run tests in a describe block with the French locale:
import { test, expect } from '@playwright/test';test.describe('french language block', () => { test.use({ locale: 'fr-FR' }); test('example', async ({ page }) => { // ... });});
### Reset an option[](#reset-an-option "Direct link to Reset an option")
You can reset an option to the value defined in the config file. Consider the following config that sets a `baseURL`:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { baseURL: 'https://playwright.dev', },});
You can now configure `baseURL` for a file, and also opt-out for a single test.
intro.spec.ts
import { test } from '@playwright/test';// Configure baseURL for this file.test.use({ baseURL: 'https://playwright.dev/docs/intro' });test('check intro contents', async ({ page }) => { // This test will use "https://playwright.dev/docs/intro" base url as defined above.});test.describe(() => { // Reset the value to a config-defined one. test.use({ baseURL: undefined }); test('can navigate to intro from the home page', async ({ page }) => { // This test will use "https://playwright.dev" base url as defined in the config. });});
If you would like to completely reset the value to `undefined`, use a long-form fixture notation.
intro.spec.ts
import { test } from '@playwright/test';// Completely unset baseURL for this file.test.use({ baseURL: [async ({}, use) => use(undefined), { scope: 'test' }],});test('no base url', async ({ page }) => { // This test will not have a base url.});
# Emulation
Emulation
=========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
With Playwright you can test your app on any browser as well as emulate a real device such as a mobile phone or tablet. Simply configure the devices you would like to emulate and Playwright will simulate the browser behavior such as `"userAgent"`, `"screenSize"`, `"viewport"` and if it `"hasTouch"` enabled. You can also emulate the `"geolocation"`, `"locale"` and `"timezone"` for all tests or for a specific test as well as set the `"permissions"` to show notifications or change the `"colorScheme"`.
Devices[](#devices "Direct link to Devices")
---------------------------------------------
Playwright comes with a [registry of device parameters](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) using [playwright.devices](/docs/api/class-playwright#playwright-devices) for selected desktop, tablet and mobile devices. It can be used to simulate browser behavior for a specific device such as user agent, screen size, viewport and if it has touch enabled. All tests will run with the specified device parameters.
* Test
* Library
playwright.config.ts
import { defineConfig, devices } from '@playwright/test'; // import devicesexport default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'], }, }, { name: 'Mobile Safari', use: { ...devices['iPhone 13'], }, }, ],});
const { chromium, devices } = require('playwright');const browser = await chromium.launch();const iphone13 = devices['iPhone 13'];const context = await browser.newContext({ ...iphone13,});
Viewport[](#viewport "Direct link to Viewport")
------------------------------------------------
The viewport is included in the device but you can override it for some tests with [page.setViewportSize()](/docs/api/class-page#page-set-viewport-size).
* Test
* Library
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'], // It is important to define the `viewport` property after destructuring `devices`, // since devices also define the `viewport` for that device. viewport: { width: 1280, height: 720 }, }, }, ]});
// Create context with given viewportconst context = await browser.newContext({ viewport: { width: 1280, height: 1024 }});
Test file:
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ viewport: { width: 1600, height: 1200 },});test('my test', async ({ page }) => { // ...});
// Create context with given viewportconst context = await browser.newContext({ viewport: { width: 1280, height: 1024 }});// Resize viewport for individual pageawait page.setViewportSize({ width: 1600, height: 1200 });// Emulate high-DPIconst context = await browser.newContext({ viewport: { width: 2560, height: 1440 }, deviceScaleFactor: 2,});
The same works inside a test file.
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.describe('specific viewport block', () => { test.use({ viewport: { width: 1600, height: 1200 } }); test('my test', async ({ page }) => { // ... });});
// Create context with given viewportconst context = await browser.newContext({ viewport: { width: 1600, height: 1200 }});const page = await context.newPage();
isMobile[](#ismobile "Direct link to isMobile")
------------------------------------------------
Whether the meta viewport tag is taken into account and touch events are enabled.
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'], // It is important to define the `isMobile` property after destructuring `devices`, // since devices also define the `isMobile` for that device. isMobile: false, }, }, ]});
Locale & Timezone[](#locale--timezone "Direct link to Locale & Timezone")
--------------------------------------------------------------------------
Emulate the browser Locale and Timezone which can be set globally for all tests in the config and then overridden for particular tests.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Emulates the browser locale. locale: 'en-GB', // Emulates the browser timezone. timezoneId: 'Europe/Paris', },});
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ locale: 'de-DE', timezoneId: 'Europe/Berlin',});test('my test for de lang in Berlin timezone', async ({ page }) => { await page.goto('https://www.bing.com'); // ...});
const context = await browser.newContext({ locale: 'de-DE', timezoneId: 'Europe/Berlin',});
Note that this only affects the browser timezone and locale, not the test runner timezone. To set the test runner timezone, you can use the [`TZ` environment variable](https://nodejs.org/api/cli.html#tz).
Permissions[](#permissions "Direct link to Permissions")
---------------------------------------------------------
Allow app to show system notifications.
* Test
* Library
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Grants specified permissions to the browser context. permissions: ['notifications'], },});
const context = await browser.newContext({ permissions: ['notifications'],});
Allow notifications for a specific domain.
* Test
* Library
tests/example.spec.ts
import { test } from '@playwright/test';test.beforeEach(async ({ context }) => { // Runs before each test and signs in each page. await context.grantPermissions(['notifications'], { origin: 'https://skype.com' });});test('first', async ({ page }) => { // page has notifications permission for https://skype.com.});
await context.grantPermissions(['notifications'], { origin: 'https://skype.com' });
Revoke all permissions with [browserContext.clearPermissions()](/docs/api/class-browsercontext#browser-context-clear-permissions).
// Libraryawait context.clearPermissions();
Geolocation[](#geolocation "Direct link to Geolocation")
---------------------------------------------------------
Grant `"geolocation"` permissions and set geolocation to a specific area.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { // Context geolocation geolocation: { longitude: 12.492507, latitude: 41.889938 }, permissions: ['geolocation'], },});
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ geolocation: { longitude: 41.890221, latitude: 12.492348 }, permissions: ['geolocation'],});test('my test with geolocation', async ({ page }) => { // ...});
const context = await browser.newContext({ geolocation: { longitude: 41.890221, latitude: 12.492348 }, permissions: ['geolocation']});
Change the location later:
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ geolocation: { longitude: 41.890221, latitude: 12.492348 }, permissions: ['geolocation'],});test('my test with geolocation', async ({ page, context }) => { // overwrite the location for this test await context.setGeolocation({ longitude: 48.858455, latitude: 2.294474 });});
await context.setGeolocation({ longitude: 48.858455, latitude: 2.294474 });
**Note** you can only change geolocation for all pages in the context.
Color Scheme and Media[](#color-scheme-and-media "Direct link to Color Scheme and Media")
------------------------------------------------------------------------------------------
Emulate the users `"colorScheme"`. Supported values are 'light' and 'dark'. You can also emulate the media type with [page.emulateMedia()](/docs/api/class-page#page-emulate-media).
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { colorScheme: 'dark', },});
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ colorScheme: 'dark' // or 'light'});test('my test with dark mode', async ({ page }) => { // ...});
// Create context with dark modeconst context = await browser.newContext({ colorScheme: 'dark' // or 'light'});// Create page with dark modeconst page = await browser.newPage({ colorScheme: 'dark' // or 'light'});// Change color scheme for the pageawait page.emulateMedia({ colorScheme: 'dark' });// Change media for pageawait page.emulateMedia({ media: 'print' });
User Agent[](#user-agent "Direct link to User Agent")
------------------------------------------------------
The User Agent is included in the device and therefore you will rarely need to change it however if you do need to test a different user agent you can override it with the `userAgent` property.
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ userAgent: 'My user agent' });test('my user agent test', async ({ page }) => { // ...});
const context = await browser.newContext({ userAgent: 'My user agent'});
Offline[](#offline "Direct link to Offline")
---------------------------------------------
Emulate the network being offline.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { offline: true },});
JavaScript Enabled[](#javascript-enabled "Direct link to JavaScript Enabled")
------------------------------------------------------------------------------
Emulate a user scenario where JavaScript is disabled.
* Test
* Library
tests/example.spec.ts
import { test, expect } from '@playwright/test';test.use({ javaScriptEnabled: false });test('test with no JavaScript', async ({ page }) => { // ...});
const context = await browser.newContext({ javaScriptEnabled: false});
# Fixtures
Fixtures
========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright Test is based on the concept of test fixtures. Test fixtures are used to establish the environment for each test, giving the test everything it needs and nothing else. Test fixtures are isolated between tests. With fixtures, you can group tests based on their meaning, instead of their common setup.
### Built-in fixtures[](#built-in-fixtures "Direct link to Built-in fixtures")
You have already used test fixtures in your first test.
import { test, expect } from '@playwright/test';test('basic test', async ({ page }) => { await page.goto('https://playwright.dev/'); await expect(page).toHaveTitle(/Playwright/);});
The `{ page }` argument tells Playwright Test to set up the `page` fixture and provide it to your test function.
Here is a list of the pre-defined fixtures that you are likely to use most of the time:
Fixture
Type
Description
page
[Page](/docs/api/class-page "Page")
Isolated page for this test run.
context
[BrowserContext](/docs/api/class-browsercontext "BrowserContext")
Isolated context for this test run. The `page` fixture belongs to this context as well. Learn how to [configure context](/docs/test-configuration).
browser
[Browser](/docs/api/class-browser "Browser")
Browsers are shared across tests to optimize resources. Learn how to [configure browsers](/docs/test-configuration).
browserName
[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string")
The name of the browser currently running the test. Either `chromium`, `firefox` or `webkit`.
request
[APIRequestContext](/docs/api/class-apirequestcontext "APIRequestContext")
Isolated [APIRequestContext](/docs/api/class-apirequestcontext) instance for this test run.
### Without fixtures[](#without-fixtures "Direct link to Without fixtures")
Here is how a typical test environment setup differs between the traditional test style and the fixture-based one.
`TodoPage` is a class that helps us interact with a "todo list" page of the web app, following the [Page Object Model](/docs/pom) pattern. It uses Playwright's `page` internally.
Click to expand the code for the `TodoPage`
todo-page.ts
import type { Page, Locator } from '@playwright/test';export class TodoPage { private readonly inputBox: Locator; private readonly todoItems: Locator; constructor(public readonly page: Page) { this.inputBox = this.page.locator('input.new-todo'); this.todoItems = this.page.getByTestId('todo-item'); } async goto() { await this.page.goto('https://demo.playwright.dev/todomvc/'); } async addToDo(text: string) { await this.inputBox.fill(text); await this.inputBox.press('Enter'); } async remove(text: string) { const todo = this.todoItems.filter({ hasText: text }); await todo.hover(); await todo.getByLabel('Delete').click(); } async removeAll() { while ((await this.todoItems.count()) > 0) { await this.todoItems.first().hover(); await this.todoItems.getByLabel('Delete').first().click(); } }}
todo.spec.ts
const { test } = require('@playwright/test');const { TodoPage } = require('./todo-page');test.describe('todo tests', () => { let todoPage; test.beforeEach(async ({ page }) => { todoPage = new TodoPage(page); await todoPage.goto(); await todoPage.addToDo('item1'); await todoPage.addToDo('item2'); }); test.afterEach(async () => { await todoPage.removeAll(); }); test('should add an item', async () => { await todoPage.addToDo('my item'); // ... }); test('should remove an item', async () => { await todoPage.remove('item1'); // ... });});
### With fixtures[](#with-fixtures "Direct link to With fixtures")
Fixtures have a number of advantages over before/after hooks:
* Fixtures **encapsulate** setup and teardown in the same place so it is easier to write. So if you have an after hook that tears down what was created in a before hook, consider turning them into a fixture.
* Fixtures are **reusable** between test files - you can define them once and use them in all your tests. That's how Playwright's built-in `page` fixture works. So if you have a helper function that is used in multiple tests, consider turning it into a fixture.
* Fixtures are **on-demand** - you can define as many fixtures as you'd like, and Playwright Test will setup only the ones needed by your test and nothing else.
* Fixtures are **composable** - they can depend on each other to provide complex behaviors.
* Fixtures are **flexible**. Tests can use any combination of fixtures to precisely tailor the environment to their needs, without affecting other tests.
* Fixtures simplify **grouping**. You no longer need to wrap tests in `describe`s that set up their environment, and are free to group your tests by their meaning instead.
Click to expand the code for the `TodoPage`
todo-page.ts
import type { Page, Locator } from '@playwright/test';export class TodoPage { private readonly inputBox: Locator; private readonly todoItems: Locator; constructor(public readonly page: Page) { this.inputBox = this.page.locator('input.new-todo'); this.todoItems = this.page.getByTestId('todo-item'); } async goto() { await this.page.goto('https://demo.playwright.dev/todomvc/'); } async addToDo(text: string) { await this.inputBox.fill(text); await this.inputBox.press('Enter'); } async remove(text: string) { const todo = this.todoItems.filter({ hasText: text }); await todo.hover(); await todo.getByLabel('Delete').click(); } async removeAll() { while ((await this.todoItems.count()) > 0) { await this.todoItems.first().hover(); await this.todoItems.getByLabel('Delete').first().click(); } }}
example.spec.ts
import { test as base } from '@playwright/test';import { TodoPage } from './todo-page';// Extend basic test by providing a "todoPage" fixture.const test = base.extend<{ todoPage: TodoPage }>({ todoPage: async ({ page }, use) => { const todoPage = new TodoPage(page); await todoPage.goto(); await todoPage.addToDo('item1'); await todoPage.addToDo('item2'); await use(todoPage); await todoPage.removeAll(); },});test('should add an item', async ({ todoPage }) => { await todoPage.addToDo('my item'); // ...});test('should remove an item', async ({ todoPage }) => { await todoPage.remove('item1'); // ...});
Creating a fixture[](#creating-a-fixture "Direct link to Creating a fixture")
------------------------------------------------------------------------------
To create your own fixture, use [test.extend()](/docs/api/class-test#test-extend) to create a new `test` object that will include it.
Below we create two fixtures `todoPage` and `settingsPage` that follow the [Page Object Model](/docs/pom) pattern.
Click to expand the code for the `TodoPage` and `SettingsPage`
todo-page.ts
import type { Page, Locator } from '@playwright/test';export class TodoPage { private readonly inputBox: Locator; private readonly todoItems: Locator; constructor(public readonly page: Page) { this.inputBox = this.page.locator('input.new-todo'); this.todoItems = this.page.getByTestId('todo-item'); } async goto() { await this.page.goto('https://demo.playwright.dev/todomvc/'); } async addToDo(text: string) { await this.inputBox.fill(text); await this.inputBox.press('Enter'); } async remove(text: string) { const todo = this.todoItems.filter({ hasText: text }); await todo.hover(); await todo.getByLabel('Delete').click(); } async removeAll() { while ((await this.todoItems.count()) > 0) { await this.todoItems.first().hover(); await this.todoItems.getByLabel('Delete').first().click(); } }}
SettingsPage is similar:
settings-page.ts
import type { Page } from '@playwright/test';export class SettingsPage { constructor(public readonly page: Page) { } async switchToDarkMode() { // ... }}
my-test.ts
import { test as base } from '@playwright/test';import { TodoPage } from './todo-page';import { SettingsPage } from './settings-page';// Declare the types of your fixtures.type MyFixtures = { todoPage: TodoPage; settingsPage: SettingsPage;};// Extend base test by providing "todoPage" and "settingsPage".// This new "test" can be used in multiple test files, and each of them will get the fixtures.export const test = base.extend({ todoPage: async ({ page }, use) => { // Set up the fixture. const todoPage = new TodoPage(page); await todoPage.goto(); await todoPage.addToDo('item1'); await todoPage.addToDo('item2'); // Use the fixture value in the test. await use(todoPage); // Clean up the fixture. await todoPage.removeAll(); }, settingsPage: async ({ page }, use) => { await use(new SettingsPage(page)); },});export { expect } from '@playwright/test';
note
Custom fixture names should start with a letter or underscore, and can contain only letters, numbers, and underscores.
Using a fixture[](#using-a-fixture "Direct link to Using a fixture")
---------------------------------------------------------------------
Just mention a fixture in your test function argument, and the test runner will take care of it. Fixtures are also available in hooks and other fixtures. If you use TypeScript, fixtures will be type safe.
Below we use the `todoPage` and `settingsPage` fixtures that we defined above.
import { test, expect } from './my-test';test.beforeEach(async ({ settingsPage }) => { await settingsPage.switchToDarkMode();});test('basic test', async ({ todoPage, page }) => { await todoPage.addToDo('something nice'); await expect(page.getByTestId('todo-title')).toContainText(['something nice']);});
Overriding fixtures[](#overriding-fixtures "Direct link to Overriding fixtures")
---------------------------------------------------------------------------------
In addition to creating your own fixtures, you can also override existing fixtures to fit your needs. Consider the following example which overrides the `page` fixture by automatically navigating to the `baseURL`:
import { test as base } from '@playwright/test';export const test = base.extend({ page: async ({ baseURL, page }, use) => { await page.goto(baseURL); await use(page); },});
Notice that in this example, the `page` fixture is able to depend on other built-in fixtures such as [testOptions.baseURL](/docs/api/class-testoptions#test-options-base-url). We can now configure `baseURL` in the configuration file, or locally in the test file with [test.use()](/docs/api/class-test#test-use).
example.spec.ts
test.use({ baseURL: 'https://playwright.dev' });
Fixtures can also be overridden, causing the base fixture to be completely replaced with something different. For example, we could override the [testOptions.storageState](/docs/api/class-testoptions#test-options-storage-state) fixture to provide our own data.
import { test as base } from '@playwright/test';export const test = base.extend({ storageState: async ({}, use) => { const cookie = await getAuthCookie(); await use({ cookies: [cookie] }); },});
Worker-scoped fixtures[](#worker-scoped-fixtures "Direct link to Worker-scoped fixtures")
------------------------------------------------------------------------------------------
Playwright Test uses [worker processes](/docs/test-parallel) to run test files. Similar to how test fixtures are set up for individual test runs, worker fixtures are set up for each worker process. That's where you can set up services, run servers, etc. Playwright Test will reuse the worker process for as many test files as it can, provided their worker fixtures match and hence environments are identical.
Below we'll create an `account` fixture that will be shared by all tests in the same worker, and override the `page` fixture to log in to this account for each test. To generate unique accounts, we'll use the [workerInfo.workerIndex](/docs/api/class-workerinfo#worker-info-worker-index) that is available to any test or fixture. Note the tuple-like syntax for the worker fixture - we have to pass `{scope: 'worker'}` so that test runner sets this fixture up once per worker.
my-test.ts
import { test as base } from '@playwright/test';type Account = { username: string; password: string;};// Note that we pass worker fixture types as a second template parameter.export const test = base.extend<{}, { account: Account }>({ account: [async ({ browser }, use, workerInfo) => { // Unique username. const username = 'user' + workerInfo.workerIndex; const password = 'verysecure'; // Create the account with Playwright. const page = await browser.newPage(); await page.goto('/signup'); await page.getByLabel('User Name').fill(username); await page.getByLabel('Password').fill(password); await page.getByText('Sign up').click(); // Make sure everything is ok. await expect(page.getByTestId('result')).toHaveText('Success'); // Do not forget to cleanup. await page.close(); // Use the account value. await use({ username, password }); }, { scope: 'worker' }], page: async ({ page, account }, use) => { // Sign in with our account. const { username, password } = account; await page.goto('/signin'); await page.getByLabel('User Name').fill(username); await page.getByLabel('Password').fill(password); await page.getByText('Sign in').click(); await expect(page.getByTestId('userinfo')).toHaveText(username); // Use signed-in page in the test. await use(page); },});export { expect } from '@playwright/test';
Automatic fixtures[](#automatic-fixtures "Direct link to Automatic fixtures")
------------------------------------------------------------------------------
Automatic fixtures are set up for each test/worker, even when the test does not list them directly. To create an automatic fixture, use the tuple syntax and pass `{ auto: true }`.
Here is an example fixture that automatically attaches debug logs when the test fails, so we can later review the logs in the reporter. Note how it uses the [TestInfo](/docs/api/class-testinfo "TestInfo") object that is available in each test/fixture to retrieve metadata about the test being run.
my-test.ts
import debug from 'debug';import fs from 'fs';import { test as base } from '@playwright/test';export const test = base.extend<{ saveLogs: void }>({ saveLogs: [async ({}, use, testInfo) => { // Collecting logs during the test. const logs = []; debug.log = (...args) => logs.push(args.map(String).join('')); debug.enable('myserver'); await use(); // After the test we can check whether the test passed or failed. if (testInfo.status !== testInfo.expectedStatus) { // outputPath() API guarantees a unique file name. const logFile = testInfo.outputPath('logs.txt'); await fs.promises.writeFile(logFile, logs.join('\n'), 'utf8'); testInfo.attachments.push({ name: 'logs', contentType: 'text/plain', path: logFile }); } }, { auto: true }],});export { expect } from '@playwright/test';
Fixture timeout[](#fixture-timeout "Direct link to Fixture timeout")
---------------------------------------------------------------------
By default, the fixture inherits the timeout value of the test. However, for slow fixtures, especially [worker-scoped](#worker-scoped-fixtures) ones, it is convenient to have a separate timeout. This way you can keep the overall test timeout small, and give the slow fixture more time.
import { test as base, expect } from '@playwright/test';const test = base.extend<{ slowFixture: string }>({ slowFixture: [async ({}, use) => { // ... perform a slow operation ... await use('hello'); }, { timeout: 60000 }]});test('example test', async ({ slowFixture }) => { // ...});
Fixtures-options[](#fixtures-options "Direct link to Fixtures-options")
------------------------------------------------------------------------
Playwright Test supports running multiple test projects that can be configured separately. You can use "option" fixtures to make your configuration options declarative and type safe. Learn more about [parameterizing tests](/docs/test-parameterize).
Below we'll create a `defaultItem` option in addition to the `todoPage` fixture from other examples. This option will be set in the configuration file. Note the tuple syntax and `{ option: true }` argument.
Click to expand the code for the `TodoPage`
todo-page.ts
import type { Page, Locator } from '@playwright/test';export class TodoPage { private readonly inputBox: Locator; private readonly todoItems: Locator; constructor(public readonly page: Page) { this.inputBox = this.page.locator('input.new-todo'); this.todoItems = this.page.getByTestId('todo-item'); } async goto() { await this.page.goto('https://demo.playwright.dev/todomvc/'); } async addToDo(text: string) { await this.inputBox.fill(text); await this.inputBox.press('Enter'); } async remove(text: string) { const todo = this.todoItems.filter({ hasText: text }); await todo.hover(); await todo.getByLabel('Delete').click(); } async removeAll() { while ((await this.todoItems.count()) > 0) { await this.todoItems.first().hover(); await this.todoItems.getByLabel('Delete').first().click(); } }}
my-test.ts
import { test as base } from '@playwright/test';import { TodoPage } from './todo-page';// Declare your options to type-check your configuration.export type MyOptions = { defaultItem: string;};type MyFixtures = { todoPage: TodoPage;};// Specify both option and fixture types.export const test = base.extend({ // Define an option and provide a default value. // We can later override it in the config. defaultItem: ['Something nice', { option: true }], // Our "todoPage" fixture depends on the option. todoPage: async ({ page, defaultItem }, use) => { const todoPage = new TodoPage(page); await todoPage.goto(); await todoPage.addToDo(defaultItem); await use(todoPage); await todoPage.removeAll(); },});export { expect } from '@playwright/test';
We can now use the `todoPage` fixture as usual, and set the `defaultItem` option in the configuration file.
playwright.config.ts
import { defineConfig } from '@playwright/test';import type { MyOptions } from './my-test';export default defineConfig({ projects: [ { name: 'shopping', use: { defaultItem: 'Buy milk' }, }, { name: 'wellbeing', use: { defaultItem: 'Exercise!' }, }, ]});
**Array as an option value**
If the value of your option is an array, for example `[{ name: 'Alice' }, { name: 'Bob' }]`, you'll need to wrap it into an extra array when providing the value. This is best illustrated with an example.
type Person = { name: string };const test = base.extend<{ persons: Person[] }>({ // Declare the option, default value is an empty array. persons: [[], { option: true }],});// Option value is an array of persons.const actualPersons = [{ name: 'Alice' }, { name: 'Bob' }];test.use({ // CORRECT: Wrap the value into an array and pass the scope. persons: [actualPersons, { scope: 'test' }],});test.use({ // WRONG: passing an array value directly will not work. persons: actualPersons,});
**Reset an option**
You can reset an option to the value defined in the config file by setting it to `undefined`. Consider the following config that sets a `baseURL`:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { baseURL: 'https://playwright.dev', },});
You can now configure `baseURL` for a file, and also opt-out for a single test.
intro.spec.ts
import { test } from '@playwright/test';// Configure baseURL for this file.test.use({ baseURL: 'https://playwright.dev/docs/intro' });test('check intro contents', async ({ page }) => { // This test will use "https://playwright.dev/docs/intro" base url as defined above.});test.describe(() => { // Reset the value to a config-defined one. test.use({ baseURL: undefined }); test('can navigate to intro from the home page', async ({ page }) => { // This test will use "https://playwright.dev" base url as defined in the config. });});
If you would like to completely reset the value to `undefined`, use a long-form fixture notation.
intro.spec.ts
import { test } from '@playwright/test';// Completely unset baseURL for this file.test.use({ baseURL: [async ({}, use) => use(undefined), { scope: 'test' }],});test('no base url', async ({ page }) => { // This test will not have a base url.});
Execution order[](#execution-order "Direct link to Execution order")
---------------------------------------------------------------------
Each fixture has a setup and teardown phase before and after the `await use()` call in the fixture. Setup is executed before the test/hook requiring it is run, and teardown is executed when the fixture is no longer being used by the test/hook.
Fixtures follow these rules to determine the execution order:
* When fixture A depends on fixture B: B is always set up before A and torn down after A.
* Non-automatic fixtures are executed lazily, only when the test/hook needs them.
* Test-scoped fixtures are torn down after each test, while worker-scoped fixtures are only torn down when the worker process executing tests is torn down.
Consider the following example:
import { test as base } from '@playwright/test';const test = base.extend<{ testFixture: string, autoTestFixture: string, unusedFixture: string,}, { workerFixture: string, autoWorkerFixture: string,}>({ workerFixture: [async ({ browser }) => { // workerFixture setup... await use('workerFixture'); // workerFixture teardown... }, { scope: 'worker' }], autoWorkerFixture: [async ({ browser }) => { // autoWorkerFixture setup... await use('autoWorkerFixture'); // autoWorkerFixture teardown... }, { scope: 'worker', auto: true }], testFixture: [async ({ page, workerFixture }) => { // testFixture setup... await use('testFixture'); // testFixture teardown... }, { scope: 'test' }], autoTestFixture: [async () => { // autoTestFixture setup... await use('autoTestFixture'); // autoTestFixture teardown... }, { scope: 'test', auto: true }], unusedFixture: [async ({ page }) => { // unusedFixture setup... await use('unusedFixture'); // unusedFixture teardown... }, { scope: 'test' }],});test.beforeAll(async () => { /* ... */ });test.beforeEach(async ({ page }) => { /* ... */ });test('first test', async ({ page }) => { /* ... */ });test('second test', async ({ testFixture }) => { /* ... */ });test.afterEach(async () => { /* ... */ });test.afterAll(async () => { /* ... */ });
Normally, if all tests pass and no errors are thrown, the order of execution is as following.
* worker setup and `beforeAll` section:
* `browser` setup because it is required by `autoWorkerFixture`.
* `autoWorkerFixture` setup because automatic worker fixtures are always set up before anything else.
* `beforeAll` runs.
* `first test` section:
* `autoTestFixture` setup because automatic test fixtures are always set up before test and `beforeEach` hooks.
* `page` setup because it is required in `beforeEach` hook.
* `beforeEach` runs.
* `first test` runs.
* `afterEach` runs.
* `page` teardown because it is a test-scoped fixture and should be torn down after the test finishes.
* `autoTestFixture` teardown because it is a test-scoped fixture and should be torn down after the test finishes.
* `second test` section:
* `autoTestFixture` setup because automatic test fixtures are always set up before test and `beforeEach` hooks.
* `page` setup because it is required in `beforeEach` hook.
* `beforeEach` runs.
* `workerFixture` setup because it is required by `testFixture` that is required by the `second test`.
* `testFixture` setup because it is required by the `second test`.
* `second test` runs.
* `afterEach` runs.
* `testFixture` teardown because it is a test-scoped fixture and should be torn down after the test finishes.
* `page` teardown because it is a test-scoped fixture and should be torn down after the test finishes.
* `autoTestFixture` teardown because it is a test-scoped fixture and should be torn down after the test finishes.
* `afterAll` and worker teardown section:
* `afterAll` runs.
* `workerFixture` teardown because it is a workers-scoped fixture and should be torn down once at the end.
* `autoWorkerFixture` teardown because it is a workers-scoped fixture and should be torn down once at the end.
* `browser` teardown because it is a workers-scoped fixture and should be torn down once at the end.
A few observations:
* `page` and `autoTestFixture` are set up and torn down for each test, as test-scoped fixtures.
* `unusedFixture` is never set up because it is not used by any tests/hooks.
* `testFixture` depends on `workerFixture` and triggers its setup.
* `workerFixture` is lazily set up before the second test, but torn down once during worker shutdown, as a worker-scoped fixture.
* `autoWorkerFixture` is set up for `beforeAll` hook, but `autoTestFixture` is not.
Combine custom fixtures from multiple modules[](#combine-custom-fixtures-from-multiple-modules "Direct link to Combine custom fixtures from multiple modules")
---------------------------------------------------------------------------------------------------------------------------------------------------------------
You can merge test fixtures from multiple files or modules:
fixtures.ts
import { mergeTests } from '@playwright/test';import { test as dbTest } from 'database-test-utils';import { test as a11yTest } from 'a11y-test-utils';export const test = mergeTests(dbTest, a11yTest);
test.spec.ts
import { test } from './fixtures';test('passes', async ({ database, page, a11y }) => { // use database and a11y fixtures.});
Box fixtures[](#box-fixtures "Direct link to Box fixtures")
------------------------------------------------------------
Usually, custom fixtures are reported as separate steps in the UI mode, Trace Viewer and various test reports. They also appear in error messages from the test runner. For frequently used fixtures, this can mean lots of noise. You can stop the fixtures steps from being shown in the UI by "boxing" it.
import { test as base } from '@playwright/test';export const test = base.extend({ helperFixture: [async ({}, use, testInfo) => { // ... }, { box: true }],});
This is useful for non-interesting helper fixtures. For example, an [automatic](/docs/test-fixtures#automatic-fixtures) fixture that sets up some common data can be safely hidden from a test report.
You can also mark the fixture as `box: 'self'` to only hide that particular fixture, but include all the steps inside the fixture in the test report.
Custom fixture title[](#custom-fixture-title "Direct link to Custom fixture title")
------------------------------------------------------------------------------------
Instead of the usual fixture name, you can give fixtures a custom title that will be shown in test reports and error messages.
import { test as base } from '@playwright/test';export const test = base.extend({ innerFixture: [async ({}, use, testInfo) => { // ... }, { title: 'my fixture' }],});
Adding global beforeEach/afterEach hooks[](#adding-global-beforeeachaftereach-hooks "Direct link to Adding global beforeEach/afterEach hooks")
-----------------------------------------------------------------------------------------------------------------------------------------------
[test.beforeEach()](/docs/api/class-test#test-before-each) and [test.afterEach()](/docs/api/class-test#test-after-each) hooks run before/after each test declared in the same file and same [test.describe()](/docs/api/class-test#test-describe) block (if any). If you want to declare hooks that run before/after each test globally, you can declare them as auto fixtures like this:
fixtures.ts
import { test as base } from '@playwright/test';export const test = base.extend<{ forEachTest: void }>({ forEachTest: [async ({ page }, use) => { // This code runs before every test. await page.goto('http://localhost:8000'); await use(); // This code runs after every test. console.log('Last URL:', page.url()); }, { auto: true }], // automatically starts for every test.});
And then import the fixtures in all your tests:
mytest.spec.ts
import { test } from './fixtures';import { expect } from '@playwright/test';test('basic', async ({ page }) => { expect(page).toHaveURL('http://localhost:8000'); await page.goto('https://playwright.dev');});
Adding global beforeAll/afterAll hooks[](#adding-global-beforeallafterall-hooks "Direct link to Adding global beforeAll/afterAll hooks")
-----------------------------------------------------------------------------------------------------------------------------------------
[test.beforeAll()](/docs/api/class-test#test-before-all) and [test.afterAll()](/docs/api/class-test#test-after-all) hooks run before/after all tests declared in the same file and same [test.describe()](/docs/api/class-test#test-describe) block (if any), once per worker process. If you want to declare hooks that run before/after all tests in every file, you can declare them as auto fixtures with `scope: 'worker'` as follows:
fixtures.ts
import { test as base } from '@playwright/test';export const test = base.extend<{}, { forEachWorker: void }>({ forEachWorker: [async ({}, use) => { // This code runs before all the tests in the worker process. console.log(`Starting test worker ${test.info().workerIndex}`); await use(); // This code runs after all the tests in the worker process. console.log(`Stopping test worker ${test.info().workerIndex}`); }, { scope: 'worker', auto: true }], // automatically starts for every worker.});
And then import the fixtures in all your tests:
mytest.spec.ts
import { test } from './fixtures';import { expect } from '@playwright/test';test('basic', async ({ }) => { // ...});
Note that the fixtures will still run once per [worker process](/docs/test-parallel#worker-processes), but you don't need to redeclare them in every file.
# Global setup and teardown
Global setup and teardown
=========================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
There are two ways to configure global setup and teardown: using a global setup file and setting it in the config under [`globalSetup`](#option-2-configure-globalsetup-and-globalteardown) or using [project dependencies](#option-1-project-dependencies). With project dependencies, you define a project that runs before all other projects. This is the recommended approach, as it integrates better with the Playwright test runner: your HTML report will include the global setup, traces will be recorded, and fixtures can be used. For a detailed comparison of the two approaches, see the table below.
Feature
Project Dependencies (recommended)
`globalSetup` (config option)
Runs before all tests
✅ Yes
✅ Yes
HTML report visibility
✅ Shown as a separate project
❌ Not shown
Trace recording
✅ Full trace available
❌ Not supported
Playwright fixtures
✅ Fully supported
❌ Not supported
Browser management
✅ Via `browser` fixture
❌ Fully manual via `browserType.launch()`
Parallelism and retries
✅ Supported via standard config
❌ Not applicable
Config options like `headless` or `testIdAttribute`
✅ Automatically applied
❌ Ignored
Option 1: Project Dependencies[](#option-1-project-dependencies "Direct link to Option 1: Project Dependencies")
-----------------------------------------------------------------------------------------------------------------
[Project dependencies](/docs/api/class-testproject#test-project-dependencies) are a list of projects that need to run before the tests in another project run. They can be useful for configuring the global setup actions so that one project depends on this running first. Using dependencies allows global setup to produce traces and other artifacts.
### Setup[](#setup "Direct link to Setup")
First we add a new project with the name 'setup db'. We then give it a [testProject.testMatch](/docs/api/class-testproject#test-project-test-match) property in order to match the file called `global.setup.ts`:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ testDir: './tests', // ... projects: [ { name: 'setup db', testMatch: /global\.setup\.ts/, }, // { // other project // } ]});
Then we add the [testProject.dependencies](/docs/api/class-testproject#test-project-dependencies) property to our projects that depend on the setup project and pass into the array the name of our dependency project, which we defined in the previous step:
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ testDir: './tests', // ... projects: [ { name: 'setup db', testMatch: /global\.setup\.ts/, }, { name: 'chromium with db', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup db'], }, ]});
In this example the 'chromium with db' project depends on the 'setup db' project. We then create a setup test, stored at root level of your project (note that setup and teardown code must be defined as regular tests by calling [test()](/docs/api/class-test#test-call) function):
tests/global.setup.ts
import { test as setup } from '@playwright/test';setup('create new database', async ({ }) => { console.log('creating new database...'); // Initialize the database});
tests/menu.spec.ts
import { test, expect } from '@playwright/test';test('menu', async ({ page }) => { // Your test that depends on the database});
### Teardown[](#teardown "Direct link to Teardown")
You can teardown your setup by adding a [testProject.teardown](/docs/api/class-testproject#test-project-teardown) property to your setup project. This will run after all dependent projects have run.
First we add the [testProject.teardown](/docs/api/class-testproject#test-project-teardown) property to our setup project with the name 'cleanup db' which is the name we gave to our teardown project in the previous step:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ testDir: './tests', // ... projects: [ { name: 'setup db', testMatch: /global\.setup\.ts/, teardown: 'cleanup db', }, { name: 'cleanup db', testMatch: /global\.teardown\.ts/, }, { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup db'], }, ]});
Then we create a `global.teardown.ts` file in the tests directory of your project. This will be used to delete the data from the database after all tests have run.
tests/global.teardown.ts
import { test as teardown } from '@playwright/test';teardown('delete database', async ({ }) => { console.log('deleting test database...'); // Delete the database});
### Test filtering[](#test-filtering "Direct link to Test filtering")
All test filtering options, such as `--grep`/`--grep-invert`, `--shard`, filtering directly by location in the command line, or using [`test.only()`](/docs/api/class-test#test-only), directly select the primary tests to be run. If those tests belong to a project with dependencies, all tests from those dependencies will also run.
You can pass `--no-deps` command line option to ignore all dependencies and teardowns. Only your directly selected projects will run.
### More examples[](#more-examples "Direct link to More examples")
For more detailed examples check out:
* our [authentication](/docs/auth) guide
* our blog post [A better global setup in Playwright reusing login with project dependencies](https://dev.to/playwright/a-better-global-setup-in-playwright-reusing-login-with-project-dependencies-14)
* [v1.31 release video](https://youtu.be/PI50YAPTAs4) to see the demo
Option 2: Configure globalSetup and globalTeardown[](#option-2-configure-globalsetup-and-globalteardown "Direct link to Option 2: Configure globalSetup and globalTeardown")
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
You can use the `globalSetup` option in the [configuration file](/docs/test-configuration#advanced-configuration) to set something up once before running all tests. The global setup file must export a single function that takes a config object. This function will be run once before all the tests.
Similarly, use `globalTeardown` to run something once after all the tests. Alternatively, let `globalSetup` return a function that will be used as a global teardown. You can pass data such as port number, authentication tokens, etc. from your global setup to your tests using environment variables.
note
Beware that `globalSetup` and `globalTeardown` lack some features — see the [intro](#introduction) section for a detailed comparison. Consider using [project dependencies](#option-1-project-dependencies) instead to get full feature support.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ globalSetup: require.resolve('./global-setup'), globalTeardown: require.resolve('./global-teardown'),});
### Example[](#example "Direct link to Example")
Here is a global setup example that authenticates once and reuses authentication state in tests. It uses the `baseURL` and `storageState` options from the configuration file.
global-setup.ts
import { chromium, type FullConfig } from '@playwright/test';async function globalSetup(config: FullConfig) { const { baseURL, storageState } = config.projects[0].use; const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto(baseURL!); await page.getByLabel('User Name').fill('user'); await page.getByLabel('Password').fill('password'); await page.getByText('Sign in').click(); await page.context().storageState({ path: storageState as string }); await browser.close();}export default globalSetup;
Specify `globalSetup`, `baseURL` and `storageState` in the configuration file.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ globalSetup: require.resolve('./global-setup'), use: { baseURL: 'http://localhost:3000/', storageState: 'state.json', },});
Tests start already authenticated because we specify `storageState` that was populated by global setup.
import { test } from '@playwright/test';test('test', async ({ page }) => { await page.goto('/'); // You are signed in!});
You can make arbitrary data available in your tests from your global setup file by setting them as environment variables via `process.env`.
global-setup.ts
import type { FullConfig } from '@playwright/test';async function globalSetup(config: FullConfig) { process.env.FOO = 'some data'; // Or a more complicated data structure as JSON: process.env.BAR = JSON.stringify({ some: 'data' });}export default globalSetup;
Tests have access to the `process.env` properties set in the global setup.
import { test } from '@playwright/test';test('test', async ({ page }) => { // environment variables which are set in globalSetup are only available inside test(). const { FOO, BAR } = process.env; // FOO and BAR properties are populated. expect(FOO).toEqual('some data'); const complexData = JSON.parse(BAR); expect(BAR).toEqual({ some: 'data' });});
### Capturing trace of failures during global setup[](#capturing-trace-of-failures-during-global-setup "Direct link to Capturing trace of failures during global setup")
In some instances, it may be useful to capture a trace of failures encountered during the global setup. In order to do this, you must [start tracing](/docs/api/class-tracing#tracing-start) in your setup, and you must ensure that you [stop tracing](/docs/api/class-tracing#tracing-stop) if an error occurs before that error is thrown. This can be achieved by wrapping your setup in a `try...catch` block. Here is an example that expands the global setup example to capture a trace.
global-setup.ts
import { chromium, type FullConfig } from '@playwright/test';async function globalSetup(config: FullConfig) { const { baseURL, storageState } = config.projects[0].use; const browser = await chromium.launch(); const context = await browser.newContext(); const page = await context.newPage(); try { await context.tracing.start({ screenshots: true, snapshots: true }); await page.goto(baseURL!); await page.getByLabel('User Name').fill('user'); await page.getByLabel('Password').fill('password'); await page.getByText('Sign in').click(); await context.storageState({ path: storageState as string }); await context.tracing.stop({ path: './test-results/setup-trace.zip', }); await browser.close(); } catch (error) { await context.tracing.stop({ path: './test-results/failed-setup-trace.zip', }); await browser.close(); throw error; }}export default globalSetup;
# Parallelism
Parallelism
===========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright Test runs tests in parallel. In order to achieve that, it runs several worker processes that run at the same time. By default, **test files** are run in parallel. Tests in a single file are run in order, in the same worker process.
* You can configure tests using [`test.describe.configure`](#parallelize-tests-in-a-single-file) to run **tests in a single file** in parallel.
* You can configure **entire project** to have all tests in all files to run in parallel using [testProject.fullyParallel](/docs/api/class-testproject#test-project-fully-parallel) or [testConfig.fullyParallel](/docs/api/class-testconfig#test-config-fully-parallel).
* To **disable** parallelism limit the number of [workers to one](#disable-parallelism).
You can control the number of [parallel worker processes](#limit-workers) and [limit the number of failures](#limit-failures-and-fail-fast) in the whole test suite for efficiency.
Worker processes[](#worker-processes "Direct link to Worker processes")
------------------------------------------------------------------------
All tests run in worker processes. These processes are OS processes, running independently, orchestrated by the test runner. All workers have identical environments and each starts its own browser.
You can't communicate between the workers. Playwright Test reuses a single worker as much as it can to make testing faster, so multiple test files are usually run in a single worker one after another.
Workers are always shutdown after a [test failure](/docs/test-retries#failures) to guarantee pristine environment for following tests.
Limit workers[](#limit-workers "Direct link to Limit workers")
---------------------------------------------------------------
You can control the maximum number of parallel worker processes via [command line](/docs/test-cli) or in the [configuration file](/docs/test-configuration).
From the command line:
npx playwright test --workers 4
In the configuration file:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Limit the number of workers on CI, use default locally workers: process.env.CI ? 2 : undefined,});
Disable parallelism[](#disable-parallelism "Direct link to Disable parallelism")
---------------------------------------------------------------------------------
You can disable any parallelism by allowing just a single worker at any time. Either set `workers: 1` option in the configuration file or pass `--workers=1` to the command line.
npx playwright test --workers=1
Parallelize tests in a single file[](#parallelize-tests-in-a-single-file "Direct link to Parallelize tests in a single file")
------------------------------------------------------------------------------------------------------------------------------
By default, tests in a single file are run in order. If you have many independent tests in a single file, you might want to run them in parallel with [test.describe.configure()](/docs/api/class-test#test-describe-configure).
Note that parallel tests are executed in separate worker processes and cannot share any state or global variables. Each test executes all relevant hooks just for itself, including `beforeAll` and `afterAll`.
import { test } from '@playwright/test';test.describe.configure({ mode: 'parallel' });test('runs in parallel 1', async ({ page }) => { /* ... */ });test('runs in parallel 2', async ({ page }) => { /* ... */ });
Alternatively, you can opt-in all tests into this fully-parallel mode in the configuration file:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ fullyParallel: true,});
You can also opt in for fully-parallel mode for just a few projects:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // runs all tests in all files of a specific project in parallel projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, fullyParallel: true, }, ]});
Serial mode[](#serial-mode "Direct link to Serial mode")
---------------------------------------------------------
You can annotate inter-dependent tests as serial. If one of the serial tests fails, all subsequent tests are skipped. All tests in a group are retried together.
note
Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.
import { test, type Page } from '@playwright/test';// Annotate entire file as serial.test.describe.configure({ mode: 'serial' });let page: Page;test.beforeAll(async ({ browser }) => { page = await browser.newPage();});test.afterAll(async () => { await page.close();});test('runs first', async () => { await page.goto('https://playwright.dev/');});test('runs second', async () => { await page.getByText('Get Started').click();});
Opt out of fully parallel mode[](#opt-out-of-fully-parallel-mode "Direct link to Opt out of fully parallel mode")
------------------------------------------------------------------------------------------------------------------
If your configuration applies parallel mode to all tests using [testConfig.fullyParallel](/docs/api/class-testconfig#test-config-fully-parallel), you might still want to run some tests with default settings. You can override the mode per describe:
test.describe('runs in parallel with other describes', () => { test.describe.configure({ mode: 'default' }); test('in order 1', async ({ page }) => {}); test('in order 2', async ({ page }) => {});});
Shard tests between multiple machines[](#shard-tests-between-multiple-machines "Direct link to Shard tests between multiple machines")
---------------------------------------------------------------------------------------------------------------------------------------
Playwright Test can shard a test suite, so that it can be executed on multiple machines. See [sharding guide](/docs/test-sharding) for more details.
npx playwright test --shard=2/3
Limit failures and fail fast[](#limit-failures-and-fail-fast "Direct link to Limit failures and fail fast")
------------------------------------------------------------------------------------------------------------
You can limit the number of failed tests in the whole test suite by setting `maxFailures` config option or passing `--max-failures` command line flag.
When running with "max failures" set, Playwright Test will stop after reaching this number of failed tests and skip any tests that were not executed yet. This is useful to avoid wasting resources on broken test suites.
Passing command line option:
npx playwright test --max-failures=10
Setting in the configuration file:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Limit the number of failures on CI to save resources maxFailures: process.env.CI ? 10 : undefined,});
Worker index and parallel index[](#worker-index-and-parallel-index "Direct link to Worker index and parallel index")
---------------------------------------------------------------------------------------------------------------------
Each worker process is assigned two ids: a unique worker index that starts with 1, and a parallel index that is between `0` and `workers - 1`. When a worker is restarted, for example after a failure, the new worker process has the same `parallelIndex` and a new `workerIndex`.
You can read an index from environment variables `process.env.TEST_WORKER_INDEX` and `process.env.TEST_PARALLEL_INDEX`, or access them through [testInfo.workerIndex](/docs/api/class-testinfo#test-info-worker-index) and [testInfo.parallelIndex](/docs/api/class-testinfo#test-info-parallel-index).
### Isolate test data between parallel workers[](#isolate-test-data-between-parallel-workers "Direct link to Isolate test data between parallel workers")
You can leverage `process.env.TEST_WORKER_INDEX` or [testInfo.workerIndex](/docs/api/class-testinfo#test-info-worker-index) mentioned above to isolate user data in the database between tests running on different workers. All tests run by the worker reuse the same user.
Create `playwright/fixtures.ts` file that will [create `dbUserName` fixture](/docs/test-fixtures#creating-a-fixture) and initialize a new user in the test database. Use [testInfo.workerIndex](/docs/api/class-testinfo#test-info-worker-index) to differentiate between workers.
playwright/fixtures.ts
import { test as baseTest, expect } from '@playwright/test';// Import project utils for managing users in the test database.import { createUserInTestDatabase, deleteUserFromTestDatabase } from './my-db-utils';export * from '@playwright/test';export const test = baseTest.extend<{}, { dbUserName: string }>({ // Returns db user name unique for the worker. dbUserName: [async ({ }, use) => { // Use workerIndex as a unique identifier for each worker. const userName = `user-${test.info().workerIndex}`; // Initialize user in the database. await createUserInTestDatabase(userName); await use(userName); // Clean up after the tests are done. await deleteUserFromTestDatabase(userName); }, { scope: 'worker' }],});
Now, each test file should import `test` from our fixtures file instead of `@playwright/test`.
tests/example.spec.ts
// Important: import our fixtures.import { test, expect } from '../playwright/fixtures';test('test', async ({ dbUserName }) => { // Use the user name in the test.});
Control test order[](#control-test-order "Direct link to Control test order")
------------------------------------------------------------------------------
Playwright Test runs tests from a single file in the order of declaration, unless you [parallelize tests in a single file](#parallelize-tests-in-a-single-file).
There is no guarantee about the order of test execution across the files, because Playwright Test runs test files in parallel by default. However, if you [disable parallelism](#disable-parallelism), you can control test order by either naming your files in alphabetical order or using a "test list" file.
### Sort test files alphabetically[](#sort-test-files-alphabetically "Direct link to Sort test files alphabetically")
When you **disable parallel test execution**, Playwright Test runs test files in alphabetical order. You can use some naming convention to control the test order, for example `001-user-signin-flow.spec.ts`, `002-create-new-document.spec.ts` and so on.
### Use a "test list" file[](#use-a-test-list-file "Direct link to Use a \"test list\" file")
warning
Tests lists are discouraged and supported as a best-effort only. Some features such as VS Code Extension and tracing may not work properly with test lists.
You can put your tests in helper functions in multiple files. Consider the following example where tests are not defined directly in the file, but rather in a wrapper function.
feature-a.spec.ts
import { test, expect } from '@playwright/test';export default function createTests() { test('feature-a example test', async ({ page }) => { // ... test goes here });}
feature-b.spec.ts
import { test, expect } from '@playwright/test';export default function createTests() { test.use({ viewport: { width: 500, height: 500 } }); test('feature-b example test', async ({ page }) => { // ... test goes here });}
You can create a test list file that will control the order of tests - first run `feature-b` tests, then `feature-a` tests. Note how each test file is wrapped in a `test.describe()` block that calls the function where tests are defined. This way `test.use()` calls only affect tests from a single file.
test.list.ts
import { test } from '@playwright/test';import featureBTests from './feature-b.spec.ts';import featureATests from './feature-a.spec.ts';test.describe(featureBTests);test.describe(featureATests);
Now **disable parallel execution** by setting workers to one, and specify your test list file.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ workers: 1, testMatch: 'test.list.ts',});
note
Do not define your tests directly in a helper file. This could lead to unexpected results because your tests are now dependent on the order of `import`/`require` statements. Instead, wrap tests in a function that will be explicitly called by a test list file, as in the example above.
# Parameterize tests
Parameterize tests
==================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
You can either parameterize tests on a test level or on a project level.
Parameterized Tests[](#parameterized-tests "Direct link to Parameterized Tests")
---------------------------------------------------------------------------------
example.spec.ts
[ { name: 'Alice', expected: 'Hello, Alice!' }, { name: 'Bob', expected: 'Hello, Bob!' }, { name: 'Charlie', expected: 'Hello, Charlie!' },].forEach(({ name, expected }) => { // You can also do it with test.describe() or with multiple tests as long the test name is unique. test(`testing with ${name}`, async ({ page }) => { await page.goto(`https://example.com/greet?name=${name}`); await expect(page.getByRole('heading')).toHaveText(expected); });});
### Before and after hooks[](#before-and-after-hooks "Direct link to Before and after hooks")
Most of the time you should put `beforeEach`, `beforeAll`, `afterEach` and `afterAll` hooks outside of `forEach`, so that hooks are executed just once:
example.spec.ts
test.beforeEach(async ({ page }) => { // ...});test.afterEach(async ({ page }) => { // ...});[ { name: 'Alice', expected: 'Hello, Alice!' }, { name: 'Bob', expected: 'Hello, Bob!' }, { name: 'Charlie', expected: 'Hello, Charlie!' },].forEach(({ name, expected }) => { test(`testing with ${name}`, async ({ page }) => { await page.goto(`https://example.com/greet?name=${name}`); await expect(page.getByRole('heading')).toHaveText(expected); });});
If you want to have hooks for each test, you can put them inside a `describe()` - so they are executed for each iteration / each individual test:
example.spec.ts
[ { name: 'Alice', expected: 'Hello, Alice!' }, { name: 'Bob', expected: 'Hello, Bob!' }, { name: 'Charlie', expected: 'Hello, Charlie!' },].forEach(({ name, expected }) => { test.describe(() => { test.beforeEach(async ({ page }) => { await page.goto(`https://example.com/greet?name=${name}`); }); test(`testing with ${expected}`, async ({ page }) => { await expect(page.getByRole('heading')).toHaveText(expected); }); });});
Parameterized Projects[](#parameterized-projects "Direct link to Parameterized Projects")
------------------------------------------------------------------------------------------
Playwright Test supports running multiple test projects at the same time. In the following example, we'll run two projects with different options.
We declare the option `person` and set the value in the config. The first project runs with the value `Alice` and the second with the value `Bob`.
* TypeScript
* JavaScript
my-test.ts
import { test as base } from '@playwright/test';export type TestOptions = { person: string;};export const test = base.extend({ // Define an option and provide a default value. // We can later override it in the config. person: ['John', { option: true }],});
my-test.js
const base = require('@playwright/test');exports.test = base.test.extend({ // Define an option and provide a default value. // We can later override it in the config. person: ['John', { option: true }],});
We can use this option in the test, similarly to [fixtures](/docs/test-fixtures).
example.spec.ts
import { test } from './my-test';test('test 1', async ({ page, person }) => { await page.goto(`/index.html`); await expect(page.locator('#node')).toContainText(person); // ...});
Now, we can run tests in multiple configurations by using projects.
* TypeScript
* JavaScript
playwright.config.ts
import { defineConfig } from '@playwright/test';import type { TestOptions } from './my-test';export default defineConfig({ projects: [ { name: 'alice', use: { person: 'Alice' }, }, { name: 'bob', use: { person: 'Bob' }, }, ]});
playwright.config.ts
// @ts-checkmodule.exports = defineConfig({ projects: [ { name: 'alice', use: { person: 'Alice' }, }, { name: 'bob', use: { person: 'Bob' }, }, ]});
We can also use the option in a fixture. Learn more about [fixtures](/docs/test-fixtures).
* TypeScript
* JavaScript
my-test.ts
import { test as base } from '@playwright/test';export type TestOptions = { person: string;};export const test = base.extend({ // Define an option and provide a default value. // We can later override it in the config. person: ['John', { option: true }], // Override default "page" fixture. page: async ({ page, person }, use) => { await page.goto('/chat'); // We use "person" parameter as a "name" for the chat room. await page.getByLabel('User Name').fill(person); await page.getByText('Enter chat room').click(); // Each test will get a "page" that already has the person name. await use(page); },});
my-test.js
const base = require('@playwright/test');exports.test = base.test.extend({ // Define an option and provide a default value. // We can later override it in the config. person: ['John', { option: true }], // Override default "page" fixture. page: async ({ page, person }, use) => { await page.goto('/chat'); // We use "person" parameter as a "name" for the chat room. await page.getByLabel('User Name').fill(person); await page.getByText('Enter chat room').click(); // Each test will get a "page" that already has the person name. await use(page); },});
note
Parameterized projects behavior has changed in version 1.18. [Learn more](/docs/release-notes#breaking-change-custom-config-options).
Passing Environment Variables[](#passing-environment-variables "Direct link to Passing Environment Variables")
---------------------------------------------------------------------------------------------------------------
You can use environment variables to configure tests from the command line.
For example, consider the following test file that needs a username and a password. It is usually a good idea not to store your secrets in the source code, so we'll need a way to pass secrets from outside.
example.spec.ts
test(`example test`, async ({ page }) => { // ... await page.getByLabel('User Name').fill(process.env.USER_NAME); await page.getByLabel('Password').fill(process.env.PASSWORD);});
You can run this test with your secret username and password set in the command line.
* Bash
* PowerShell
* Batch
USER_NAME=me PASSWORD=secret npx playwright test
$env:USER_NAME=me$env:PASSWORD=secretnpx playwright test
set USER_NAME=meset PASSWORD=secretnpx playwright test
Similarly, configuration file can also read environment variables passed through the command line.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { baseURL: process.env.STAGING === '1' ? 'http://staging.example.test/' : 'http://example.test/', }});
Now, you can run tests against a staging or a production environment:
* Bash
* PowerShell
* Batch
STAGING=1 npx playwright test
$env:STAGING=1npx playwright test
set STAGING=1npx playwright test
### .env files[](#env-files "Direct link to .env files")
To make environment variables easier to manage, consider something like `.env` files. Here is an example that uses [`dotenv`](https://www.npmjs.com/package/dotenv) package to read environment variables directly in the configuration file.
playwright.config.ts
import { defineConfig } from '@playwright/test';import dotenv from 'dotenv';import path from 'path';// Read from ".env" file.dotenv.config({ path: path.resolve(__dirname, '.env') });// Alternatively, read from "../my.env" file.dotenv.config({ path: path.resolve(__dirname, '..', 'my.env') });export default defineConfig({ use: { baseURL: process.env.STAGING === '1' ? 'http://staging.example.test/' : 'http://example.test/', }});
Now, you can just edit `.env` file to set any variables you'd like.
# .env fileSTAGING=0USER_NAME=mePASSWORD=secret
Run tests as usual, your environment variables should be picked up.
npx playwright test
Create tests via a CSV file[](#create-tests-via-a-csv-file "Direct link to Create tests via a CSV file")
---------------------------------------------------------------------------------------------------------
The Playwright test-runner runs in Node.js, this means you can directly read files from the file system and parse them with your preferred CSV library.
See for example this CSV file, in our example `input.csv`:
"test_case","some_value","some_other_value""value 1","value 11","foobar1""value 2","value 22","foobar21""value 3","value 33","foobar321""value 4","value 44","foobar4321"
Based on this we'll generate some tests by using the [csv-parse](https://www.npmjs.com/package/csv-parse) library from NPM:
test.spec.ts
import fs from 'fs';import path from 'path';import { test } from '@playwright/test';import { parse } from 'csv-parse/sync';const records = parse(fs.readFileSync(path.join(__dirname, 'input.csv')), { columns: true, skip_empty_lines: true});for (const record of records) { test(`foo: ${record.test_case}`, async ({ page }) => { console.log(record.test_case, record.some_value, record.some_other_value); });}
# Projects
Projects
========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
A project is logical group of tests running with the same configuration. We use projects so we can run tests on different browsers and devices. Projects are configured in the `playwright.config.ts` file and once configured you can then run your tests on all projects or only on a specific project. You can also use projects to run the same tests in different configurations. For example, you can run the same tests in a logged-in and logged-out state.
By setting up projects you can also run a group of tests with different timeouts or retries or a group of tests against different environments such as staging and production, splitting tests per package/functionality and more.
Configure projects for multiple browsers[](#configure-projects-for-multiple-browsers "Direct link to Configure projects for multiple browsers")
------------------------------------------------------------------------------------------------------------------------------------------------
By using **projects** you can run your tests in multiple browsers such as chromium, webkit and firefox as well as branded browsers such as Google Chrome and Microsoft Edge. Playwright can also run on emulated tablet and mobile devices. See the [registry of device parameters](https://github.com/microsoft/playwright/blob/main/packages/playwright-core/src/server/deviceDescriptorsSource.json) for a complete list of selected desktop, tablet and mobile devices.
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, }, /* Test against mobile viewports. */ { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] }, }, { name: 'Mobile Safari', use: { ...devices['iPhone 12'] }, }, /* Test against branded browsers. */ { name: 'Microsoft Edge', use: { ...devices['Desktop Edge'], channel: 'msedge' }, }, { name: 'Google Chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' }, }, ],});
Run projects[](#run-projects "Direct link to Run projects")
------------------------------------------------------------
Playwright will run all projects by default.
npx playwright testRunning 7 tests using 5 workers ✓ [chromium] › example.spec.ts:3:1 › basic test (2s) ✓ [firefox] › example.spec.ts:3:1 › basic test (2s) ✓ [webkit] › example.spec.ts:3:1 › basic test (2s) ✓ [Mobile Chrome] › example.spec.ts:3:1 › basic test (2s) ✓ [Mobile Safari] › example.spec.ts:3:1 › basic test (2s) ✓ [Microsoft Edge] › example.spec.ts:3:1 › basic test (2s) ✓ [Google Chrome] › example.spec.ts:3:1 › basic test (2s)
Use the `--project` command line option to run a single project.
npx playwright test --project=firefoxRunning 1 test using 1 worker ✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
The VS Code test runner runs your tests on the default browser of Chrome. To run on other/multiple browsers click the play button's dropdown from the testing sidebar and choose another profile or modify the default profile by clicking **Select Default Profile** and select the browsers you wish to run your tests on.
Choose a specific profile, various profiles or all profiles to run tests on.
Configure projects for multiple environments[](#configure-projects-for-multiple-environments "Direct link to Configure projects for multiple environments")
------------------------------------------------------------------------------------------------------------------------------------------------------------
By setting up projects we can also run a group of tests with different timeouts or retries or run a group of tests against different environments. For example we can run our tests against a staging environment with 2 retries as well as against a production environment with 0 retries.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ timeout: 60000, // Timeout is shared between all tests. projects: [ { name: 'staging', use: { baseURL: 'staging.example.com', }, retries: 2, }, { name: 'production', use: { baseURL: 'production.example.com', }, retries: 0, }, ],});
Splitting tests into projects[](#splitting-tests-into-projects "Direct link to Splitting tests into projects")
---------------------------------------------------------------------------------------------------------------
We can split tests into projects and use filters to run a subset of tests. For example, we can create a project that runs tests using a filter matching all tests with a specific file name. We can then have another group of tests that ignore specific test files.
Here is an example that defines a common timeout and two projects. The "Smoke" project runs a small subset of tests without retries, and "Default" project runs all other tests with retries.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ timeout: 60000, // Timeout is shared between all tests. projects: [ { name: 'Smoke', testMatch: /.*smoke.spec.ts/, retries: 0, }, { name: 'Default', testIgnore: /.*smoke.spec.ts/, retries: 2, }, ],});
Dependencies[](#dependencies "Direct link to Dependencies")
------------------------------------------------------------
Dependencies are a list of projects that need to run before the tests in another project run. They can be useful for configuring the global setup actions so that one project depends on this running first. When using project dependencies, [test reporters](/docs/test-reporters) will show the setup tests and the [trace viewer](/docs/trace-viewer) will record traces of the setup. You can use the inspector to inspect the DOM snapshot of the trace of your setup tests and you can also use [fixtures](/docs/test-fixtures) inside your setup.
In this example the chromium, firefox and webkit projects depend on the setup project.
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';export default defineConfig({ projects: [ { name: 'setup', testMatch: '**/*.setup.ts', }, { name: 'chromium', use: { ...devices['Desktop Chrome'] }, dependencies: ['setup'], }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, dependencies: ['setup'], }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, dependencies: ['setup'], }, ],});
### Running Sequence[](#running-sequence "Direct link to Running Sequence")
When working with tests that have a dependency, the dependency will always run first and once all tests from this project have passed, then the other projects will run in parallel.
Running order:
1. Tests in the 'setup' project run. Once all tests from this project have passed, then the tests from the dependent projects will start running.
2. Tests in the 'chromium', 'webkit' and 'firefox' projects run together. By default, these projects will [run in parallel](/docs/test-parallel), subject to the maximum workers limit.
If there are more than one dependency then these project dependencies will be run first and in parallel. If the tests from a dependency fails then the tests that rely on this project will not be run.
Running order:
1. Tests in the 'Browser Login' and 'DataBase' projects run in parallel:
* 'Browser Login' passes
* ❌ 'DataBase' fails!
2. The 'e2e tests' project is not run!
### Teardown[](#teardown "Direct link to Teardown")
You can also teardown your setup by adding a [testProject.teardown](/docs/api/class-testproject#test-project-teardown) property to your setup project. Teardown will run after all dependent projects have run. See the [teardown guide](/docs/test-global-setup-teardown#teardown) for more information.
### Test filtering[](#test-filtering "Direct link to Test filtering")
All test filtering options, such as `--grep`/`--grep-invert`, `--shard`, filtering directly by location in the command line, or using [`test.only()`](/docs/api/class-test#test-only), directly select the primary tests to be run. If those tests belong to a project with dependencies, all tests from those dependencies will also run.
You can pass `--no-deps` command line option to ignore all dependencies and teardowns. Only your directly selected projects will run.
Custom project parameters[](#custom-project-parameters "Direct link to Custom project parameters")
---------------------------------------------------------------------------------------------------
Projects can be also used to parametrize tests with your custom configuration - take a look at [this separate guide](/docs/test-parameterize#parameterized-projects).
# Reporters
Reporters
=========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright Test comes with a few built-in reporters for different needs and ability to provide custom reporters. The easiest way to try out built-in reporters is to pass `--reporter` [command line option](/docs/test-cli).
npx playwright test --reporter=line
For more control, you can specify reporters programmatically in the [configuration file](/docs/test-configuration).
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: 'line',});
### Multiple reporters[](#multiple-reporters "Direct link to Multiple reporters")
You can use multiple reporters at the same time. For example you can use `'list'` for nice terminal output and `'json'` to get a comprehensive json file with the test results.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [ ['list'], ['json', { outputFile: 'test-results.json' }] ],});
### Reporters on CI[](#reporters-on-ci "Direct link to Reporters on CI")
You can use different reporters locally and on CI. For example, using concise `'dot'` reporter avoids too much output. This is the default on CI.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Concise 'dot' for CI, default 'list' when running locally reporter: process.env.CI ? 'dot' : 'list',});
Built-in reporters[](#built-in-reporters "Direct link to Built-in reporters")
------------------------------------------------------------------------------
All built-in reporters show detailed information about failures, and mostly differ in verbosity for successful runs.
### List reporter[](#list-reporter "Direct link to List reporter")
List reporter is default (except on CI where the `dot` reporter is default). It prints a line for each test being run.
npx playwright test --reporter=list
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: 'list',});
Here is an example output in the middle of a test run. Failures will be listed at the end.
npx playwright test --reporter=listRunning 124 tests using 6 workers 1 ✓ should access error in env (438ms) 2 ✓ handle long test names (515ms) 3 x 1) render expected (691ms) 4 ✓ should timeout (932ms) 5 should repeat each: 6 ✓ should respect enclosing .gitignore (569ms) 7 should teardown env after timeout: 8 should respect excluded tests: 9 ✓ should handle env beforeEach error (638ms)10 should respect enclosing .gitignore:
You can opt into the step rendering via passing the following config option:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['list', { printSteps: true }]],});
List report supports the following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_LIST_PRINT_STEPS`
`printSteps`
Whether to print each step on its own line.
`false`
`PLAYWRIGHT_FORCE_TTY`
Whether to produce output suitable for a live terminal. Supports `true`, `1`, `false`, `0`, `[WIDTH]`, and `[WIDTH]x[HEIGHT]`. `[WIDTH]` and `[WIDTH]x[HEIGHT]` specifies the TTY dimensions.
`true` when terminal is in TTY mode, `false` otherwise.
`FORCE_COLOR`
Whether to produce colored output.
`true` when terminal is in TTY mode, `false` otherwise.
### Line reporter[](#line-reporter "Direct link to Line reporter")
Line reporter is more concise than the list reporter. It uses a single line to report last finished test, and prints failures when they occur. Line reporter is useful for large test suites where it shows the progress but does not spam the output by listing all the tests.
npx playwright test --reporter=line
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: 'line',});
Here is an example output in the middle of a test run. Failures are reported inline.
npx playwright test --reporter=lineRunning 124 tests using 6 workers 1) dot-reporter.spec.ts:20:1 › render expected =================================================== Error: expect(received).toBe(expected) // Object.is equality Expected: 1 Received: 0[23/124] gitignore.spec.ts - should respect nested .gitignore
Line report supports the following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_FORCE_TTY`
Whether to produce output suitable for a live terminal. Supports `true`, `1`, `false`, `0`, `[WIDTH]`, and `[WIDTH]x[HEIGHT]`. `[WIDTH]` and `[WIDTH]x[HEIGHT]` specifies the TTY dimensions.
`true` when terminal is in TTY mode, `false` otherwise.
`FORCE_COLOR`
Whether to produce colored output.
`true` when terminal is in TTY mode, `false` otherwise.
### Dot reporter[](#dot-reporter "Direct link to Dot reporter")
Dot reporter is very concise - it only produces a single character per successful test run. It is the default on CI and useful where you don't want a lot of output.
npx playwright test --reporter=dot
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: 'dot',});
Here is an example output in the middle of a test run. Failures will be listed at the end.
npx playwright test --reporter=dotRunning 124 tests using 6 workers······F·············································
One character is displayed for each test that has run, indicating its status:
Character
Description
`·`
Passed
`F`
Failed
`×`
Failed or timed out - and will be retried
`±`
Passed on retry (flaky)
`T`
Timed out
`°`
Skipped
Dot report supports the following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_FORCE_TTY`
Whether to produce output suitable for a live terminal. Supports `true`, `1`, `false`, `0`, `[WIDTH]`, and `[WIDTH]x[HEIGHT]`. `[WIDTH]` and `[WIDTH]x[HEIGHT]` specifies the TTY dimensions.
`true` when terminal is in TTY mode, `false` otherwise.
`FORCE_COLOR`
Whether to produce colored output.
`true` when terminal is in TTY mode, `false` otherwise.
### HTML reporter[](#html-reporter "Direct link to HTML reporter")
HTML reporter produces a self-contained folder that contains report for the test run that can be served as a web page.
npx playwright test --reporter=html
By default, HTML report is opened automatically if some of the tests failed. You can control this behavior via the `open` property in the Playwright config or the `PLAYWRIGHT_HTML_OPEN` environmental variable. The possible values for that property are `always`, `never` and `on-failure` (default).
You can also configure `host` and `port` that are used to serve the HTML report.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { open: 'never' }]],});
By default, report is written into the `playwright-report` folder in the current working directory. One can override that location using the `PLAYWRIGHT_HTML_OUTPUT_DIR` environment variable or a reporter configuration.
In configuration file, pass options directly:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { outputFolder: 'my-report' }]],});
If you are uploading attachments from data folder to other location, you can use `attachmentsBaseURL` option to let html report where to look for them.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['html', { attachmentsBaseURL: 'https://external-storage.com/' }]],});
A quick way of opening the last test run report is:
npx playwright show-report
Or if there is a custom folder name:
npx playwright show-report my-report
HTML report supports the following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_HTML_TITLE`
`title`
A title to display in the generated report.
No title is displayed by default
`PLAYWRIGHT_HTML_OUTPUT_DIR`
`outputFolder`
Directory to save the report to.
`playwright-report`
`PLAYWRIGHT_HTML_OPEN`
`open`
When to open the html report in the browser, one of `'always'`, `'never'` or `'on-failure'`
`'on-failure'`
`PLAYWRIGHT_HTML_HOST`
`host`
When report opens in the browser, it will be served bound to this hostname.
`localhost`
`PLAYWRIGHT_HTML_PORT`
`port`
When report opens in the browser, it will be served on this port.
`9323` or any available port when `9323` is not available.
`PLAYWRIGHT_HTML_ATTACHMENTS_BASE_URL`
`attachmentsBaseURL`
A separate location where attachments from the `data` subdirectory are uploaded. Only needed when you upload report and `data` separately to different locations.
`data/`
`PLAYWRIGHT_HTML_NO_COPY_PROMPT`
`noCopyPrompt`
If true, disable rendering of the Copy prompt for errors. Supports `true`, `1`, `false`, and `0`.
`false`
`PLAYWRIGHT_HTML_NO_SNIPPETS`
`noSnippets`
If true, disable rendering code snippets in the action log. If there is a top level error, that report section with code snippet will still render. Supports `true`, `1`, `false`, and `0`.
`false`
### Blob reporter[](#blob-reporter "Direct link to Blob reporter")
Blob reports contain all the details about the test run and can be used later to produce any other report. Their primary function is to facilitate the merging of reports from [sharded tests](/docs/test-sharding).
npx playwright test --reporter=blob
By default, the report is written into the `blob-report` directory in the package.json directory or current working directory (if no package.json is found). The report file name looks like `report-.zip` or `report--.zip` when [sharding](/docs/test-sharding) is used. The hash is an optional value computed from `--grep`, `--grepInverted`, `--project` and file filters passed as command line arguments. The hash guarantees that running Playwright with different command line options will produce different but stable between runs report names. The output file name can be overridden in the configuration file or pass as `'PLAYWRIGHT_BLOB_OUTPUT_FILE'` environment variable.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['blob', { outputFile: `./blob-report/report-${os.platform()}.zip` }]],});
Blob report supports following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_BLOB_OUTPUT_DIR`
`outputDir`
Directory to save the output. Existing content is deleted before writing the new report.
`blob-report`
`PLAYWRIGHT_BLOB_OUTPUT_NAME`
`fileName`
Report file name.
`report---.zip`
`PLAYWRIGHT_BLOB_OUTPUT_FILE`
`outputFile`
Full path to the output file. If defined, `outputDir` and `fileName` will be ignored.
`undefined`
### JSON reporter[](#json-reporter "Direct link to JSON reporter")
JSON reporter produces an object with all information about the test run.
Most likely you want to write the JSON to a file. When running with `--reporter=json`, use `PLAYWRIGHT_JSON_OUTPUT_NAME` environment variable:
* Bash
* PowerShell
* Batch
PLAYWRIGHT_JSON_OUTPUT_NAME=results.json npx playwright test --reporter=json
$env:PLAYWRIGHT_JSON_OUTPUT_NAME="results.json"npx playwright test --reporter=json
set PLAYWRIGHT_JSON_OUTPUT_NAME=results.jsonnpx playwright test --reporter=json
In configuration file, pass options directly:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['json', { outputFile: 'results.json' }]],});
JSON report supports following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_JSON_OUTPUT_DIR`
Directory to save the output file. Ignored if output file is specified.
`cwd` or config directory.
`PLAYWRIGHT_JSON_OUTPUT_NAME`
`outputFile`
Base file name for the output, relative to the output dir.
JSON report is printed to the stdout.
`PLAYWRIGHT_JSON_OUTPUT_FILE`
`outputFile`
Full path to the output file. If defined, `PLAYWRIGHT_JSON_OUTPUT_DIR` and `PLAYWRIGHT_JSON_OUTPUT_NAME` will be ignored.
JSON report is printed to the stdout.
### JUnit reporter[](#junit-reporter "Direct link to JUnit reporter")
JUnit reporter produces a JUnit-style xml report.
Most likely you want to write the report to an xml file. When running with `--reporter=junit`, use `PLAYWRIGHT_JUNIT_OUTPUT_NAME` environment variable:
* Bash
* PowerShell
* Batch
PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xml npx playwright test --reporter=junit
$env:PLAYWRIGHT_JUNIT_OUTPUT_NAME="results.xml"npx playwright test --reporter=junit
set PLAYWRIGHT_JUNIT_OUTPUT_NAME=results.xmlnpx playwright test --reporter=junit
In configuration file, pass options directly:
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ reporter: [['junit', { outputFile: 'results.xml' }]],});
JUnit report supports following configuration options and environment variables:
Environment Variable Name
Reporter Config Option
Description
Default
`PLAYWRIGHT_JUNIT_OUTPUT_DIR`
Directory to save the output file. Ignored if output file is not specified.
`cwd` or config directory.
`PLAYWRIGHT_JUNIT_OUTPUT_NAME`
`outputFile`
Base file name for the output, relative to the output dir.
JUnit report is printed to the stdout.
`PLAYWRIGHT_JUNIT_OUTPUT_FILE`
`outputFile`
Full path to the output file. If defined, `PLAYWRIGHT_JUNIT_OUTPUT_DIR` and `PLAYWRIGHT_JUNIT_OUTPUT_NAME` will be ignored.
JUnit report is printed to the stdout.
`PLAYWRIGHT_JUNIT_STRIP_ANSI`
`stripANSIControlSequences`
Whether to remove ANSI control sequences from the text before writing it in the report.
By default output text is added as is.
`PLAYWRIGHT_JUNIT_INCLUDE_PROJECT_IN_TEST_NAME`
`includeProjectInTestName`
Whether to include Playwright project name in every test case as a name prefix.
By default not included.
`PLAYWRIGHT_JUNIT_SUITE_ID`
Value of the `id` attribute on the root `.strategy.matrix`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) option. The `matrix` option will run a separate job for every possible combination of the provided options.
The following example shows you how to configure a job to run your tests on four machines in parallel and then merge the reports into a single report. Don't forget to add `reporter: process.env.CI ? 'blob' : 'html',` to your `playwright.config.ts` file as in the example above.
1. First we add a `matrix` option to our job configuration with the `shardTotal: [4]` option containing the total number of shards we want to create and `shardIndex: [1, 2, 3, 4]` with an array of the shard numbers.
2. Then we run our Playwright tests with the `--shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}` option. This will run our test command for each shard.
3. Finally we upload our blob report to the GitHub Actions Artifacts. This will make the blob report available to other jobs in the workflow.
.github/workflows/playwright.yml
name: Playwright Testson: push: branches: [ main, master ] pull_request: branches: [ main, master ]jobs: playwright-tests: timeout-minutes: 60 runs-on: ubuntu-latest strategy: fail-fast: false matrix: shardIndex: [1, 2, 3, 4] shardTotal: [4] steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: lts/* - name: Install dependencies run: npm ci - name: Install Playwright browsers run: npx playwright install --with-deps - name: Run Playwright tests run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} - name: Upload blob report to GitHub Actions Artifacts if: ${{ !cancelled() }} uses: actions/upload-artifact@v4 with: name: blob-report-${{ matrix.shardIndex }} path: blob-report retention-days: 1
1. After all shards have completed, you can run a separate job that will merge the reports and produce a combined [HTML report](/docs/test-reporters#html-reporter). To ensure the execution order, we make the `merge-reports` job [depend](https://docs.github.com/en/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs) on our sharded `playwright-tests` job by adding `needs: [playwright-tests]`.
.github/workflows/playwright.yml
jobs:... merge-reports: # Merge reports after playwright-tests, even if some shards have failed if: ${{ !cancelled() }} needs: [playwright-tests] runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: lts/* - name: Install dependencies run: npm ci - name: Download blob reports from GitHub Actions Artifacts uses: actions/download-artifact@v5 with: path: all-blob-reports pattern: blob-report-* merge-multiple: true - name: Merge into HTML Report run: npx playwright merge-reports --reporter html ./all-blob-reports - name: Upload HTML report uses: actions/upload-artifact@v4 with: name: html-report--attempt-${{ github.run_attempt }} path: playwright-report retention-days: 14
You can now see the reports have been merged and a combined HTML report is available in the GitHub Actions Artifacts tab.
Merge-reports CLI[](#merge-reports-cli "Direct link to Merge-reports CLI")
---------------------------------------------------------------------------
`npx playwright merge-reports path/to/blob-reports-dir` reads all blob reports from the passed directory and merges them into a single report.
When merging reports from different OS'es you'll have to provide an explicit merge config to disambiguate which directory should be used as tests root.
Supported options:
* `--reporter reporter-to-use`
Which report to produce. Can be multiple reporters separated by comma.
Example:
npx playwright merge-reports --reporter=html,github ./blob-reports
* `--config path/to/config/file`
Specifies the Playwright configuration file with output reporters. Use this option to pass additional configuration to the output reporter. This configuration file can differ from the one used during the creation of blob reports.
Example:
npx playwright merge-reports --config=merge.config.ts ./blob-reports
merge.config.ts
export default { testDir: 'e2e', reporter: [['html', { open: 'never' }]],};
# Timeouts
Timeouts
========
Playwright Test has multiple configurable timeouts for various tasks.
Timeout
Default
Description
Test timeout
30\_000 ms
Timeout for each test
Set in config
`{ timeout: 60_000 }`
Override in test
`test.setTimeout(120_000)`
Expect timeout
5\_000 ms
Timeout for each assertion
Set in config
`{ expect: { timeout: 10_000 } }`
Override in test
`expect(locator).toBeVisible({ timeout: 10_000 })`
Test timeout[](#test-timeout "Direct link to Test timeout")
------------------------------------------------------------
Playwright Test enforces a timeout for each test, 30 seconds by default. Time spent by the test function, fixture setups, and `beforeEach` hooks is included in the test timeout.
Timed out test produces the following error:
example.spec.ts:3:1 › basic test ===========================Timeout of 30000ms exceeded.
Additional separate timeout, of the same value, is shared between fixture teardowns and `afterEach` hooks, after the test function has finished.
The same timeout value also applies to `beforeAll` and `afterAll` hooks, but they do not share time with any test.
### Set test timeout in the config[](#set-test-timeout-in-the-config "Direct link to Set test timeout in the config")
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ timeout: 120_000,});
API reference: [testConfig.timeout](/docs/api/class-testconfig#test-config-timeout).
### Set timeout for a single test[](#set-timeout-for-a-single-test "Direct link to Set timeout for a single test")
example.spec.ts
import { test, expect } from '@playwright/test';test('slow test', async ({ page }) => { test.slow(); // Easy way to triple the default timeout // ...});test('very slow test', async ({ page }) => { test.setTimeout(120_000); // ...});
API reference: [test.setTimeout()](/docs/api/class-test#test-set-timeout) and [test.slow()](/docs/api/class-test#test-slow).
### Change timeout from a `beforeEach` hook[](#change-timeout-from-a-beforeeach-hook "Direct link to change-timeout-from-a-beforeeach-hook")
example.spec.ts
import { test, expect } from '@playwright/test';test.beforeEach(async ({ page }, testInfo) => { // Extend timeout for all tests running this hook by 30 seconds. testInfo.setTimeout(testInfo.timeout + 30_000);});
API reference: [testInfo.setTimeout()](/docs/api/class-testinfo#test-info-set-timeout).
### Change timeout for `beforeAll`/`afterAll` hook[](#change-timeout-for-beforeallafterall-hook "Direct link to change-timeout-for-beforeallafterall-hook")
`beforeAll` and `afterAll` hooks have a separate timeout, by default equal to test timeout. You can change it separately for each hook by calling [testInfo.setTimeout()](/docs/api/class-testinfo#test-info-set-timeout) inside the hook.
example.spec.ts
import { test, expect } from '@playwright/test';test.beforeAll(async () => { // Set timeout for this hook. test.setTimeout(60000);});
API reference: [testInfo.setTimeout()](/docs/api/class-testinfo#test-info-set-timeout).
Expect timeout[](#expect-timeout "Direct link to Expect timeout")
------------------------------------------------------------------
Auto-retrying assertions like [expect(locator).toHaveText()](/docs/api/class-locatorassertions#locator-assertions-to-have-text) have a separate timeout, 5 seconds by default. Assertion timeout is unrelated to the test timeout. It produces the following error:
example.spec.ts:3:1 › basic test ===========================Error: expect(received).toHaveText(expected)Expected string: "my text"Received string: ""Call log: - expect.toHaveText with timeout 5000ms - waiting for "locator('button')"
### Set expect timeout in the config[](#set-expect-timeout-in-the-config "Direct link to Set expect timeout in the config")
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ expect: { timeout: 10_000, },});
API reference: [testConfig.expect](/docs/api/class-testconfig#test-config-expect).
### Specify expect timeout for a single assertion[](#specify-expect-timeout-for-a-single-assertion "Direct link to Specify expect timeout for a single assertion")
example.spec.ts
import { test, expect } from '@playwright/test';test('example', async ({ page }) => { await expect(locator).toHaveText('hello', { timeout: 10_000 });});
Global timeout[](#global-timeout "Direct link to Global timeout")
------------------------------------------------------------------
Playwright Test supports a timeout for the whole test run. This prevents excess resource usage when everything went wrong. There is no default global timeout, but you can set a reasonable one in the config, for example one hour. Global timeout produces the following error:
Running 1000 tests using 10 workers 514 skipped 486 passed Timed out waiting 3600s for the entire test run
You can set global timeout in the config.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ globalTimeout: 3_600_000,});
API reference: [testConfig.globalTimeout](/docs/api/class-testconfig#test-config-global-timeout).
Advanced: low level timeouts[](#advanced-low-level-timeouts "Direct link to Advanced: low level timeouts")
-----------------------------------------------------------------------------------------------------------
These are the low-level timeouts that are pre-configured by the test runner, you should not need to change these. If you happen to be in this section because your test are flaky, it is very likely that you should be looking for the solution elsewhere.
Timeout
Default
Description
Action timeout
no timeout
Timeout for each action
Set in config
`{ use: { actionTimeout: 10_000 } }`
Override in test
`locator.click({ timeout: 10_000 })`
Navigation timeout
no timeout
Timeout for each navigation action
Set in config
`{ use: { navigationTimeout: 30_000 } }`
Override in test
`page.goto('/', { timeout: 30_000 })`
Global timeout
no timeout
Global timeout for the whole test run
Set in config
`{ globalTimeout: 3_600_000 }`
`beforeAll`/`afterAll` timeout
30\_000 ms
Timeout for the hook
Set in hook
`test.setTimeout(60_000)`
Fixture timeout
no timeout
Timeout for an individual fixture
Set in fixture
`{ scope: 'test', timeout: 30_000 }`
### Set action and navigation timeouts in the config[](#set-action-and-navigation-timeouts-in-the-config "Direct link to Set action and navigation timeouts in the config")
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ use: { actionTimeout: 10 * 1000, navigationTimeout: 30 * 1000, },});
API reference: [testOptions.actionTimeout](/docs/api/class-testoptions#test-options-action-timeout) and [testOptions.navigationTimeout](/docs/api/class-testoptions#test-options-navigation-timeout).
### Set timeout for a single action[](#set-timeout-for-a-single-action "Direct link to Set timeout for a single action")
example.spec.ts
import { test, expect } from '@playwright/test';test('basic test', async ({ page }) => { await page.goto('https://playwright.dev', { timeout: 30000 }); await page.getByText('Get Started').click({ timeout: 10000 });});
Fixture timeout[](#fixture-timeout "Direct link to Fixture timeout")
---------------------------------------------------------------------
By default, [fixture](/docs/test-fixtures) shares timeout with the test. However, for slow fixtures, especially [worker-scoped](/docs/test-fixtures#worker-scoped-fixtures) ones, it is convenient to have a separate timeout. This way you can keep the overall test timeout small, and give the slow fixture more time.
example.spec.ts
import { test as base, expect } from '@playwright/test';const test = base.extend<{ slowFixture: string }>({ slowFixture: [async ({}, use) => { // ... perform a slow operation ... await use('hello'); }, { timeout: 60_000 }]});test('example test', async ({ slowFixture }) => { // ...});
API reference: [test.extend()](/docs/api/class-test#test-extend).
# TypeScript
TypeScript
==========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright supports TypeScript out of the box. You just write tests in TypeScript, and Playwright will read them, transform to JavaScript and run.
Note that Playwright does not check the types and will run tests even if there are non-critical TypeScript compilation errors. We recommend you run TypeScript compiler alongside Playwright. For example on GitHub actions:
jobs: test: runs-on: ubuntu-latest steps: ... - name: Run type checks run: npx tsc -p tsconfig.json --noEmit - name: Run Playwright tests run: npx playwright test
For local development, you can run `tsc` in [watch](https://www.typescriptlang.org/docs/handbook/configuring-watch.html) mode like this:
npx tsc -p tsconfig.json --noEmit -w
tsconfig.json[](#tsconfigjson "Direct link to tsconfig.json")
--------------------------------------------------------------
Playwright will pick up `tsconfig.json` for each source file it loads. Note that Playwright **only supports** the following tsconfig options: `allowJs`, `baseUrl`, `paths` and `references`.
We recommend setting up a separate `tsconfig.json` in the tests directory so that you can change some preferences specifically for the tests. Here is an example directory structure.
src/ source.tstests/ tsconfig.json # test-specific tsconfig example.spec.tstsconfig.json # generic tsconfig for all typescript sourcesplaywright.config.ts
### tsconfig path mapping[](#tsconfig-path-mapping "Direct link to tsconfig path mapping")
Playwright supports [path mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) declared in the `tsconfig.json`. Make sure that `baseUrl` is also set.
Here is an example `tsconfig.json` that works with Playwright:
tsconfig.json
{ "compilerOptions": { "baseUrl": ".", "paths": { "@myhelper/*": ["packages/myhelper/*"] // This mapping is relative to "baseUrl". } }}
You can now import using the mapped paths:
example.spec.ts
import { test, expect } from '@playwright/test';import { username, password } from '@myhelper/credentials';test('example', async ({ page }) => { await page.getByLabel('User Name').fill(username); await page.getByLabel('Password').fill(password);});
### tsconfig resolution[](#tsconfig-resolution "Direct link to tsconfig resolution")
By default, Playwright will look up a closest tsconfig for each imported file by going up the directory structure and looking for `tsconfig.json` or `jsconfig.json`. This way, you can create a `tests/tsconfig.json` file that will be used only for your tests and Playwright will pick it up automatically.
# Playwright will choose tsconfig automaticallynpx playwright test
Alternatively, you can specify a single tsconfig file to use in the command line, and Playwright will use it for all imported files, not only test files.
# Pass a specific tsconfignpx playwright test --tsconfig=tsconfig.test.json
You can specify a single tsconfig file in the config file, that will be used for loading test files, reporters, etc. However, it will not be used while loading the playwright config itself or any files imported from it.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ tsconfig: './tsconfig.test.json',});
Manually compile tests with TypeScript[](#manually-compile-tests-with-typescript "Direct link to Manually compile tests with TypeScript")
------------------------------------------------------------------------------------------------------------------------------------------
Sometimes, Playwright Test will not be able to transform your TypeScript code correctly, for example when you are using experimental or very recent features of TypeScript, usually configured in `tsconfig.json`.
In this case, you can perform your own TypeScript compilation before sending the tests to Playwright.
First add a `tsconfig.json` file inside the tests directory:
{ "compilerOptions": { "target": "ESNext", "module": "commonjs", "moduleResolution": "Node", "sourceMap": true, "outDir": "../tests-out", }}
In `package.json`, add two scripts:
{ "scripts": { "pretest": "tsc --incremental -p tests/tsconfig.json", "test": "playwright test -c tests-out" }}
The `pretest` script runs typescript on the tests. `test` will run the tests that have been generated to the `tests-out` directory. The `-c` argument configures the test runner to look for tests inside the `tests-out` directory.
Then `npm run test` will build the tests and run them.
# UI Mode
UI Mode
=======
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
UI Mode lets you explore, run, and debug tests with a time travel experience complete with a watch mode. All test files are displayed in the testing sidebar, allowing you to expand each file and describe block to individually run, view, watch, and debug each test. Filter tests by **name**, [**projects**](/docs/test-projects) (set in your `playwright.config` file), **@tag**, or by the execution status of **passed**, **failed**, and **skipped**. See a full trace of your tests and hover back and forward over each action to see what was happening during each step. You can also pop out the DOM snapshot of a given moment into a separate window for a better debugging experience.
Opening UI Mode[](#opening-ui-mode "Direct link to Opening UI Mode")
---------------------------------------------------------------------
To open UI mode, run the following command in your terminal:
npx playwright test --ui
Running your tests[](#running-your-tests "Direct link to Running your tests")
------------------------------------------------------------------------------
Once you launch UI Mode you will see a list of all your test files. You can run all your tests by clicking the triangle icon in the sidebar. You can also run a single test file, a block of tests or a single test by hovering over the name and clicking on the triangle next to it.
Filtering tests[](#filtering-tests "Direct link to Filtering tests")
---------------------------------------------------------------------
Filter tests by text or `@tag` or by passed, failed or skipped tests. You can also filter by [projects](/docs/test-projects) as set in your `playwright.config` file. If you are using project dependencies make sure to run your setup tests first before running the tests that depend on them. The UI mode will not take into consideration the setup tests and therefore you will have to manually run them first.
Timeline view[](#timeline-view "Direct link to Timeline view")
---------------------------------------------------------------
At the top of the trace you can see a timeline view of your test with different colors to highlight navigation and actions. Hover back and forth to see an image snapshot for each action. Double click on an action to see the time range for that action. You can use the slider in the timeline to increase the actions selected and these will be shown in the Actions tab and all console logs and network logs will be filtered to only show the logs for the actions selected.
Actions[](#actions "Direct link to Actions")
---------------------------------------------
In the Actions tab you can see what locator was used for every action and how long each one took to run. Hover over each action of your test and visually see the change in the DOM snapshot. Go back and forward in time and click an action to inspect and debug. Use the Before and After tabs to visually see what happened before and after the action. 
Pop out and inspect the DOM[](#pop-out-and-inspect-the-dom "Direct link to Pop out and inspect the DOM")
---------------------------------------------------------------------------------------------------------
Pop out the DOM snapshot into its own window for a better debugging experience by clicking on the pop out icon above the DOM snapshot. From there you can open the browser DevTools and inspect the HTML, CSS, Console etc. Go back to UI Mode and click on another action and pop that one out to easily compare the two side by side or debug each individually.
Pick locator[](#pick-locator "Direct link to Pick locator")
------------------------------------------------------------
Click on the pick locator button and hover over the DOM snapshot to see the locator for each element highlighted as you hover. Click on an element to add the locator playground. You can modify the locator in the playground and see if your modified locator matches any locators in the DOM snapshot. Once you are satisfied with the locator you can use the copy button to copy the locator and paste it into your test.
Source[](#source "Direct link to Source")
------------------------------------------
As you hover over each action of your test the line of code for that action is highlighted in the source panel. The button "Open in VSCode" is at the top-right of this section. Upon clicking the button, it will open your test in VS Code right at the line of code that you clicked on.
Call[](#call "Direct link to Call")
------------------------------------
The call tab shows you information about the action such as the time it took, what locator was used, if in strict mode and what key was used.
Log[](#log "Direct link to Log")
---------------------------------
See a full log of your test to better understand what Playwright is doing behind the scenes such as scrolling into view, waiting for element to be visible, enabled and stable and performing actions such as click, fill, press etc.
Errors[](#errors "Direct link to Errors")
------------------------------------------
If your test fails you will see the error messages for each test in the Errors tab. The timeline will also show a red line highlighting where the error occurred. You can also click on the source tab to see on which line of the source code the error is.
Console[](#console "Direct link to Console")
---------------------------------------------
See console logs from the browser as well as from your test. Different icons are displayed to show you if the console log came from the browser or from the test file.
Network[](#network "Direct link to Network")
---------------------------------------------
The Network tab shows you all the network requests that were made during your test. You can sort by different types of requests, status code, method, request, content type, duration and size. Click on a request to see more information about it such as the request headers, response headers, request body and response body.
Attachments[](#attachments "Direct link to Attachments")
---------------------------------------------------------
The "Attachments" tab allows you to explore attachments. If you're doing [visual regression testing](/docs/test-snapshots), you'll be able to compare screenshots by examining the image diff, the actual image and the expected image. When you click on the expected image you can use the slider to slide one image over the other so you can easily see the differences in your screenshots.
Metadata[](#metadata "Direct link to Metadata")
------------------------------------------------
Next to the Actions tab you will find the Metadata tab which will show you more information on your test such as the Browser, viewport size, test duration and more.
Watch mode[](#watch-mode "Direct link to Watch mode")
------------------------------------------------------
Next to the name of each test in the sidebar you will find an eye icon. Clicking on the icon will activate watch mode which will re-run the test when you make changes to it. You can watch a number of tests at the same time be clicking the eye icon next to each one or all tests by clicking the eye icon at the top of the sidebar.
Docker & GitHub Codespaces[](#docker--github-codespaces "Direct link to Docker & GitHub Codespaces")
-----------------------------------------------------------------------------------------------------
For Docker and GitHub Codespaces environments, you can run UI mode in the browser. In order for an endpoint to be accessible outside of the container, it needs to be bound to the `0.0.0.0` interface:
npx playwright test --ui-host=0.0.0.0
In the case of GitHub Codespaces, the port gets [forwarded automatically](https://docs.github.com/en/codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace#about-forwarded-ports), so you can open UI mode in the browser by clicking on the link in the terminal.
To have a static port, you can pass the `--ui-port` flag:
npx playwright test --ui-port=8080 --ui-host=0.0.0.0
note
Be aware that when specifying the `--ui-host=0.0.0.0` flag, UI Mode with your traces, the passwords and secrets is accessible from other machines inside your network. In the case of GitHub Codespaces, the ports are only accessible from your account by default.
# Web server
Web server
==========
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright comes with a `webserver` option in the config file which gives you the ability to launch a local dev server before running your tests. This is ideal for when writing your tests during development and when you don't have a staging or production url to test against.
Configuring a web server[](#configuring-a-web-server "Direct link to Configuring a web server")
------------------------------------------------------------------------------------------------
Use the `webserver` property in your Playwright config to launch a development web server during the tests.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Run your local dev server before starting the tests webServer: { command: 'npm run start', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, stdout: 'ignore', stderr: 'pipe', },});
Property
Description
[testConfig.webServer](/docs/api/class-testconfig#test-config-web-server)
Launch a development web server (or multiple) during the tests.
`command`
Shell command to start the local dev server of your app.
`cwd`
Current working directory of the spawned process, defaults to the directory of the configuration file.
`env`
Environment variables for the command. Defaults to inheriting `process.env` with `PLAYWRIGHT_TEST=1` added.
`gracefulShutdown`
How to shut down the process. If unspecified, the process group is forcefully `SIGKILL`ed. If set to `{ signal: 'SIGTERM', timeout: 500 }`, the process group is sent a `SIGTERM` signal, followed by `SIGKILL` if it doesn't exit within 500ms. You can also use `SIGINT` as the signal instead. A `0` timeout means no `SIGKILL` will be sent. Windows doesn't support `SIGTERM` and `SIGINT` signals, so this option is ignored on Windows. Note that shutting down a Docker container requires `SIGTERM`.
`ignoreHTTPSErrors`
Whether to ignore HTTPS errors when fetching the `url`. Defaults to `false`.
`name`
Specifies a custom name for the web server. This name will be prefixed to log messages. Defaults to `[WebServer]`.
`reuseExistingServer`
If `true`, it will re-use an existing server on the url when available. If no server is running on that url, it will run the command to start a new server. If `false`, it will throw if an existing process is listening on the url. To see the stdout, you can set the `DEBUG=pw:webserver` environment variable.
`stderr`
Whether to pipe the stderr of the command to the process stderr or ignore it. Defaults to `"pipe"`.
`stdout`
If `"pipe"`, it will pipe the stdout of the command to the process stdout. If `"ignore"`, it will ignore the stdout of the command. Default to `"ignore"`.
`timeout`
How long to wait for the process to start up and be available in milliseconds. Defaults to 60000.
`url`
URL of your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections.
Adding a server timeout[](#adding-a-server-timeout "Direct link to Adding a server timeout")
---------------------------------------------------------------------------------------------
Webservers can sometimes take longer to boot up. In this case, you can increase the timeout to wait for the server to start.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Rest of your config... // Run your local dev server before starting the tests webServer: { command: 'npm run start', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, timeout: 120 * 1000, },});
Adding a baseURL[](#adding-a-baseurl "Direct link to Adding a baseURL")
------------------------------------------------------------------------
It is also recommended to specify the `baseURL` in the `use: {}` section of your config, so that tests can use relative urls and you don't have to specify the full URL over and over again.
When using [page.goto()](/docs/api/class-page#page-goto), [page.route()](/docs/api/class-page#page-route), [page.waitForURL()](/docs/api/class-page#page-wait-for-url), [page.waitForRequest()](/docs/api/class-page#page-wait-for-request), or [page.waitForResponse()](/docs/api/class-page#page-wait-for-response) it takes the base URL in consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. For Example, by setting the baseURL to `http://localhost:3000` and navigating to `/login` in your tests, Playwright will run the test using `http://localhost:3000/login`.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ // Rest of your config... // Run your local dev server before starting the tests webServer: { command: 'npm run start', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, }, use: { baseURL: 'http://localhost:3000', },});
Now you can use a relative path when navigating the page:
test.spec.ts
import { test } from '@playwright/test';test('test', async ({ page }) => { // This will navigate to http://localhost:3000/login await page.goto('./login');});
Multiple web servers[](#multiple-web-servers "Direct link to Multiple web servers")
------------------------------------------------------------------------------------
Multiple web servers (or background processes) can be launched simultaneously by providing an array of `webServer` configurations. See [testConfig.webServer](/docs/api/class-testconfig#test-config-web-server) for more info.
playwright.config.ts
import { defineConfig } from '@playwright/test';export default defineConfig({ webServer: [ { command: 'npm run start', url: 'http://localhost:3000', name: 'Frontend', timeout: 120 * 1000, reuseExistingServer: !process.env.CI, }, { command: 'npm run backend', url: 'http://localhost:3333', name: 'Backend', timeout: 120 * 1000, reuseExistingServer: !process.env.CI, } ], use: { baseURL: 'http://localhost:3000', },});
# Library
Library
=======
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright Library provides unified APIs for launching and interacting with browsers, while Playwright Test provides all this plus a fully managed end-to-end Test Runner and experience.
Under most circumstances, for end-to-end testing, you'll want to use `@playwright/test` (Playwright Test), and not `playwright` (Playwright Library) directly. To get started with Playwright Test, follow the [Getting Started Guide](/docs/intro).
Differences when using library[](#differences-when-using-library "Direct link to Differences when using library")
------------------------------------------------------------------------------------------------------------------
### Library Example[](#library-example "Direct link to Library Example")
The following is an example of using the Playwright Library directly to launch Chromium, go to a page, and check its title:
* TypeScript
* JavaScript
import { chromium, devices } from 'playwright';import assert from 'node:assert';(async () => { // Setup const browser = await chromium.launch(); const context = await browser.newContext(devices['iPhone 11']); const page = await context.newPage(); // The actual interesting bit await context.route('**.jpg', route => route.abort()); await page.goto('https://example.com/'); assert(await page.title() === 'Example Domain'); // 👎 not a Web First assertion // Teardown await context.close(); await browser.close();})();
const assert = require('node:assert');const { chromium, devices } = require('playwright');(async () => { // Setup const browser = await chromium.launch(); const context = await browser.newContext(devices['iPhone 11']); const page = await context.newPage(); // The actual interesting bit await context.route('**.jpg', route => route.abort()); await page.goto('https://example.com/'); assert(await page.title() === 'Example Domain'); // 👎 not a Web First assertion // Teardown await context.close(); await browser.close();})();
Run it with `node my-script.js`.
### Test Example[](#test-example "Direct link to Test Example")
A test to achieve similar behavior, would look like:
* TypeScript
* JavaScript
import { expect, test, devices } from '@playwright/test';test.use(devices['iPhone 11']);test('should be titled', async ({ page, context }) => { await context.route('**.jpg', route => route.abort()); await page.goto('https://example.com/'); await expect(page).toHaveTitle('Example');});
const { expect, test, devices } = require('@playwright/test');test.use(devices['iPhone 11']);test('should be titled', async ({ page, context }) => { await context.route('**.jpg', route => route.abort()); await page.goto('https://example.com/'); await expect(page).toHaveTitle('Example');});
Run it with `npx playwright test`.
### Key Differences[](#key-differences "Direct link to Key Differences")
The key differences to note are as follows:
Library
Test
Installation
`npm install playwright`
`npm init playwright@latest` - note `install` vs. `init`
Install browsers
Install `@playwright/browser-chromium`, `@playwright/browser-firefox` and/or `@playwright/browser-webkit`
`npx playwright install` or `npx playwright install chromium` for a single one
`import` from
`playwright`
`@playwright/test`
Initialization
Explicitly need to:
1. Pick a browser to use, e.g. `chromium`
2. Launch browser with [browserType.launch()](/docs/api/class-browsertype#browser-type-launch)
3. Create a context with [browser.newContext()](/docs/api/class-browser#browser-new-context), _and_ pass any context options explicitly, e.g. `devices['iPhone 11']`
4. Create a page with [browserContext.newPage()](/docs/api/class-browsercontext#browser-context-new-page)
An isolated `page` and `context` are provided to each test out-of the box, along with other [built-in fixtures](/docs/test-fixtures#built-in-fixtures). No explicit creation. If referenced by the test in its arguments, the Test Runner will create them for the test. (i.e. lazy-initialization)
Assertions
No built-in Web-First Assertions
[Web-First assertions](/docs/test-assertions) like:
* [expect(page).toHaveTitle()](/docs/api/class-pageassertions#page-assertions-to-have-title)
* [expect(page).toHaveScreenshot()](/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1)
which auto-wait and retry for the condition to be met.
Timeouts
Defaults to 30s for most operations.
Most operations don't time out, but every test has a timeout that makes it fail (30s by default).
Cleanup
Explicitly need to:
1. Close context with [browserContext.close()](/docs/api/class-browsercontext#browser-context-close)
2. Close browser with [browser.close()](/docs/api/class-browser#browser-close)
No explicit close of [built-in fixtures](/docs/test-fixtures#built-in-fixtures); the Test Runner will take care of it.
Running
When using the Library, you run the code as a node script, possibly with some compilation first.
When using the Test Runner, you use the `npx playwright test` command. Along with your [config](/docs/test-configuration), the Test Runner handles any compilation and choosing what to run and how to run it.
In addition to the above, Playwright Test, as a full-featured Test Runner, includes:
* [Configuration Matrix and Projects](/docs/test-configuration): In the above example, in the Playwright Library version, if we wanted to run with a different device or browser, we'd have to modify the script and plumb the information through. With Playwright Test, we can just specify the [matrix of configurations](/docs/test-configuration) in one place, and it will create run the one test under each of these configurations.
* [Parallelization](/docs/test-parallel)
* [Web-First Assertions](/docs/test-assertions)
* [Reporting](/docs/test-reporters)
* [Retries](/docs/test-retries)
* [Easily Enabled Tracing](/docs/trace-viewer-intro)
* and more…
Usage[](#usage "Direct link to Usage")
---------------------------------------
Use npm or Yarn to install Playwright library in your Node.js project. See [system requirements](/docs/intro#system-requirements).
npm i -D playwright
You will also need to install browsers - either manually or by adding a package that will do it for you automatically.
# Download the Chromium, Firefox and WebKit browsernpx playwright install chromium firefox webkit# Alternatively, add packages that will download a browser upon npm installnpm i -D @playwright/browser-chromium @playwright/browser-firefox @playwright/browser-webkit
See [managing browsers](/docs/browsers#managing-browser-binaries) for more options.
Once installed, you can import Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
const { chromium } = require('playwright');(async () => { const browser = await chromium.launch(); // Create pages, interact with UI elements, assert values await browser.close();})();
Playwright APIs are asynchronous and return Promise objects. Our code examples use [the async/await pattern](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) to ease readability. The code is wrapped in an unnamed async arrow function which is invoking itself.
(async () => { // Start of async arrow function // Function code // ...})(); // End of the function and () to invoke itself
First script[](#first-script "Direct link to First script")
------------------------------------------------------------
In our first script, we will navigate to `https://playwright.dev/` and take a screenshot in WebKit.
const { webkit } = require('playwright');(async () => { const browser = await webkit.launch(); const page = await browser.newPage(); await page.goto('https://playwright.dev/'); await page.screenshot({ path: `example.png` }); await browser.close();})();
By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution. Learn more in the debugging tools [section](/docs/debug).
firefox.launch({ headless: false, slowMo: 50 });
Record scripts[](#record-scripts "Direct link to Record scripts")
------------------------------------------------------------------
[Command line tools](/docs/test-cli) can be used to record user interactions and generate JavaScript code.
npx playwright codegen wikipedia.org
Browser downloads[](#browser-downloads "Direct link to Browser downloads")
---------------------------------------------------------------------------
To download Playwright browsers run:
# Explicitly download browsersnpx playwright install
Alternatively, you can add `@playwright/browser-chromium`, `@playwright/browser-firefox` and `@playwright/browser-webkit` packages to automatically download the respective browser during the package installation.
# Use a helper package that downloads a browser on npm installnpm install @playwright/browser-chromium
**Download behind a firewall or a proxy**
Pass `HTTPS_PROXY` environment variable to download through a proxy.
* Bash
* PowerShell
* Batch
# ManualHTTPS_PROXY=https://192.0.2.1 npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesHTTPS_PROXY=https://192.0.2.1 npm install
# Manual$Env:HTTPS_PROXY=https://192.0.2.1npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packages$Env:HTTPS_PROXY=https://192.0.2.1npm install
# Manualset HTTPS_PROXY=https://192.0.2.1npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesset HTTPS_PROXY=https://192.0.2.1npm install
**Download from artifact repository**
By default, Playwright downloads browsers from Microsoft's CDN. Pass `PLAYWRIGHT_DOWNLOAD_HOST` environment variable to download from an internal artifacts repository instead.
* Bash
* PowerShell
* Batch
# ManualPLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesPLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install
# Manual$Env:PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packages$Env:PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1npm install
# Manualset PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1npx playwright install# Through @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesset PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1npm install
**Skip browser download**
In certain cases, it is desired to avoid browser downloads altogether because browser binaries are managed separately. This can be done by setting `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` variable before installing packages.
* Bash
* PowerShell
* Batch
# When using @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesPLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
# When using @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packages$Env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1npm install
# When using @playwright/browser-chromium, @playwright/browser-firefox# and @playwright/browser-webkit helper packagesset PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1npm install
TypeScript support[](#typescript-support "Direct link to TypeScript support")
------------------------------------------------------------------------------
Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.
### In JavaScript[](#in-javascript "Direct link to In JavaScript")
Add the following to the top of your JavaScript file to get type-checking in VS Code or WebStorm.
// @ts-check// ...
Alternatively, you can use JSDoc to set types for variables.
/** @type {import('playwright').Page} */let page;
### In TypeScript[](#in-typescript "Direct link to In TypeScript")
TypeScript support will work out-of-the-box. Types can also be imported explicitly.
let page: import('playwright').Page;
# Accessibility testing
Accessibility testing
=====================
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright can be used to test your application for many types of accessibility issues.
A few examples of problems this can catch include:
* Text that would be hard to read for users with vision impairments due to poor color contrast with the background behind it
* UI controls and form elements without labels that a screen reader could identify
* Interactive elements with duplicate IDs which can confuse assistive technologies
The following examples rely on the [`@axe-core/playwright`](https://npmjs.org/@axe-core/playwright) package which adds support for running the [axe accessibility testing engine](https://www.deque.com/axe/) as part of your Playwright tests.
Disclaimer
Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.
For manual assessments, we recommend [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/?referrer=playwright-accessibility-testing-js), a free and open source dev tool that walks you through assessing a website for [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aaa) coverage.
Example accessibility tests[](#example-accessibility-tests "Direct link to Example accessibility tests")
---------------------------------------------------------------------------------------------------------
Accessibility tests work just like any other Playwright test. You can either create separate test cases for them, or integrate accessibility scans and assertions into your existing test cases.
The following examples demonstrate a few basic accessibility testing scenarios.
### Scanning an entire page[](#scanning-an-entire-page "Direct link to Scanning an entire page")
This example demonstrates how to test an entire page for automatically detectable accessibility violations. The test:
1. Imports the `@axe-core/playwright` package
2. Uses normal Playwright Test syntax to define a test case
3. Uses normal Playwright syntax to navigate to the page under test
4. Awaits `AxeBuilder.analyze()` to run the accessibility scan against the page
5. Uses normal Playwright Test [assertions](/docs/test-assertions) to verify that there are no violations in the returned scan results
* TypeScript
* JavaScript
import { test, expect } from '@playwright/test';import AxeBuilder from '@axe-core/playwright'; // 1test.describe('homepage', () => { // 2 test('should not have any automatically detectable accessibility issues', async ({ page }) => { await page.goto('https://your-site.com/'); // 3 const accessibilityScanResults = await new AxeBuilder({ page }).analyze(); // 4 expect(accessibilityScanResults.violations).toEqual([]); // 5 });});
const { test, expect } = require('@playwright/test');const AxeBuilder = require('@axe-core/playwright').default; // 1test.describe('homepage', () => { // 2 test('should not have any automatically detectable accessibility issues', async ({ page }) => { await page.goto('https://your-site.com/'); // 3 const accessibilityScanResults = await new AxeBuilder({ page }).analyze(); // 4 expect(accessibilityScanResults.violations).toEqual([]); // 5 });});
### Configuring axe to scan a specific part of a page[](#configuring-axe-to-scan-a-specific-part-of-a-page "Direct link to Configuring axe to scan a specific part of a page")
`@axe-core/playwright` supports many configuration options for axe. You can specify these options by using a Builder pattern with the `AxeBuilder` class.
For example, you can use [`AxeBuilder.include()`](https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md#axebuilderincludeselector-string--string) to constrain an accessibility scan to only run against one specific part of a page.
`AxeBuilder.analyze()` will scan the page _in its current state_ when you call it. To scan parts of a page that are revealed based on UI interactions, use [Locators](/docs/locators) to interact with the page before invoking `analyze()`:
test('navigation menu should not have automatically detectable accessibility violations', async ({ page,}) => { await page.goto('https://your-site.com/'); await page.getByRole('button', { name: 'Navigation Menu' }).click(); // It is important to waitFor() the page to be in the desired // state *before* running analyze(). Otherwise, axe might not // find all the elements your test expects it to scan. await page.locator('#navigation-menu-flyout').waitFor(); const accessibilityScanResults = await new AxeBuilder({ page }) .include('#navigation-menu-flyout') .analyze(); expect(accessibilityScanResults.violations).toEqual([]);});
### Scanning for WCAG violations[](#scanning-for-wcag-violations "Direct link to Scanning for WCAG violations")
By default, axe checks against a wide variety of accessibility rules. Some of these rules correspond to specific success criteria from the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG21/), and others are "best practice" rules that are not specifically required by any WCAG criterion.
You can constrain an accessibility scan to only run those rules which are "tagged" as corresponding to specific WCAG success criteria by using [`AxeBuilder.withTags()`](https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md#axebuilderwithtagstags-stringarray). For example, [Accessibility Insights for Web's Automated Checks](https://accessibilityinsights.io/docs/web/getstarted/fastpass/?referrer=playwright-accessibility-testing-js) only include axe rules that test for violations of WCAG A and AA success criteria; to match that behavior, you would use the tags `wcag2a`, `wcag2aa`, `wcag21a`, and `wcag21aa`.
Note that automated testing cannot detect all types of WCAG violations.
test('should not have any automatically detectable WCAG A or AA violations', async ({ page }) => { await page.goto('https://your-site.com/'); const accessibilityScanResults = await new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) .analyze(); expect(accessibilityScanResults.violations).toEqual([]);});
You can find a complete listing of the rule tags axe-core supports in [the "Axe-core Tags" section of the axe API documentation](https://www.deque.com/axe/core-documentation/api-documentation/#axecore-tags).
Handling known issues[](#handling-known-issues "Direct link to Handling known issues")
---------------------------------------------------------------------------------------
A common question when adding accessibility tests to an application is "how do I suppress known violations?" The following examples demonstrate a few techniques you can use.
### Excluding individual elements from a scan[](#excluding-individual-elements-from-a-scan "Direct link to Excluding individual elements from a scan")
If your application contains a few specific elements with known issues, you can use [`AxeBuilder.exclude()`](https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md#axebuilderexcludeselector-string--string) to exclude them from being scanned until you're able to fix the issues.
This is usually the simplest option, but it has some important downsides:
* `exclude()` will exclude the specified elements _and all of their descendants_. Avoid using it with components that contain many children.
* `exclude()` will prevent _all_ rules from running against the specified elements, not just the rules corresponding to known issues.
Here is an example of excluding one element from being scanned in one specific test:
test('should not have any accessibility violations outside of elements with known issues', async ({ page,}) => { await page.goto('https://your-site.com/page-with-known-issues'); const accessibilityScanResults = await new AxeBuilder({ page }) .exclude('#element-with-known-issue') .analyze(); expect(accessibilityScanResults.violations).toEqual([]);});
If the element in question is used repeatedly in many pages, consider [using a test fixture](#using-a-test-fixture-for-common-axe-configuration) to reuse the same `AxeBuilder` configuration across multiple tests.
### Disabling individual scan rules[](#disabling-individual-scan-rules "Direct link to Disabling individual scan rules")
If your application contains many different preexisting violations of a specific rule, you can use [`AxeBuilder.disableRules()`](https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md#axebuilderdisablerulesrules-stringarray) to temporarily disable individual rules until you're able to fix the issues.
You can find the rule IDs to pass to `disableRules()` in the `id` property of the violations you want to suppress. A [complete list of axe's rules](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) can be found in `axe-core`'s documentation.
test('should not have any accessibility violations outside of rules with known issues', async ({ page,}) => { await page.goto('https://your-site.com/page-with-known-issues'); const accessibilityScanResults = await new AxeBuilder({ page }) .disableRules(['duplicate-id']) .analyze(); expect(accessibilityScanResults.violations).toEqual([]);});
### Using snapshots to allow specific known issues[](#using-snapshots-to-allow-specific-known-issues "Direct link to Using snapshots to allow specific known issues")
If you would like to allow for a more granular set of known issues, you can use [Snapshots](/docs/test-snapshots) to verify that a set of preexisting violations has not changed. This approach avoids the downsides of using `AxeBuilder.exclude()` at the cost of slightly more complexity and fragility.
Do not use a snapshot of the entire `accessibilityScanResults.violations` array. It contains implementation details of the elements in question, such as a snippet of their rendered HTML; if you include these in your snapshots, it will make your tests prone to breaking every time one of the components in question changes for an unrelated reason:
// Don't do this! This is fragile.expect(accessibilityScanResults.violations).toMatchSnapshot();
Instead, create a _fingerprint_ of the violation(s) in question that contains only enough information to uniquely identify the issue, and use a snapshot of the fingerprint:
// This is less fragile than snapshotting the entire violations array.expect(violationFingerprints(accessibilityScanResults)).toMatchSnapshot();// my-test-utils.jsfunction violationFingerprints(accessibilityScanResults) { const violationFingerprints = accessibilityScanResults.violations.map(violation => ({ rule: violation.id, // These are CSS selectors which uniquely identify each element with // a violation of the rule in question. targets: violation.nodes.map(node => node.target), })); return JSON.stringify(violationFingerprints, null, 2);}
Exporting scan results as a test attachment[](#exporting-scan-results-as-a-test-attachment "Direct link to Exporting scan results as a test attachment")
---------------------------------------------------------------------------------------------------------------------------------------------------------
Most accessibility tests are primarily concerned with the `violations` property of the axe scan results. However, the scan results contain more than just `violations`. For example, the results also contain information about rules which passed and about elements which axe found to have inconclusive results for some rules. This information can be useful for debugging tests that aren't detecting all the violations you expect them to.
To include _all_ of the scan results as part of your test results for debugging purposes, you can add the scan results as a test attachment with [`testInfo.attach()`](/docs/api/class-testinfo#test-info-attach). [Reporters](/docs/test-reporters) can then embed or link the full results as part of your test output.
The following example demonstrates attaching scan results to a test:
test('example with attachment', async ({ page }, testInfo) => { await page.goto('https://your-site.com/'); const accessibilityScanResults = await new AxeBuilder({ page }).analyze(); await testInfo.attach('accessibility-scan-results', { body: JSON.stringify(accessibilityScanResults, null, 2), contentType: 'application/json' }); expect(accessibilityScanResults.violations).toEqual([]);});
Using a test fixture for common axe configuration[](#using-a-test-fixture-for-common-axe-configuration "Direct link to Using a test fixture for common axe configuration")
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[Test fixtures](/docs/test-fixtures) are a good way to share common `AxeBuilder` configuration across many tests. Some scenarios where this might be useful include:
* Using a common set of rules among all of your tests
* Suppressing a known violation in a common element which appears in many different pages
* Attaching standalone accessibility reports consistently for many scans
The following example demonstrates creating and using a test fixture that covers each of those scenarios.
### Creating a fixture[](#creating-a-fixture "Direct link to Creating a fixture")
This example fixture creates an `AxeBuilder` object which is pre-configured with shared `withTags()` and `exclude()` configuration.
* TypeScript
* JavaScript
axe-test.ts
import { test as base } from '@playwright/test';import AxeBuilder from '@axe-core/playwright';type AxeFixture = { makeAxeBuilder: () => AxeBuilder;};// Extend base test by providing "makeAxeBuilder"//// This new "test" can be used in multiple test files, and each of them will get// a consistently configured AxeBuilder instance.export const test = base.extend({ makeAxeBuilder: async ({ page }, use) => { const makeAxeBuilder = () => new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) .exclude('#commonly-reused-element-with-known-issue'); await use(makeAxeBuilder); }});export { expect } from '@playwright/test';
axe-test.js
const base = require('@playwright/test');const AxeBuilder = require('@axe-core/playwright').default;// Extend base test by providing "makeAxeBuilder"//// This new "test" can be used in multiple test files, and each of them will get// a consistently configured AxeBuilder instance.exports.test = base.test.extend({ makeAxeBuilder: async ({ page }, use) => { const makeAxeBuilder = () => new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']) .exclude('#commonly-reused-element-with-known-issue'); await use(makeAxeBuilder); }});exports.expect = base.expect;
### Using a fixture[](#using-a-fixture "Direct link to Using a fixture")
To use the fixture, replace the earlier examples' `new AxeBuilder({ page })` with the newly defined `makeAxeBuilder` fixture:
const { test, expect } = require('./axe-test');test('example using custom fixture', async ({ page, makeAxeBuilder }) => { await page.goto('https://your-site.com/'); const accessibilityScanResults = await makeAxeBuilder() // Automatically uses the shared AxeBuilder configuration, // but supports additional test-specific configuration too .include('#specific-element-under-test') .analyze(); expect(accessibilityScanResults.violations).toEqual([]);});
# Actions
Actions
=======
Introduction[](#introduction "Direct link to Introduction")
------------------------------------------------------------
Playwright can interact with HTML Input elements such as text inputs, checkboxes, radio buttons, select options, mouse clicks, type characters, keys and shortcuts as well as upload files and focus elements.
Text input[](#text-input "Direct link to Text input")
------------------------------------------------------
Using [locator.fill()](/docs/api/class-locator#locator-fill) is the easiest way to fill out the form fields. It focuses the element and triggers an `input` event with the entered text. It works for `