Update Playwright to latest version
npm: npm install -D @playwright/test@latest yarn: yarn add --dev @playwright/test@latest pnpm: pnpm install --save-dev @playwright/test@latest
configuration
165 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Keep Playwright dependency up to date
Keep Playwright version up to date to test on the latest browser versions and catch failures before the latest browser version is released to the public. Check release notes to see what the latest version is and what changes have been released.
Check Playwright version
npm: npx playwright --version yarn: yarn playwright --version pnpm: pnpm exec playwright --version
Test across all browsers
Playwright makes it easy to test your site across all browsers regardless of platform. Testing across all browsers ensures your app works for all users. In the config file, set up projects with the name and which browser or device to use.
Configure multiple browser projects example
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'] }, }, ], });
BFCache restoration not supported
Testing BFCache restorations is not supported in Playwright. A BFCache restore skips the network fetch phase, so the browser does not fire standard navigation lifecycle events such as commit, domcontentloaded, or load. Playwright's internal Page state relies heavily on these network-level events to stay synchronized. Triggering a BFCache restore (such as via page.goBack()) will bypass Playwright's lifecycle tracking, resulting in timeouts and a completely desynchronized Page object where subsequent interactions will fail.
BFCache disabled by default in Playwright
Playwright disables the Back/Forward Cache (BFCache) across all browsers by default to ensure consistent, clean testing environments.
Playwright Test TypeScript support
Playwright Test provides full zero-configuration TypeScript support.
networkidle replaces networkidle2
In Playwright's page.goto() waitUntil option, use 'networkidle' instead of Puppeteer's 'networkidle2'. In most cases, the explicit network idle wait is not useful thanks to auto-waiting.
Playwright Test cross-browser and cross-platform
Playwright Test runs tests across all web engines (Chrome, Firefox, Safari) on any popular operating system (Windows, macOS, Ubuntu).
Playwright Library browser launch syntax
In Playwright Library, launch a browser with await playwright.chromium.launch(), await playwright.firefox.launch(), or await playwright.webkit.launch(). Each browser type is explicitly imported.
setViewportSize replaces setViewport
In Playwright, the method to set viewport dimensions is page.setViewportSize({ width, height }) instead of Puppeteer's page.setViewport().
Playwright Test artifact collection
Playwright Test has built-in test artifact collection capabilities as configured via test-use-options.
Filter tests by tag in configuration file
You can filter tests in the configuration file via TestConfig.grep and TestProject.grep properties.
webServer configuration option
The webServer option launches a server during tests. It takes an object with properties: command (the command to start the server), url (the URL where the server is accessible), and reuseExistingServer (whether to reuse an existing server instance).
outputDir configuration option
The outputDir option specifies a folder where test artifacts such as screenshots, videos, and traces are stored. Example: outputDir: 'test-results'
baseURL use option
The baseURL option in the use section sets a base URL to use in actions like await page.goto('/'). Example: baseURL: 'http://localhost:3000'
testIgnore configuration option
The testIgnore option accepts glob patterns or regular expressions that should be ignored when looking for test files. Example: testIgnore: '*test-assets'
trace use option
The trace option in the use section configures when traces are collected. The value 'on-first-retry' collects a trace when retrying a failed test.
use configuration section
The use section in the configuration file contains options that apply to all tests, such as baseURL and trace settings. Test runner options are top-level and should not be placed in the use section.
globalSetup configuration option
The globalSetup option specifies a path to a global setup file. This file will be required and run before all tests. It must export a single function.
workers configuration option
The workers option specifies the maximum number of concurrent worker processes to use for parallelizing tests. It can be a number or a percentage of logical CPU cores, e.g., '50%'. See Parallelism and Sharding documentation for more details.
reporter configuration option
The reporter option specifies which test reporter to use. See Test Reporters documentation to learn about available reporters.
forbidOnly configuration option
The forbidOnly option, when set to true, causes the test runner to exit with an error if any tests are marked as test.only. This is useful on CI to prevent accidentally committing test.only markers.
projects configuration option
The projects option allows you to run tests in multiple configurations or on multiple browsers. Each project can have its own configuration and device settings.
retries configuration option
The retries option specifies the maximum number of retry attempts per test. See Test Retries documentation for more details about retries.
testMatch configuration option
The testMatch option accepts glob patterns or regular expressions that match test files. Example: testMatch: '*todo-tests/*.spec.ts'. By default, Playwright runs .*(test|spec)\.(js|ts|mjs) files.
testDir configuration option
The testDir option specifies the directory where Playwright looks for test files, relative to the configuration file. Example: testDir: 'tests'
globalTeardown configuration option
The globalTeardown option specifies a path to a global teardown file. This file will be required and run after all tests. It must export a single function.
timeout configuration option
The timeout option sets the test timeout in milliseconds. Playwright enforces a timeout for each test, with a default of 30 seconds (30000 milliseconds). The time spent by the test function, test fixtures, and beforeEach hooks is included in the test timeout.
Test runner options are top-level
Test runner options in the Playwright configuration must be top-level and should not be placed in the use section. Options like testDir, fullyParallel, forbidOnly, retries, and workers are top-level options.
fullyParallel configuration option
The fullyParallel option, when set to true, runs all tests in all files in parallel. See Parallelism and Sharding documentation for more details.
Parameterized projects with custom options
You can parameterize tests at the project level by extending the base test with custom options. Define an option with a default value using the syntax: option: ['defaultValue', { option: true }]. Override option values in the config file's projects array using the use property.
Load .env file in config example
Example of loading .env file in playwright.config.ts: import { defineConfig } from '@playwright/test'; import dotenv from 'dotenv'; import path from 'path'; dotenv.config({ path: path.resolve(__dirname, '.env') }); export default defineConfig({ use: { baseURL: process.env.STAGING === '1' ? 'http://staging.example.test/' : 'http://example.test/', } });
.env file example
Example .env file contents: # .env file STAGING=0 USER_NAME=me PASSWORD=secret
Custom test option example code
Example of defining a custom test option in my-test.ts: import { test as base } from '@playwright/test'; export type TestOptions = { person: string; }; export const test = base.extend<TestOptions>({ person: ['John', { option: true }], });
Use .env files with dotenv package
Use the dotenv package to load environment variables from .env files in the configuration file. Import dotenv and call dotenv.config({ path: path.resolve(__dirname, '.env') }) to read from a .env file.
Read environment variables in config file
The configuration file can read environment variables passed through the command line using process.env.VARIABLE_NAME. This allows configuring baseURL and other settings based on environment.
Access environment variables in tests
Access environment variables in tests using process.env.VARIABLE_NAME syntax, for example process.env.USER_NAME or process.env.PASSWORD.
Pass environment variables via command line
Use environment variables to configure tests from the command line. Set variables before running the test command: USER_NAME=me PASSWORD=secret npx playwright test on bash, set USER_NAME=me and set PASSWORD=secret followed by npx playwright test on batch, or $env:USER_NAME=me and $env:PASSWORD=secret followed by npx playwright test on PowerShell.
Custom test option configuration example
Example of configuring custom options in playwright.config.ts: import { defineConfig } from '@playwright/test'; import type { TestOptions } from './my-test'; export default defineConfig<TestOptions>({ projects: [ { name: 'alice', use: { person: 'Alice' }, }, { name: 'bob', use: { person: 'Bob' }, }, ] });
Ignore project dependencies with --no-deps
You can pass the --no-deps command line option to ignore all dependencies and teardowns. Only directly selected projects will run.
Project teardown
You can add a teardown property to a setup project to teardown resources after all dependent projects have run.
Project dependencies example
Example configuration showing projects with dependencies: ```js 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'], }, ], }); ```
Multiple project dependencies execution order
If there are multiple dependencies, those project dependencies run first and in parallel. If tests from a dependency fail, the projects that depend on it will not run.
Project dependencies definition
Dependencies are a list of projects that need to run before tests in another project run. They are useful for configuring global setup actions. When using project dependencies, test reporters show the setup tests and the trace viewer records traces of the setup. Fixtures can be used inside setup projects.
Test splitting example with testMatch and testIgnore
Example splitting tests into projects: ```js import { defineConfig } from '@playwright/test'; export default defineConfig({ timeout: 60000, projects: [ { name: 'Smoke', testMatch: /.*smoke.spec.ts/, retries: 0, }, { name: 'Default', testIgnore: /.*smoke.spec.ts/, retries: 2, }, ], }); ```
Splitting tests into projects with testMatch and testIgnore
Tests can be split into projects using testMatch and testIgnore filters. Example creates a 'Smoke' project that runs tests matching a pattern with 0 retries, and a 'Default' project that runs all other tests with retries.
Project configuration example with multiple browsers
Example showing projects configuration for multiple browsers and devices: ```js 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'] }, }, { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] }, }, { name: 'Mobile Safari', use: { ...devices['iPhone 12'] }, }, { name: 'Microsoft Edge', use: { ...devices['Desktop Edge'], channel: 'msedge' }, }, { name: 'Google Chrome', use: { ...devices['Desktop Chrome'], channel: 'chrome' }, }, ], }); ```
Project configuration example with multiple environments
Example showing projects configuration for different environments with different retries: ```js import { defineConfig } from '@playwright/test'; export default defineConfig({ timeout: 60000, projects: [ { name: 'staging', use: { baseURL: 'staging.example.com', }, retries: 2, }, { name: 'production', use: { baseURL: 'production.example.com', }, retries: 0, }, ], }); ```
VS Code test runner default browser
The VS Code test runner runs tests on the default browser of Chrome. To run on other or 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 selecting the browsers to run tests on.
Run single project with --project flag
Use the --project command line option to run a single project: npx playwright test --project=firefox
Running all projects by default
Playwright runs all configured projects by default when executing 'npx playwright test'.
Project dependencies execution order
When tests have dependencies, the dependency project always runs first. Once all tests from the dependency project have passed, the dependent projects run in parallel subject to the maximum workers limit.
Multiple browser projects configuration
Projects can run tests on multiple browsers including chromium, webkit, firefox, and branded browsers such as Google Chrome and Microsoft Edge. Playwright can also run on emulated tablet and mobile devices with parameters from the device descriptors registry.
Project definition and purpose
A project is a logical group of tests running with the same configuration. Projects are configured in the playwright.config.ts file and allow running tests on different browsers and devices, in different configurations (such as logged-in and logged-out states), with different timeouts or retries, against different environments (staging and production), or split per package/functionality.
Custom project parameters for parametrization
Projects can be used to parametrize tests with custom configuration. See the parameterized projects guide for details.
Test filtering with dependencies
All test filtering options such as --grep/--grep-invert, --shard, filtering by location in the command line, or using 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.
Configure retries in playwright.config.ts
Configure retries in the configuration file using the retries option. Example: export default defineConfig({ retries: 3 });
Enable retries via command line with --retries flag
Enable test retries by running: npx playwright test --retries=3 (replace 3 with the desired number of retry attempts).