命令行

Playwright 提供了一个强大的命令行界面，用于运行测试、生成代码、调试等。通过 npx playwright --help 可以始终获取最新的可用命令行命令和参数列表。

基本命令

运行测试

运行 Playwright 测试。阅读更多关于运行测试的信息。

语法

npx playwright test [options] [test-filter...]

示例

# 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

在交互式UI 模式下运行测试

npx playwright test --ui

通用选项

选项	描述
--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%）。

所有选项

选项	描述
非选项参数	每个参数都被视为与完整测试文件路径匹配的正则表达式。只有与模式匹配的文件中的测试才会被执行。像 $ 或 * 这样的特殊符号应该用 \ 转义。在许多 shell/终端中，你可能需要用引号括起参数。
-c <file> 或 --config <file>	配置文件，或包含可选 "playwright.config.{m,c}?{js,ts}" 的测试目录。默认为当前目录中的 playwright.config.ts 或 playwright.config.js。
--debug	使用 Playwright Inspector 运行测试。PWDEBUG=1 环境变量和 --timeout=0 --max-failures=1 --headed --workers=1 选项的快捷方式。
--fail-on-flaky-tests	如果任何测试被标记为不稳定，则失败（默认：false）。
--forbid-only	如果调用 test.only 则失败（默认：false）。在 CI 上很有用。
--fully-parallel	并行运行所有测试（默认：false）。
--global-timeout <timeout>	此测试套件可以运行的最大时间（毫秒）（默认：无限制）。
-g <grep> 或 --grep <grep>	仅运行与此正则表达式匹配的测试（默认："."）。
--grep-invert <grep>	仅运行与此正则表达式不匹配的测试。
--headed	在有头浏览器中运行测试（默认：无头）。
--ignore-snapshots	忽略屏幕截图和快照预期。
-j <workers> 或 --workers <workers>	并发工作程序的数量或逻辑 CPU 核的百分比，使用 1 在单个工作程序中运行（默认：50%）。
--last-failed	仅重新运行失败的测试。
--list	收集所有测试并报告它们，但不运行。
--max-failures <N> 或 -x	在首次 N 次失败后停止。传递 -x 在首次失败后停止。
--no-deps	不运行项目依赖项。
--output <dir>	输出工件的文件夹（默认："test-results"）。
--only-changed [ref]	仅运行 'HEAD' 和 'ref' 之间已更改的测试文件。默认为运行所有未提交的更改。仅支持 Git。
--pass-with-no-tests	即使没有找到测试，也使测试运行成功。
--project <project-name...>	仅运行指定项目列表中的测试，支持 '*' 通配符（默认：运行所有项目）。
--quiet	抑制标准输出/标准错误。
--repeat-each <N>	每个测试运行 N 次（默认：1）。
--reporter <reporter>	要使用的报告器，逗号分隔，可以是 "dot"、"line"、"list" 或其他（默认："list"）。你也可以传递自定义报告器文件的路径。
--retries <retries>	不稳定测试的最大重试次数，零表示不重试（默认：不重试）。
--shard <shard>	分片测试并仅执行选定的分片，形式为 "current/all"，从 1 开始，例如 "3/5"。
--timeout <timeout>	指定测试超时阈值（毫秒），零表示无限制（默认：30 秒）。
--trace <mode>	强制跟踪模式，可以是 on、off、on-first-retry、on-all-retries、retain-on-failure、retain-on-first-failure。
--tsconfig <path>	适用于所有导入文件的单个 tsconfig 路径（默认：为每个导入文件单独查找 tsconfig）。
--ui	在交互式 UI 模式下运行测试。
--ui-host <host>	UI 服务的主机；指定此选项会在浏览器标签页中打开 UI。
--ui-port <port>	UI 服务的端口，0 表示任何空闲端口；指定此选项会在浏览器标签页中打开 UI。
-u 或 --update-snapshots [mode]	用实际结果更新快照。可能的值有 "all"、"changed"、"missing" 和 "none"。不带此标志运行测试默认为 "missing"；带此标志但不带值运行测试默认为 "changed"。
--update-source-method [mode]	用实际结果更新快照。可能的值有 "patch"（默认）、"3way" 和 "overwrite"。 "Patch" 创建一个统一的差异文件，以后可用于更新源代码。"3way" 在源代码中生成合并冲突标记。"Overwrite" 用新的快照值覆盖源代码。
-x	在首次失败后停止。

显示报告

显示上一次测试运行的 HTML 报告。阅读更多关于 HTML 报告器的信息。

语法

npx playwright show-report [report] [options]

示例

# 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

选项

选项	描述
--host <host>	报告服务的主机（默认：localhost）
--port <port>	报告服务的端口（默认：9323）

安装浏览器

安装 Playwright 所需的浏览器。阅读更多关于 Playwright 浏览器支持的信息。

语法

npx playwright install [options] [browser...]
npx playwright install-deps [options] [browser...]
npx playwright uninstall

示例

# 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

安装选项

选项	描述
--force	强制重新安装稳定浏览器渠道
--with-deps	安装浏览器系统依赖项
--dry-run	不执行安装，只打印信息
--only-shell	只安装 chromium-headless-shell 而不是完整的 Chromium
--no-shell	不安装 chromium-headless-shell

安装依赖项选项

选项	描述
--dry-run	不执行安装，只打印信息

生成与调试工具

代码生成

记录操作并为多种语言生成测试。阅读更多关于 Codegen 的信息。

语法

npx playwright codegen [options] [url]

示例

# Start recording with interactive UI
npx playwright codegen

# Record on specific site
npx playwright codegen https://playwright.net.cn

# Generate Python code
npx playwright codegen --target=python

选项

选项	描述
-b, --browser <name>	要使用的浏览器：chromium、firefox 或 webkit（默认：chromium）
-o, --output <file>	生成脚本的输出文件
--target <language>	要使用的语言：javascript、playwright-test、python 等。
--test-id-attribute <attr>	用于测试 ID 的属性

跟踪查看器

分析和查看测试跟踪以进行调试。阅读更多关于 Trace Viewer 的信息。

语法

npx playwright show-trace [options] <trace>

示例

# View a trace file
npx playwright show-trace trace.zip

# View trace from directory
npx playwright show-trace trace/

选项

选项	描述
-b, --browser <name>	要使用的浏览器：chromium、firefox 或 webkit（默认：chromium）
-h, --host <host>	跟踪服务的主机
-p, --port <port>	跟踪服务的端口

专用命令

合并报告

读取blob报告并合并它们。阅读更多关于合并报告的信息。

语法

npx playwright merge-reports [options] <blob dir>

示例

# Combine test reports
npx playwright merge-reports ./reports

选项

选项	描述
-c, --config <file>	配置文件。可用于为输出报告指定附加配置
--reporter <reporter>	要使用的报告器，逗号分隔，可以是 "list"、"line"、"dot"、"json"、"junit"、"null"、"github"、"html"、"blob"（默认："list"）

清除缓存

清除所有 Playwright 缓存。

语法

npx playwright clear-cache