Recommended package for end-to-end tests
For writing end-to-end tests, @playwright/test is the recommended package to use.
test execution
38 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Test command filtering syntax
Tests can be filtered by specific file (npm run ctest tests/page/locator-click.spec.ts), specific location (npm run ctest tests/page/locator-click.spec.ts:12), test name (npm run ctest -- --grep "should click"), or file name part (npm run ctest-mcp snapshot).
Run single project with --project flag
Use `npx playwright test --project=firefox` to run tests on a single project only, where the project name matches one defined in the config's `projects` array.
Run tests in headed browsers with --headed
The `--headed` option runs tests in headed browsers instead of the default headless mode.
Filter tests by title with --grep
The `-g <grep>` or `--grep <grep>` option runs only tests matching the specified regular expression (default: ".*").
Run tests for specific project with --project
The `--project <project-name...>` option runs only tests from the specified list of projects and supports '*' wildcard (default: run all projects).
Common CLI options for npx playwright test
Common options for running tests: `--debug` (run with Inspector), `--headed` (run in headed browsers), `-g <grep>` (filter by test title), `--project <project-name...>` (run specific projects), `--ui` (interactive UI mode), `-j <workers>` (concurrent workers, default 50%).
Set test timeout with --timeout option
The `--timeout <timeout>` option specifies the test timeout threshold in milliseconds. Use zero for unlimited (default: 30 seconds).
Run tests in specific files or directories
When running `npx playwright test`, you can specify single test files like `tests/todo-page.spec.ts`, sets of test files like `tests/todo-page/ tests/landing-page/`, or tests at specific lines like `my-spec.ts:42`.
Invert grep filter with --grep-invert
The `-G <grep>` or `--grep-invert <grep>` option runs only tests that do not match the specified regular expression.
Re-run failed tests with --last-failed
The `--last-failed` option re-runs only the test failures from the previous run. Use `--last-failed-file <file>` to override the default last-run JSON path (default: `<outputDir>/.last-run.json`), equivalent to `PLAYWRIGHT_LAST_RUN_OUTPUT_FILE` environment variable.
List all tests without running them with --list
The `--list` option collects all tests and reports them without executing any tests.
Repeat each test multiple times with --repeat-each
The `--repeat-each <N>` option runs each test N times (default: 1).
Fail if test.only is used with --forbid-only
The `--forbid-only` option fails the test run if `test.only` is called (default: false). This is useful on CI to prevent accidentally committing focused tests.
Fail on flaky tests with --fail-on-flaky-tests
The `--fail-on-flaky-tests` option fails the test run if any test is flagged as flaky (default: false).
Set global timeout for entire test suite with --global-timeout
The `--global-timeout <timeout>` option sets the maximum time the entire test suite can run in milliseconds (default: unlimited).
Ignore snapshots with --ignore-snapshots
The `--ignore-snapshots` option ignores screenshot and snapshot expectations during test execution.
Set output directory with --output
The `--output <dir>` option specifies the folder for output artifacts (default: "test-results").
Run only changed test files with --only-changed
The `--only-changed [ref]` option runs only test files that have been changed between 'HEAD' and 'ref'. Defaults to running all uncommitted changes. Only supports Git.
Pass with no tests with --pass-with-no-tests
The `--pass-with-no-tests` option makes the test run succeed even if no tests were found.
Suppress output with --quiet
The `--quiet` option suppresses stdout during test execution.
Configure retries for flaky tests with --retries
The `--retries <retries>` option sets the maximum retry count for flaky tests. Use zero for no retries (default: no retries).
Specify test list file with --test-list
The `--test-list <file>` option runs tests from a specified file containing a list of tests. The file should list tests in a format similar to the output produced in `--list` mode.
Skip tests with --test-list-invert
The `--test-list-invert <file>` option skips tests listed in the specified file, running all others instead.
Test list file format and examples
Test list files support various formats: 'path/to/example.spec.ts' (all tests in file), '[chromium] › path/to/example.spec.ts' (all tests for specific project), 'path/to/example.spec.ts › suite name' (tests in suite), '[chromium] › path/to/example.spec.ts:3:9 › suite › nested suite › example test' (fully qualified test), 'path/to/example.spec.ts › example test' (included for all projects). Both '›' and '>' can be used as separators. Line/column numbers are ignored.
Add reporters with --add-reporter
The `--add-reporter <reporter>` option adds a reporter on top of the reporters configured in the config file (comma-separated). Can be a built-in reporter name or a path to a custom reporter file. Unlike `--reporter`, this keeps the configured reporters instead of replacing them.
Configure reporter with --reporter
The `--reporter <reporter>` option specifies which 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.
Update snapshots with --update-snapshots
The `-u` or `--update-snapshots [mode]` option updates snapshots with actual results. Possible values are "all", "changed", "missing", and "none". Running tests without the flag defaults to "missing"; running with the flag but without a value defaults to "changed".
Update snapshots with --update-source-method
The `--update-source-method [mode]` option updates snapshots with actual results using different strategies: "patch" (default) creates a unified diff file for later application, "3way" generates merge conflict markers in source code, and "overwrite" overwrites source code with new snapshot values.
Skip project dependencies with --no-deps
The `--no-deps` option skips running project dependencies.
Filter tests by file path using non-option arguments
Each non-option argument passed to `npx playwright test` 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 arguments may need to be quoted.
Show HTML report with show-report command
Use `npx playwright show-report [report] [options]` to display HTML report from a previous test run. Can show the latest report, a specific report directory, or show report on a custom port.
Show-report command options
The show-report command accepts: `--host <host>` to specify host to serve report on (default: localhost) and `--port <port>` to specify port to serve report on (default: 9323).
Merge test reports with merge-reports command
Use `npx playwright merge-reports [options] <blob dir>` to read blob reports and combine them into a single report.
Merge-reports command options
Merge-reports options: `-c, --config <file>` to specify configuration file for additional output report configuration, `--reporter <reporter>` to specify reporter (comma-separated, can be "list", "line", "dot", "json", "junit", "null", "github", "html", "blob", default: "list").
UI mode options for test command
The `--ui-host <host>` option specifies the host to serve UI on; specifying this opens UI in a browser tab. The `--ui-port <port>` option specifies the port to serve UI on, with 0 for any free port; specifying this opens UI in a browser tab.
Stop after N failures with --max-failures
The `--max-failures <N>` or `-x` option stops test execution after the first N failures. Passing `-x` alone stops after the first failure.
Run tests in interactive UI mode with --ui
Running `npx playwright test --ui` launches tests in interactive UI mode for visual test execution and debugging.