Playwright Running Tests

This chapter comprehensively introduces how to run Playwright tests, command-line arguments, and various filtering techniques.

Basic Run Commands

Examples

# Run all tests
npx playwright test

# By default, uses the project configured in package.json
npm test

Filtering Specific Tests

By File Path

# 运行单个测试文件
npx playwright test tests/login.spec.ts

# 运行目录中的所有测试
npx playwright test tests/user/

# 运行多个文件（空格分隔）
npx playwright test tests/login.spec.ts tests/register.spec.ts

By File Name Keyword

# 运行文件名中包含 "login" 或 "user" 的所有测试
npx playwright test login user

Filter by Test Name (-g / --grep)

# 运行测试名称中包含 "登录" 的测试
npx playwright test -g "登录"

# 通过正则表达式筛选
npx playwright test -g "登录|注册"

Filter by Tag

Examples

// Define tag in test
test('Quick smoke test @smoke', async ({ page }) => {
  // ...
});

test('Slow test @slow', async ({ page }) => {
  // ...
});
# 只运行带 @smoke 标签的测试
npx playwright test --grep "@smoke"

# 跳过带 @slow 标签的测试
npx playwright test --grep-invert "@slow"

Browser Control

Specify Browser (--project)

# 只在 Chromium 上运行
npx playwright test --project=chromium

# 在多个浏览器上运行
npx playwright test --project=chromium --project=firefox

Headed Mode (--headed)

# 显示浏览器窗口（默认无头）
npx playwright test --headed

Specify Browser Executable Path

# 使用本地安装的 Chrome 而非 Playwright 的 Chromium
npx playwright test --project=chromium \
  --channel=chrome

Execution Modes

UI Mode (--ui)

# 在 UI 模式下运行（推荐开发和调试时使用）
npx playwright test --ui

Debug Mode (--debug)

# 单步调试测试
npx playwright test --debug

Parallelism and Repetition

Control Number of Workers (--workers)

# 使用 4 个 worker 并行运行
npx playwright test --workers=4

# 单线程运行（方便调试）
npx playwright test --workers=1

Repeat Run (--repeat-each)

# 每个测试重复运行 3 次（检查稳定性）
npx playwright test --repeat-each=3

Sharded Run (--shard)

# 在 CI 上分片运行（分 4 片，当前为第 1 片）
npx playwright test --shard=1/4

# 第 2 片
npx playwright test --shard=2/4

Sharding is commonly used in CI to run tests in parallel across multiple machines, with each machine running only a portion, and finally merging the results.

Screenshots and Trace Control

# 更新视觉回归的基准截图
npx playwright test --update-snapshots

# 强制生成 Trace 文件（即使配置中没有开启）
npx playwright test --trace on

# 查看最后一次运行的 Trace
npx playwright show-trace test-results/.../trace.zip

Common Commands Quick Reference

CommandDescription
npx playwright testRun all tests
npx playwright test file.spec.tsRun specified file
npx playwright test -g "关键词"Filter by test name
npx playwright test --project=chromiumSpecify browser
npx playwright test --headedHeaded mode (show browser window)
npx playwright test --uiUI mode
npx playwright test --debugDebug mode
npx playwright test --workers=4Specify number of workers
npx playwright test --shard=1/4Sharded run
npx playwright test --repeat-each=3Repeat run
npx playwright test --update-snapshotsUpdate visual baseline screenshots
npx playwright show-reportView HTML report
npx playwright show-trace trace.zipView Trace
npx playwright codegen urlLaunch code generator
Other Extensions