Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
docs: add clarity to CLI options (#35954)
Adam Gastineau333dde055d74
diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.mdindex b6adcaffdd..890b9b86de 100644--- a/docs/src/release-notes-js.md+++ b/docs/src/release-notes-js.md@@ -841,7 +841,7 @@ test('test customer login', {npx playwright test --grep @fast```-- `--project` command line [flag](./test-cli#reference) now supports '*' wildcard:+- `--project` command line [flag](./test-cli#all-options) now supports '*' wildcard:```shnpx playwright test --project='*mobile*'```diff --git a/docs/src/test-annotations-js.md b/docs/src/test-annotations-js.mdindex 5fc2f78955..8b72344733 100644--- a/docs/src/test-annotations-js.md+++ b/docs/src/test-annotations-js.md@@ -105,7 +105,7 @@ test.describe('group', {});```-You can now run tests that have a particular tag with [`--grep`](./test-cli.md#reference) command line option.+You can now run tests that have a particular tag with [`--grep`](./test-cli.md#all-options) command line option.```bash tab=bash-bashnpx playwright test --grep @fastdiff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.mdindex aa200d18e3..fe1d92d8b3 100644--- a/docs/src/test-api/class-test.md+++ b/docs/src/test-api/class-test.md@@ -56,7 +56,7 @@ test('another test @smoke', async ({ page }) => {Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.You can also filter tests by their tags during test execution:-* in the [command line](../test-cli.md#reference);+* in the [command line](../test-cli.md#all-options);* in the config with [`property: TestConfig.grep`] and [`property: TestProject.grep`];Learn more about [tagging](../test-annotations.md#tag-tests).diff --git a/docs/src/test-cli-js.md b/docs/src/test-cli-js.mdindex 2bfc655d1e..73e79c3fca 100644--- a/docs/src/test-cli-js.md+++ b/docs/src/test-cli-js.md@@ -3,83 +3,81 @@ id: test-clititle: "Command line"----## Introduction+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`.-Here are the most common options available in the command line.+## Essential Commands-- Run all the tests- ```bash- npx playwright test- ```+### Run Tests-- Run a single test file- ```bash- npx playwright test tests/todo-page.spec.ts- ```+Run your Playwright tests. [Read more about running tests](./running-tests.md).-- Run a set of test files- ```bash- npx playwright test tests/todo-page/ tests/landing-page/- ```+#### Syntax-- Run files that have `my-spec` or `my-spec-2` in the file name- ```bash- npx playwright test my-spec my-spec-2- ```+```bash+npx playwright test [options] [test-filter...]+```-- Run tests that are in line 42 in my-spec.ts- ```bash- npx playwright test my-spec.ts:42- ```+#### Examples-- Run the test with the title- ```bash- npx playwright test -g "add a todo item"- ```+```bash+# Run all tests+npx playwright test-- Run tests in headed browsers- ```bash- npx playwright test --headed- ```+# Run a single test file+npx playwright test tests/todo-page.spec.ts-- Run all the tests against a specific project- ```bash- npx playwright test --project=chromium- ```+# Run a set of test files+npx playwright test tests/todo-page/ tests/landing-page/-- Disable [parallelization](./test-parallel.md)- ```bash- npx playwright test --workers=1- ```+# Run tests at a specific line+npx playwright test my-spec.ts:42-- Choose a [reporter](./test-reporters.md)- ```bash- npx playwright test --reporter=dot- ```+# Run tests by title+npx playwright test -g "add a todo item"-- Run in debug mode with [Playwright Inspector](./debug.md)- ```bash- npx playwright test --debug- ```+# Run tests in headed browsers+npx playwright test --headed-- Run tests in interactive UI mode, with a built-in watch mode (Preview)- ```bash- npx playwright test --ui- ```+# Run tests for a specific project+npx playwright test --project=chromium-- Ask for help- ```bash- npx playwright test --help- ```+# Get help+npx playwright test --help+```-## Reference+**Disable [parallelization](./test-parallel.md)**-Complete set of Playwright Test options is available in the [configuration file](./test-use-options.md). Following options can be passed to a command line and take priority over the configuration file:+```bash+npx playwright test --workers=1+```-<!-- // Note: packages/playwright/src/program.ts is the source of truth. -->+**Run in debug mode with [Playwright Inspector](./debug.md)**++```bash+npx playwright test --debug+```++**Run tests in interactive [UI mode](./test-ui-mode.md)**++```bash+npx playwright test --ui+```++#### 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 <grep>` or `--grep <grep>` | Only run tests matching this regular expression (default: ".*"). |+| `--project <project-name...>` | Only run tests from the specified list of projects, supports '*' wildcard (default: run all projects). |+| `--ui` | Run tests in interactive UI mode. |+| `-j <workers>` or `--workers <workers>` | Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%). |++#### 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 <file>` or `--config <file>` | 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. |@@ -91,6 +89,7 @@ Complete set of Playwright Test options is available in the [configuration file]| `-gv <grep>` or `--grep-invert <grep>` | 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 <workers>` or `--workers <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 <N>` or `-x` | Stop after the first `N` failures. Passing `-x` stops after the first failure. |@@ -105,12 +104,183 @@ Complete set of Playwright Test options is available in the [configuration file]| `--retries <retries>` | Maximum retry count for flaky tests, zero for no retries (default: no retries). || `--shard <shard>` | Shard tests and execute only the selected shard, specified in the form "current/all", 1-based, e.g., "3/5". || `--timeout <timeout>` | Specify test timeout threshold in milliseconds, zero for unlimited (default: 30 seconds). |-| `--trace <mode>` | Force tracing mode, can be "on", "off", "on-first-retry", "on-all-retries", "retain-on-failure", "retain-on-first-failure". |+| `--trace <mode>` | Force tracing mode, can be `on`, `off`, `on-first-retry`, `on-all-retries`, `retain-on-failure`, `retain-on-first-failure`. || `--tsconfig <path>` | 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>` | Host to serve UI on; specifying this option opens UI in a browser tab. || `--ui-port <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.|-| `-j <workers>` or `--workers <workers>` | Number of concurrent workers or percentage of logical CPU cores, use 1 to run in a single worker (default: 50%). || `-x` | Stop after the first failure. |++### Show Report++Display HTML report from previous test run. [Read more about the HTML reporter](./test-reporters#html-reporter).++#### Syntax++```bash+npx playwright show-report [report] [options]+```++#### Examples++```bash+# Show latest test report+npx playwright show-report++# Show a specific report+npx playwright show-report playwright-report/++# Show report on custom port+npx playwright show-report --port 8080+```++#### Options++| Option | Description |+| :--- | :--- |+| `--host <host>` | Host to serve report on (default: localhost) |+| `--port <port>` | Port to serve report on (default: 9323) |++### Install Browsers++Install browsers required by Playwright. [Read more about Playwright's browser support](./browsers.md).++#### Syntax++```bash+npx playwright install [options] [browser...]+npx playwright install-deps [options] [browser...]+npx playwright uninstall+```++#### Examples++```bash+# Install all browsers+npx playwright install++# Install only Chromium+npx playwright install chromium++# Install specific browsers+npx playwright install chromium webkit++# Install browsers with dependencies+npx playwright install --with-deps+```++#### 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++| Option | Description |+| :--- | :--- |+| `--dry-run` | Don't perform installation, just print information |++## Generation & Debugging Tools++### Code Generation++Record actions and generate tests for multiple languages. [Read more about Codegen](./codegen-intro.md).++#### Syntax++```bash+npx playwright codegen [options] [url]+```++#### Examples++```bash+# Start recording with interactive UI+npx playwright codegen++# Record on specific site+npx playwright codegen https://playwright.dev++# Generate Python code+npx playwright codegen --target=python+```++#### Options++| Option | Description |+| :--- | :--- |+| `-b, --browser <name>` | Browser to use: chromium, firefox, or webkit (default: chromium) |+| `-o, --output <file>` | Output file for the generated script |+| `--target <language>` | Language to use: javascript, playwright-test, python, etc. |+| `--test-id-attribute <attr>` | Attribute to use for test IDs |++### Trace Viewer++Analyze and view test traces for debugging. [Read more about Trace Viewer](./trace-viewer.md).++#### Syntax++```bash+npx playwright show-trace [options] <trace>+```++#### Examples++```bash+# View a trace file+npx playwright show-trace trace.zip++# View trace from directory+npx playwright show-trace trace/+```++#### Options++| Option | Description |+| :--- | :--- |+| `-b, --browser <name>` | Browser to use: chromium, firefox, or webkit (default: chromium) |+| `-h, --host <host>` | Host to serve trace on |+| `-p, --port <port>` | Port to serve trace on |++## Specialized Commands++### Merge Reports++Read [blob](./test-reporters#blob-reporter) reports and combine them. [Read more about merge-reports](./test-sharding.md).++#### Syntax++```bash+npx playwright merge-reports [options] <blob dir>+```++#### Examples++```bash+# Combine test reports+npx playwright merge-reports ./reports+```++#### Options++| Option | Description |+| :--- | :--- |+| `-c, --config <file>` | Configuration file. Can be used to specify additional configuration for the output report |+| `--reporter <reporter>` | Reporter to use, comma-separated, can be "list", "line", "dot", "json", "junit", "null", "github", "html", "blob" (default: "list") |++### Clear Cache++Clear all Playwright caches.++#### Syntax++```bash+npx playwright clear-cache+```diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.tsindex 1aa216f182..796774fac1 100644--- a/packages/playwright/types/test.d.ts+++ b/packages/playwright/types/test.d.ts@@ -2640,7 +2640,7 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {* Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.** You can also filter tests by their tags during test execution:- * - in the [command line](https://playwright.dev/docs/test-cli#reference);+ * - in the [command line](https://playwright.dev/docs/test-cli#all-options);* - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and* [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);*@@ -2717,7 +2717,7 @@ export interface TestType<TestArgs extends {}, WorkerArgs extends {}> {* Test tags are displayed in the test report, and are available to a custom reporter via `TestCase.tags` property.** You can also filter tests by their tags during test execution:- * - in the [command line](https://playwright.dev/docs/test-cli#reference);+ * - in the [command line](https://playwright.dev/docs/test-cli#all-options);* - in the config with [testConfig.grep](https://playwright.dev/docs/api/class-testconfig#test-config-grep) and* [testProject.grep](https://playwright.dev/docs/api/class-testproject#test-project-grep);*