Back to Details

playwright

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Playwright CLI Skill

Playwright CLI Skill

Drive a real browser from the terminal using 
playwright-cli
. Prefer the bundled wrapper script so the CLI works even when it is not globally installed. Treat this skill as CLI-first automation. Do not pivot to 
@playwright/test
unless the user explicitly asks for test files.
使用
playwright-cli
从终端控制真实浏览器。优先使用捆绑的包装脚本，这样即使未全局安装该CLI也能运行。 将此技能视为以CLI优先的自动化工具。除非用户明确要求测试文件，否则不要转向
@playwright/test
。

Prerequisite check (required)

前置检查（必填）

Before proposing commands, check whether 
npx
is available (the wrapper depends on it):
bash
command -v npx >/dev/null 2>&1
If it is not available, pause and ask the user to install Node.js/npm (which provides 
npx
). Provide these steps verbatim:
bash
undefined
在提供命令之前，检查
npx
是否可用（包装脚本依赖它）：
bash
command -v npx >/dev/null 2>&1
如果不可用，请暂停并要求用户安装Node.js/npm（它会提供
npx
）。请一字不差地提供以下步骤：
bash
undefined

Verify Node/npm are installed

验证Node/npm是否已安装

node --version npm --version
node --version npm --version

If missing, install Node.js/npm, then:

如果缺失，安装Node.js/npm，然后执行：

npm install -g @playwright/mcp@latest playwright-cli --help

Once `npx` is present, proceed with the wrapper script. A global install of `playwright-cli` is optional.
npm install -g @playwright/mcp@latest playwright-cli --help

一旦`npx`可用，就可以继续使用包装脚本。全局安装`playwright-cli`是可选的。

Skill path (set once)

技能路径（设置一次）

bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
User-scoped skills install under 
$CODEX_HOME/skills
(default: 
~/.codex/skills
).
bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
用户范围的技能安装在
$CODEX_HOME/skills
下（默认：
~/.codex/skills
）。

Quick start

快速开始

Use the wrapper script:
bash
"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot
If the user prefers a global install, this is also valid:
bash
npm install -g @playwright/mcp@latest
playwright-cli --help
使用包装脚本：
bash
"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot
如果用户偏好全局安装，以下方式也有效：
bash
npm install -g @playwright/mcp@latest
playwright-cli --help

Core workflow

核心工作流

  1. Open the page.
  2. Snapshot to get stable element refs.
  3. Interact using refs from the latest snapshot.
  4. Re-snapshot after navigation or significant DOM changes.
  5. Capture artifacts (screenshot, pdf, traces) when useful.
Minimal loop:
bash
"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot
  1. 打开页面。
  2. 生成快照以获取稳定的元素引用。
  3. 使用最新快照中的引用进行交互。
  4. 在导航或DOM发生重大变化后重新生成快照。
  5. 在需要时捕获工件（截图、PDF、跟踪文件）。
最小循环示例：
bash
"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot

When to snapshot again

何时重新生成快照

Snapshot again after:
  • navigation
  • clicking elements that change the UI substantially
  • opening/closing modals or menus
  • tab switches
Refs can go stale. When a command fails due to a missing ref, snapshot again.
在以下情况后重新生成快照：
  • 页面导航
  • 点击会大幅改变UI的元素
  • 打开/关闭模态框或菜单
  • 切换标签页
引用可能会失效。当命令因引用缺失而失败时，请重新生成快照。

Recommended patterns

推荐模式

Form fill and submit

表单填写与提交

bash
"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot
bash
"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

Debug a UI flow with traces

使用跟踪文件调试UI流程

bash
"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
bash
"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start

...interactions...

...交互操作...

"$PWCLI" tracing-stop
undefined
"$PWCLI" tracing-stop
undefined

Multi-tab work

多标签页操作

bash
"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot
bash
"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot

Wrapper script

包装脚本

The wrapper script uses 
npx --package @playwright/mcp playwright-cli
so the CLI can run without a global install:
bash
"$PWCLI" --help
Prefer the wrapper unless the repository already standardizes on a global install.
包装脚本使用
npx --package @playwright/mcp playwright-cli
，因此无需全局安装即可运行该CLI：
bash
"$PWCLI" --help
除非仓库已标准化使用全局安装，否则优先使用包装脚本。

References

参考资料

Open only what you need:
  • CLI command reference: 
    references/cli.md
  • Practical workflows and troubleshooting: 
    references/workflows.md
仅打开你需要的内容：
  • CLI命令参考：
    references/cli.md
  • 实用工作流与故障排除：
    references/workflows.md

Guardrails

注意事项

  • Always snapshot before referencing element ids like 
    e12
    .
  • Re-snapshot when refs seem stale.
  • Prefer explicit commands over 
    eval
    and 
    run-code
    unless needed.
  • When you do not have a fresh snapshot, use placeholder refs like 
    eX
    and say why; do not bypass refs with 
    run-code
    .
  • Use 
    --headed
    when a visual check will help.
  • When capturing artifacts in this repo, use 
    output/playwright/
    and avoid introducing new top-level artifact folders.
  • Default to CLI commands and workflows, not Playwright test specs.
  • 在引用
    e12
    这类元素ID之前，务必先生成快照。
  • 当引用似乎失效时，重新生成快照。
  • 优先使用明确的命令，而非
    eval
    和
    run-code
    ，除非必要。
  • 当你没有最新快照时，使用
    eX
    这类占位符引用并说明原因；不要使用
    run-code
    绕过引用。
  • 当需要视觉检查时，使用
    --headed
    参数。
  • 在此仓库中捕获工件时，请使用
    output/playwright/
    ，避免引入新的顶级工件文件夹。
  • 默认使用CLI命令和工作流，而非Playwright测试规范。