命令行

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

| 选项 | 描述 |

| :--- | :--- |

| 非选项参数 | 每个参数都被视为与完整测试文件路径匹配的正则表达式。只有匹配该模式的文件中的测试会被执行。像 $ 或 * 这样的特殊符号应使用 \ 转义。在许多 shell/终端中，你可能需要为参数加上引号。 |

| -c <file> 或 --config <file> | 配置文件，或带有可选 playwright.config.{m,c}?{js,ts} 的测试目录。默认为当前目录下的 playwright.config.ts 或 playwright.config.js。 |

| --debug | 使用 Playwright 检查器运行测试。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> | 对碎片进行测试并仅执行所选碎片，指定格式为“当前/总数”，从1开始计数，例如，“3/5”。 |

| --test-list <file> | 包含要运行的测试列表的文件路径。详情请参见 测试列表。 |

| --test-list-invert <file> | 包含要跳过的测试列表的文件路径。详情请参见 测试列表。 |

| --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-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 | 在第一次失败后停止。 |

测试列表

🌐 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