Day 04 - Running Tests and CLI Essentials

今日目标

掌握常用 Playwright CLI。
能按文件、浏览器、headed/debug 模式运行测试。

学习时间安排（60–120 分钟）

时间	模块	做什么
0-20 分钟	核心概念与词汇	读概念表，把每个 flag 和它的使用场景对上号。
20-45 分钟	官方文档阅读	读 Running and debugging tests 的命令行部分。
45-75 分钟	实操练习	至少运行 4 种不同模式，记录每种模式的适用场景。
75-105 分钟	示例代码改写	用 `--grep` 筛选自己的测试，尝试组合多个 flag。
105-120 分钟	复盘与作业	完成“命令用途对照表”，完成今日问题。

核心概念与词汇

English	中文	场景用法
`--headed`	有头运行	Use it when you need to see the browser window during a run.
`--debug`	调试模式	Use it when you want to step through test code line by line.
`--ui`	UI 模式	Use it when you explore, run, and watch tests in the interactive UI Mode.
`--project`	项目/浏览器选择	Use it when you run only one browser or device profile from the config.
`--grep`	用例名筛选	Use it when you run a subset of tests matching a name pattern.
`--reporter`	报告格式	Use it when you switch between list, line, dot, HTML, or JSON output.
`--list`	列出用例	Use it when you list all tests without executing them.
`--workers`	并行数	Use it when you control parallelism from the command line.
headless	无头模式	Use it when tests run without a visible browser, the CI default.
retry	失败重试	Use it when you configure automatic reruns of failed tests.
debugger	调试器	Use it when you pause execution with the Playwright Inspector.

学习材料

必读：[Running and debugging tests](https://playwright.dev/docs/running-tests)
必读：[Debugging tests](https://playwright.dev/docs/debug)
选读：[Test CLI reference](https://playwright.dev/docs/test-cli)（扫一遍有哪些命令即可）

重点理解

常用命令：

npx playwright test
npx playwright test tests/example.spec.ts
npx playwright test --project=chromium
npx playwright test --headed
npx playwright test --debug
npx playwright test --ui
npx playwright show-report

理解：

--headed：打开真实浏览器窗口。
--debug：逐步调试。
--ui：UI Mode。
--project：选择配置中的浏览器或项目。
--grep：按用例名筛选。
--reporter：选择报告格式。

实操步骤

分别执行：

npx playwright test --headed
npx playwright test --debug
npx playwright test --ui
npx playwright test --grep "navigate"

记录每种模式适合什么场景。

示例代码

组合使用 flag：

# 只看 chromium 上标题含 smoke 的用例，列表模式输出
npx playwright test --project=chromium --grep "smoke" --reporter=list

# 只运行一个文件并保持有头模式
npx playwright test tests/day02-basic.spec.ts --headed

# 列出全部用例不执行
npx playwright test --list

常见坑

本地开发习惯用 --headed，提交 CI 时忘了 CI 默认 headless 导致的差异。
混淆 --debug（逐步调试）和 --ui（交互式运行器），两者解决的问题不同。
--grep 匹配的是完整测试名（含 describe 前缀），只记得短名时筛选不到。
每次全量跑测试浪费大量时间，不会用文件名 + --grep 快速缩小范围。
用了 --project=webkit 才发现本地没装 WebKit，报错信息不仔细看。

今日产出

一张“命令用途对照表”。
至少运行 4 种不同模式。

今日问题

Headless 和 headed 有什么区别？
Debug mode 和 UI Mode 有什么区别？
什么情况下只运行单个 spec 文件？
--grep 适合解决什么问题？
CI 环境通常用 headed 还是 headless？

复盘要点

你不需要背下所有 flag，但要记住“缩小范围三件套”：文件名、--project、--grep。
Debug mode 解决“哪一行代码有问题”，UI Mode 解决“这批测试现在是什么状态”。
把今天的命令对照表放进项目 README，这是你第一个可交付文档。

AI 时代扩展：AI 辅助 Playwright 测试

新增概念

English	中文
CLI assistance	命令行辅助
command autocompletion	命令自动补全
failure triage	失败分类
run scoping	运行范围控制

适用场景

让 AI 解释报错输出中的关键行，或者根据你的“想跑哪类测试”描述生成对应命令。CI 日志很长时，可以让 AI 帮忙提取失败用例清单和共同原因。

可复用表达 / 提示词

我想只运行 chromium 项目里名称包含 login 的测试并输出 list 报告，请给出命令并解释每个 flag。
以下是 200 行 CI 日志，请提取所有失败的测试名、错误类型和第一条报错位置。

追问加练

AI 给出的命令里有一个 flag 不存在，你如何快速发现？
让 AI 读 CI 日志提取失败原因，什么信息它最容易漏掉？
哪些场景你不应该让 AI 替你决定运行范围？

今日作业

完成“命令用途对照表”，至少 8 条命令，每条注明适用场景。
用 --list 列出你项目的全部用例，核对数量和预期是否一致。
故意写坏一个 locator，用 --debug 和 --ui 各排查一次，记录体验差异。

自检清单

我能说出 6 个以上常用 flag 的用途。
我运行过 headed、debug、ui、grep 四种模式。
我能用文件名 + --grep 只跑一个测试。
我知道 CI 为什么默认 headless。
明天复盘前，我能独立从 0 创建项目并写基础测试。