快照
🌐 Snapshots
在每个命令之后，playwright-cli 会输出当前浏览器状态的快照——带有用于交互的元素引用的无障碍树。
🌐 After each command, playwright-cli outputs a snapshot of the current browser state — an accessibility tree with element refs for interaction.
自动快照
🌐 Automatic snapshots
每个命令都会返回页面信息和快照文件的链接：
🌐 Every command returns page info and a link to the snapshot file:
### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React - TodoMVC
### Snapshot
- [Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
快照文件包含可访问性树：
🌐 The snapshot file contains the accessibility tree:
- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
- checkbox "Toggle Todo" [ref=e10]
- text: "Buy groceries"
- listitem:
- checkbox "Toggle Todo" [ref=e14]
- text: "Water flowers"
- contentinfo:
- text: "2 items left"
- link "All" [ref=e20]
- link "Active" [ref=e21]
- link "Completed" [ref=e22]
元素引用
🌐 Element refs
每个交互元素都会获得一个唯一的引用（例如，e5、e10）。引用在单个快照中是稳定的，但在页面更改时会失效——导航后始终重新快照。
🌐 Each interactive element gets a unique ref (e.g., e5, e10). Refs are stable within a single snapshot but invalidated when the page changes — always re-snapshot after navigation.
| 属性 | 详情 |
|---|---|
| 格式 | e 后跟一个数字（例如，e1、e15、e203） |
| 范围 | 在单个快照中唯一 |
| 生命周期 | 有效直到下一次页面更改 |
| 分配 | 只有交互元素才会获得引用（按钮、链接、输入框等） |
按需快照
🌐 On-demand snapshots
所有这些选项都可以组合起来。
🌐 All of these options can be combined.
playwright-cli snapshot # full page, timestamped filename
playwright-cli snapshot --filename=after.yaml # custom filename
playwright-cli snapshot "#main" # scope to CSS selector
playwright-cli snapshot e34 # scope to element ref
playwright-cli snapshot --depth=4 # limit tree depth
playwright-cli snapshot --boxes # include bounding boxes
--boxes 会将 [box=x,y,width,height] 添加到每个元素。坐标是相对于视口的 CSS 像素，由 Element.getBoundingClientRect() 返回——可作为基于坐标的交互的输入。
在深入页面时，一个常见的做法是先拍一个浅层快照，然后对感兴趣的子树拍一个部分快照：
🌐 A common pattern on a deep page is to take a shallow snapshot first, then a partial one of the interesting subtree:
playwright-cli snapshot --depth=4
playwright-cli snapshot e34
正在搜索快照
🌐 Searching a snapshot
在一个大页面上，find 比捕获整个树要便宜得多。它会返回匹配的节点，并在每个匹配周围提供三行上下文 —— 就像 grep -C 一样 —— 显示在它们从树根到当前节点的路径下。
🌐 On a large page, find is much cheaper than capturing the whole tree. It returns the matching
nodes with three lines of context around each match — like grep -C — under their path from the
root of the tree.
# case-insensitive substring match
playwright-cli find "Add to cart"
# regular expression, case-sensitive by default
playwright-cli find --regex "\\$[0-9]+\\.[0-9]{2}"
# wrap the pattern in slashes to add flags
playwright-cli find --regex "/sign (in|up)/i"
传入文本参数或 --regex，不要同时传入两者。
🌐 Pass either a text argument or --regex, not both.
使用 refs
🌐 Using refs
playwright-cli click e10 # check the checkbox
playwright-cli fill e5 "Walk the dog" # type into textbox
playwright-cli hover e20 # hover over "All" link
使用选择器
🌐 Using selectors
CSS 选择器和 Playwright 定位器可以作为 refs 的替代方案：
🌐 CSS selectors and Playwright locators work as alternatives to refs:
# CSS selectors
playwright-cli click "#main > button.submit"
playwright-cli click "[data-testid='submit']"
# Playwright locators
playwright-cli click "getByRole('button', { name: 'Submit' })"
playwright-cli click "getByTestId('submit-button')"
playwright-cli click "getByText('Login')"
原始输出
🌐 Raw output
--raw 是一个全局选项，它会去掉页面状态、生成的代码以及快照部分，只留下结果值。它就是让输出可以管道化的原因：
playwright-cli --raw snapshot > before.yml
playwright-cli click e5
playwright-cli --raw snapshot > after.yml
diff before.yml after.yml
最佳实践
🌐 Best practices
- 使用 refs，而不是选择器 — 来自快照的 refs 比 CSS 选择器更可靠，因为它们指向代理刚刚看到的确切元素
- 导航后重新快照 — 当页面变化时，引用会失效
- 搜索而不是捕获 —— 当你只需要定位一个元素时使用
find - 限制深度 — 在复杂页面上使用
--depth以减少输出大小 - 限定到元素 — 截取页面的特定部分而不是整个页面
- 命名快照文件 — 当快照是工作流结果的一部分时使用
--filename - 检查对话框 — 如果命令报告有对话框打开，请在执行其他操作之前处理它