会话管理

# 创建一个新的隔离有状态会话
playwriter session new

# 列出所有活动会话（显示浏览器、配置文件、状态信息）
playwriter session list

# 删除一个会话并清除其状态
playwriter session delete <sessionId>

# 重置 CDP 连接并清除执行环境
playwriter session reset <sessionId>

-e / --eval 标志

在会话中执行任意 Playwright 代码：

# 导航到 URL
playwriter -s 1 -e 'await page.goto("https://github.com")'

# 填写表单字段
playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

# 获取无障碍快照（对于文本内容，比截图更推荐，节省 token）
playwriter -s 1 -e 'await snapshot({ page })'

# 截取带有视觉无障碍标签的屏幕截图（按元素类型颜色编码）
playwriter -s 1 -e 'await screenshotWithAccessibilityLabels({ page })'

# 在多次调用之间存储状态（state 对象在会话内持久存在）
playwriter -s 1 -e 'state.url = page.url(); state.title = await page.title()'
playwriter -s 1 -e 'console.log(state.url, state.title)'

引用规则 : 用单引号包裹代码。对于多行代码，使用 heredoc：

playwriter -s 1 -e "$(cat <<'EOF'
const text = await page.textContent('h1');
state.heading = text;
await snapshot({ page });
EOF
)"

MCP 集成

Claude Desktop 配置 (~/.claude/settings.json 或 Claude Desktop MCP 设置)

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

远程中继服务器

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_HOST": "your-relay-host",
        "PLAYWRITER_TOKEN": "your-secret-token",
        "PLAYWRITER_SESSION": "1"
      }
    }
  }
}

暴露的 MCP 工具

内置全局对象（在执行沙盒中）

无障碍标签

screenshotWithAccessibilityLabels({ page }) 在交互式元素上叠加颜色编码的标记：

使用 aria-ref 点击带标签的元素：

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

网络拦截和状态持久化

# 拦截网络请求
playwriter -s 1 -e 'state.requests = []; page.on("request", r => state.requests.push(r.url()))'

# 稍后检查收集到的请求
playwriter -s 1 -e 'console.log(state.requests.slice(-5).join("\n"))'

# 屏幕录制
playwriter -s 1 -e 'await recording.start()'
# ... 执行操作 ...
playwriter -s 1 -e 'const video = await recording.stop(); state.video = video'

远程访问

通过隧道控制远程机器上的 Chrome：

# 在运行 Chrome 的机器上：
playwriter serve --token my-secret --replace

# 从代理机器：
playwriter --host <ip-or-hostname> --token my-secret -s 1 -e 'await page.goto("https://example.com")'

最佳实践

• 观察 → 执行 → 观察 : 每次操作前后都调用 snapshot({ page })
• 对于文本检查，优先使用 snapshot() 而非截图（更少的 token，更快）
• 切勿盲目链接操作 — 在步骤之间验证状态
• 使用稳定的选择器 : 优先使用 aria-ref、data-testid 或无障碍角色
• 将上下文存储在 state 中: 通过持久化页面引用来避免重复导航
• 在失败时使用 reset: 使用 playwriter session reset 可以干净地恢复 CDP 断开连接

故障排除

参考

• GitHub: remorses/playwriter
• Chrome 扩展程序 Web 应用商店
• playwriter skill — 从 CLI 打印完整使用指南
• playwriter logfile — 查看中继服务器 + CDP 日志路径

每周安装数

1

代码仓库

akillness/oh-my-gods

首次出现

1 天前

安全审计

Gen Agent Trust HubFailSocketPassSnykFail

安装于

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1

The extension auto-starts a WebSocket relay server at localhost:19988.

Core workflow

Always follow the Observe → Act → Observe pattern:

# 1. Create a session
playwriter session new

# 2. Navigate and observe
playwriter -s 1 -e 'await page.goto("https://example.com")'
playwriter -s 1 -e 'await snapshot({ page })'

# 3. Interact based on snapshot output
playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

# 4. Re-observe after action
playwriter -s 1 -e 'await snapshot({ page })'

Session management

# Create a new isolated stateful session
playwriter session new

# List all active sessions (shows browser, profile, state info)
playwriter session list

# Delete a session and clear its state
playwriter session delete <sessionId>

# Reset the CDP connection and clear execution environment
playwriter session reset <sessionId>

The -e / --eval flag

Execute arbitrary Playwright code in a session:

# Navigate to a URL
playwriter -s 1 -e 'await page.goto("https://github.com")'

# Fill a form field
playwriter -s 1 -e 'await page.fill("#search", "playwriter"); await page.keyboard.press("Enter")'

# Get accessibility snapshot (preferred over screenshots for text content)
playwriter -s 1 -e 'await snapshot({ page })'

# Take screenshot with visual accessibility labels (color-coded by element type)
playwriter -s 1 -e 'await screenshotWithAccessibilityLabels({ page })'

# Store state between calls (state object persists within session)
playwriter -s 1 -e 'state.url = page.url(); state.title = await page.title()'
playwriter -s 1 -e 'console.log(state.url, state.title)'

Quoting rules : Wrap code in single quotes. For multiline code, use heredoc:

playwriter -s 1 -e "$(cat <<'EOF'
const text = await page.textContent('h1');
state.heading = text;
await snapshot({ page });
EOF
)"

MCP Integration

Claude Desktop config (~/.claude/settings.json or Claude Desktop MCP settings)

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

Remote relay server

{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_HOST": "your-relay-host",
        "PLAYWRITER_TOKEN": "your-secret-token",
        "PLAYWRITER_SESSION": "1"
      }
    }
  }
}

MCP tools exposed

Built-in globals (in execute sandbox)

Accessibility labeling

screenshotWithAccessibilityLabels({ page }) overlays color-coded markers on interactive elements:

Click a labeled element using aria-ref:

playwriter -s 1 -e 'await page.locator("aria-ref=e5").click()'

Network interception and state persistence

# Intercept network requests
playwriter -s 1 -e 'state.requests = []; page.on("request", r => state.requests.push(r.url()))'

# Check collected requests later
playwriter -s 1 -e 'console.log(state.requests.slice(-5).join("\n"))'

# Screen recording
playwriter -s 1 -e 'await recording.start()'
# ... do actions ...
playwriter -s 1 -e 'const video = await recording.stop(); state.video = video'

Remote access

Control Chrome on a remote machine via tunnel:

# On the machine with Chrome:
playwriter serve --token my-secret --replace

# From agent machine:
playwriter --host <ip-or-hostname> --token my-secret -s 1 -e 'await page.goto("https://example.com")'

Best practices

• Observe → Act → Observe : always call snapshot({ page }) before and after each action
• Prefersnapshot() over screenshots for text inspection (fewer tokens, faster)
• Never chain actions blindly — verify state between steps
• Use stable selectors : prefer aria-ref, data-testid, or accessible roles
• Store context instate: avoid repeated navigation by persisting page references
• Usereset on failures: CDP disconnects recover cleanly with playwriter session reset

Troubleshooting

References

• GitHub: remorses/playwriter
• Chrome Extension Web Store
• playwriter skill — print full usage guide from CLI
• playwriter logfile — view relay server + CDP log paths

Weekly Installs

1

Repository

akillness/oh-my-gods

First Seen

1 day ago

Security Audits

Gen Agent Trust HubFailSocketPassSnykFail

Installed on

mcpjam1

claude-code1

replit1

junie1

windsurf1

zencoder1