命令行
Playwright 提供了一个强大的命令行接口，用于运行测试、生成代码、调试等。关于 CLI 可用命令和参数的最新列表，可以随时通过 npx playwright --help 获取。
🌐 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
运行测试
🌐 Run Tests
运行你的 Playwright 测试。阅读关于运行测试的更多信息。
🌐 Run your Playwright tests. Read more about running tests.
语法
🌐 Syntax
npx playwright test [options] [test-filter...]
示例
🌐 Examples
# Run all tests
npx playwright test
# Run a single test file
npx playwright test tests/todo-page.spec.ts
# Run a set of test files
npx playwright test tests/todo-page/ tests/landing-page/
# Run tests at a specific line
npx playwright test my-spec.ts:42
# Run tests by title
npx playwright test -g "add a todo item"
# Run tests in headed browsers
npx playwright test --headed
# Run tests for a specific project
npx playwright test --project=chromium
# Get help
npx playwright test --help
禁用并行化
npx playwright test --workers=1
使用 Playwright Inspector 以调试模式运行
npx playwright test --debug
在交互式用户界面模式下运行测试
npx playwright test --ui
常用选项
🌐 Common Options
| 选项 | 描述 |
|---|---|
--debug | 使用 Playwright Inspector 运行测试。是 PWDEBUG=1 环境变量和 --timeout=0 --max-failures=1 --headed --workers=1 选项的快捷方式。 |
--headed | 在有界面浏览器中运行测试（默认：无界面）。 |
-g <grep> 或 --grep <grep> | 仅运行匹配此正则表达式的测试（默认：".*"）。 |
--project <project-name...> | 仅运行指定项目列表中的测试，支持 '*' 通配符（默认：运行所有项目）。 |
--ui | 以交互式 UI 模式运行测试。 |
-j <workers> 或 --workers <workers> | 并发工作进程数量或逻辑 CPU 核心百分比，使用 1 可在单个工作进程中运行（默认：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. |
--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 <timeout> | Maximum time this test suite can run in milliseconds (default: unlimited). |
-g <grep> or --grep <grep> | Only run tests matching this regular expression (default: ".*"). |
--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. |
--no-deps | Do not run project dependencies. |
--output <dir> | 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 <project-name...> | Only run tests from the specified list of projects, supports '*' wildcard (default: run all projects). |
--quiet | Suppress stdio. |
--repeat-each <N> | Run each test N times (default: 1). |
--reporter <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 <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". |
--test-list <file> | Path to a file containing a list of tests to run. See test list for details. |
--test-list-invert <file> | Path to a file containing a list of tests to skip. See test list for details. |
--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. |
--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. |
-x | Stop after the first failure. |
测试列表
🌐 Test list
选项 --test-list 和 --test-list-invert 接受指向测试列表文件的路径。该文件应以类似于 --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.
# Run ALL tests in a file:
path/to/example.spec.ts
# Run all tests in a file for a specific project:
[chromium] › path/to/example.spec.ts
# Run all tests in a specific group/suite:
path/to/example.spec.ts › suite name
# Run all tests in a nested group:
path/to/example.spec.ts › outer suite › inner suite
# 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 test
example.spec.ts:15 › example test
example.spec.ts:42:42 › example test
显示报告
🌐 Show Report
显示上次测试运行的 HTML 报告。了解有关 HTML 报告器的更多信息。
🌐 Display HTML report from previous test run. Read more about the HTML reporter.
语法
🌐 Syntax
npx playwright show-report [report] [options]
示例
🌐 Examples
# 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
| 选项 | 描述 |
|---|---|
--host <host> | 提供报告的主机（默认：localhost） |
--port <port> | 提供报告的端口（默认：9323） |
安装浏览器
🌐 Install Browsers
安装 Playwright 所需的浏览器。了解有关 Playwright 浏览器支持的更多信息。
🌐 Install browsers required by Playwright. Read more about Playwright's browser support.
语法
🌐 Syntax
npx playwright install [options] [browser...]
npx playwright install-deps [options] [browser...]
npx playwright uninstall
示例
🌐 Examples
# 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
| 选项 | 描述 |
|---|---|
--force | 强制重新安装稳定版浏览器渠道 |
--with-deps | 安装浏览器系统依赖 |
--dry-run | 不执行安装，仅打印信息 |
--only-shell | 仅安装 chromium-headless-shell，而不安装完整的 Chromium |
--no-shell | 不安装 chromium-headless-shell |
安装依赖选项
🌐 Install Deps Options
| 选项 | 描述 |
|---|---|
--dry-run | 不进行安装，只打印信息 |
生成和调试工具
🌐 Generation & Debugging Tools
代码生成
🌐 Code Generation
记录操作并为多种语言生成测试。了解更多关于 Codegen 的信息。
🌐 Record actions and generate tests for multiple languages. Read more about Codegen.
语法
🌐 Syntax
npx playwright codegen [options] [url]
示例
🌐 Examples
# Start recording with interactive UI
npx playwright codegen
# Record on specific site
npx playwright codegen https://playwright.nodejs.cn
# Generate Python code
npx playwright codegen --target=python
选项
🌐 Options
| 选项 | 描述 |
|---|---|
-b, --browser <name> | 使用的浏览器：chromium、firefox 或 webkit（默认：chromium） |
-o, --output <file> | 生成脚本的输出文件 |
--target <language> | 使用的语言：javascript、playwright-test、python 等 |
--test-id-attribute <attr> | 用于测试 ID 的属性 |
跟踪查看器
🌐 Trace Viewer
分析并查看测试跟踪以进行调试。了解有关跟踪查看器的更多信息。
🌐 Analyze and view test traces for debugging. Read more about Trace Viewer.
语法
🌐 Syntax
npx playwright show-trace [options] [trace]
示例
🌐 Examples
# Open trace viewer without a specific trace (can load traces via UI)
npx playwright show-trace
# View a trace file
npx playwright show-trace trace.zip
# View trace from directory
npx playwright show-trace trace/
选项
🌐 Options
| 选项 | 描述 |
|---|---|
-b, --browser <name> | 使用的浏览器：chromium、firefox 或 webkit（默认：chromium） |
-h, --host <host> | 用于提供跟踪的主机 |
-p, --port <port> | 用于提供跟踪的端口 |
专用命令
🌐 Specialized Commands
合并报告
🌐 Merge Reports
阅读 blob 报告并将它们合并。了解更多关于合并报告。
🌐 Read blob reports and combine them. Read more about merge-reports.
语法
🌐 Syntax
npx playwright merge-reports [options] <blob dir>
示例
🌐 Examples
# Combine test reports
npx playwright merge-reports ./reports
选项
🌐 Options
| 选项 | 描述 |
|---|---|
-c, --config <file> | 配置文件。可用于为输出报告指定额外配置 |
--reporter <reporter> | 使用的报告器，逗号分隔，可选 "list"、"line"、"dot"、"json"、"junit"、"null"、"github"、"html"、"blob"（默认值: "list"） |
清除缓存
🌐 Clear Cache
清除所有 Playwright 缓存。
🌐 Clear all Playwright caches.
语法
🌐 Syntax
npx playwright clear-cache