一、claude code 配置playwrite mcp

步骤 1：安装必要组件：

# 安装 Playwright 测试框架
npm install -g @playwright/test
# 安装 Playwright MCP 服务端
npm install -g @executeautomation/playwright-mcp-server
# 安装浏览器依赖（会下载 Chromium、Firefox 等）
npx playwright install

此步骤确保本地具备运行 Playwright MCP 所需的环境。

步骤 2：移除旧配置（如有）

claude mcp remove playwright -s local

步骤 3：添加 Playwright MCP 配置

在 macOS 下使用 /bin/bash 执行：

# windows 方法
claude mcp add-json playwright "{\"command\": \"cmd\", \"args\": [\"/c\", \"npx\", \"@executeautomation/playwright-mcp-server\"]}"
 
这一步的意思是：告诉Claude Code要先启动Windows命令行(cmd)，然后在命令行里执行npx命令。
 
# mac方法
 
claude mcp add-json playwright '{"command": "/bin/bash", "args": ["-c", "npx @executeautomation/playwright-mcp-server"]}'
 

这一步告诉 Claude 启动 MCP 时调用 npx 启动 Playwright MCP 服务。

步骤 4：验证配置是否成功

1. 查看已注册 MCP 服务列表：

#查看配置是否正确
claude mcp list

2. 测试连接（这里我测试成功）

# 测试连接（会看到很多调试信息，找到这一行就是成功了）
# windows 方法
claude --print "测试playwright" --debug | findstr "connected"
 
# mac 方法
claude --print "测试playwright" --debug | grep "connected"

网上说：如果输出中包含 connected，说明 Claude 已成功连接到 Playwright MCP，像图片中这样：
实际我操作过程中：

等了很长时间，都没有日志打印，我也不知道我到底安装成功没？
so，我只能另辟蹊径了。

3. 我的测试

进入claude界面，输入：“帮我用 playwright 打开百度首页，并截图保存为 screenshot.png”

成功截图！！

二、配置以及参数说明

2.1 配置内容：

常规配置内容：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp", "--browser", "chrome"]
    }
  }
}

无头模式配置：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp", "--browser", "chrome", "--headless"]
    }
  }
}

启用额外能力（如 PDF、Vision、网络拦截等）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp", "--browser", "chrome", "--caps", "core,pdf,vision,network,storage"]
    }
  }
}

HTTP SSE 模式（适合远程或无显示环境）：
先启动 MCP 服务器：

npx @playwright/mcp --browser chrome --port 8931

然后在配置中使用 HTTP 连接：

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

2.2 配置里的command为啥有的不一样？

我的mac上是 “command”: “/bin/bash”。

2.3 claude codemcp相关配置上什么样的

• 之前版本：Linux/macOS: ~/.config/claude-code/mcp_config.json；
• 2.1.x（我的版本）：Linux/macOS: 在~/.claude.json；

cat ~/.claude.json：

三、标准测试工作流

1. 配置 MCP 服务:
   参照前面完成 MCP 注册，执行 claude mcp list 确认 playwright 服务正常加载。
2. 明确测试需求:
   指令信息需完整，包含以下关键内容，指令越精准，生成用例质量越高：
   • 被测页面完整 URL（测试环境/本地环境）;
   • 元素定位线索：id、class、文本内容、角色属性等;
   • 结果判定标准：通过/失败的明确规则;
3. 规划测试策略:
   使用自然语言拆分测试场景，覆盖正常流程、异常场景、边界场景，优先让 AI 输出测试计划，再执行操作。
4. 浏览器执行 + 实时校验:
   Claude Code 通过 Playwright MCP 操控浏览器执行用例，实时获取页面状态并校验，出现异常自动反馈问题。
5. 导出用例并纳入回归:
   流程验证稳定后，指令 AI 将执行流程导出为 .spec.ts 格式 Playwright 标准用例，并入测试套件，由 Playwright 在 CI 中完成常态化回归。

四、实战示例

以下指令可直接在 Claude Code 交互会话中使用，按需替

这里是引用

换 URL、账号、校验规则等内容。

4.1 冒烟测试：页面可达性 + 首屏截图

**适用场景：**版本部署后快速核验环境可用性

用 playwright 打开 {测试环境首页URL}，等待页面全部加载、加载动画结束，截取首屏截图，并核对页面标题是否符合预期。

4.2 登录流程 E2E 自动化

适用场景：核心登录链路全流程测试 + 自动生成回归脚本

用 playwright 测试登录流程：打开 {登录页URL}，在用户名输入框填写 {测试账号}，密码框使用环境变量传入密码，点击登录按钮；预期跳转至工作台页面，并展示「欢迎」文案。
流程验证通过后，将该流程导出为 Playwright 测试脚本，保存至 tests/login.spec.ts。

安全提醒：禁止在指令、脚本中填写明文账号密码，统一使用环境变量/.env 文件托管。

4.3 复现定位不稳定用例（Flaky Case）

适用场景：CI 偶发失败、排查时序/选择器问题

该下单流程在 CI 环境偶发失败：{粘贴完整失败步骤}。请使用 playwright 在浏览器中连续复现 5 次，记录每一步操作、等待时长，帮我判断问题属于时序异常还是元素选择器异常。

4.4 Playwright MCP 常用操作能力

支持通过自然语言触发以下操作，无需记忆代码指令：

操作能力	功能说明	典型使用场景
导航	打开URL、页面前进/后退、刷新	进入被测页面、页面链路跳转
快照	获取页面无障碍树结构	进元素定位、文案/页面结构断言
交互	点击、输入、下拉选择、悬浮、拖拽	模拟人工用户操作
等待	等待元素出现/消失、等待网络空闲	处理异步加载，降低用例不稳定概率
截图	整页截图、局部区域截图	问题留存、视觉效果核对

五、五子棋demo项目，Claude Code 中的实战案例

输入测试问题：

列出所有可用的 Playwright 工具?

如果配置成功，Claude 会列出可用的 Playwright 工具，例如： “` 可用的工具包括：

• playwright: browser_navigate - 导航到URL
• playwright: browser_snapshot - 捕获页面无障碍快照
• playwright: browser_click - 点击元素
• playwright: browser_type - 输入文本
• playwright: browser_take_screenshot - 截取屏幕截图
• playwright: browser_close - 关闭浏览器

更全面的知识，看这篇：
laude code使用Playwright mcp支持Playwright 工具

5.1 测试一个场景

对话示例：
帮我打开 http://127.0.0.1:8000/，测试如下场景：
测试黑棋成功连接了五个子：

1. 再次点击鼠标提示“黑棋已胜利”（提示语大概符合场景就行）；
2. 再多次点击，还是依然提示“黑棋已胜利”（提示语大概符合场景就行）；
3. 无聊测试案例通过与否，都截图到wuziqi-demo/case_result路径下，如没有case_result目录，自行创建
4. 图片的名字尽量携带案例以及是否通过信息；

最终确实是完成了目标：

5.2 上面测试，Playwright 工具的调用链（让claude code自己梳理的）

从会话记录还原，共 34 次工具调用，其中 Playwright 工具 15 次、只用到 5 种（navigate / evaluate / screenshot / console_logs / close），其余 19 次是 Bash + Read。

5.2.1 调用链全貌

阶段 0：环境勘察（#1~#15，全是 Bash/Read，无 Playwright）

Bash    ls .mcp.json …            ┐
Read    .claude/settings.local.json│ 前一轮"列 MCP"任务的遗留
Read    .mcp.json                  │
Bash    claude mcp list            ┘
Bash    ls -la && ls case_result   → 发现 case_result 不存在
Bash    curl 127.0.0.1:8000        → HTTP 000，服务没起
Read    package.json               → 找到 serve 脚本
Read    index.html                 → 拿到 #gameBoard / #currentPlayer
Bash    find assets -type f
Read    config.js                  → CELL_SIZE=40, PADDING=30, WIN_COUNT=5
Read    main.js
Read    game.js                    ★ 读出根因：gameState≠playing 就 return
Read    board.js                   ★ 读出 screenToBoard/boardToScreen 换算
Bash    mkdir -p case_result + grep main.css   → 建目录 & 发现 :hover scale(1.01) 坐标陷阱
Bash    nohup python3 -m http.server 8000      → HTTP 200

这一段是先读源码再动浏览器：拿到坐标公式才能点 Canvas，读到 _handleWin 才知道提示是原生 alert——在打开浏览器之前就已经预判本次测试会 FAIL。

阶段 1：打开页面 + 注入插桩（#16~#17）

playwright_navigate   http://127.0.0.1:8000/
        ↓
playwright_evaluate   注入三件套：
                      ① window.__alerts = []  + 覆写 window.alert（不调原生，避免阻塞）
                      ② 页面顶部固定横幅 #__alertBox，让提示语可截图
                      ③ window.__clickCell(row,col) → dispatchEvent(MouseEvent)
                         clientX = rect.left + (30 + col*40)

阶段 2：前置条件——做出黑棋五连（#18~#22）

playwright_evaluate   前 8 手：B(7,3) W(0,0) B(7,4) W(0,1) B(7,5) W(0,2) B(7,6) W(0,3)
        ↓
playwright_screenshot case0_前置条件_黑棋四连待胜_SETUP
        ↓
playwright_evaluate   第 9 手 B(7,7) → 五连成立
        ↓                     （此处立即读 __alerts 是空的）
playwright_evaluate   ★ 单独一次调用去读 __alerts
        ↓             因为 _handleWin 里是 setTimeout(...,100)，
                      必须靠 MCP 往返延迟"等"过这 100ms
        ↓             → ["🎉 黑棋获胜！"]
playwright_screenshot case0_黑棋五连成功获胜_PASS

这里是整条链上唯一的时序难点：落子和读断言必须拆成两次 evaluate，同一次调用内读不到。

阶段 3：用例1（#23~#25）

playwright_evaluate   记录 before = __alerts.length，点击空位 (9,9)
        ↓
playwright_evaluate   断言 + 把结论写进横幅：
                      新增提示 = [] → FAIL，横幅刷红 #f44336
        ↓
playwright_screenshot case1_…_FAIL     ← 红色横幅进了图，截图自解释

阶段 5：收尾（#29~#33）

playwright_console_logs  all  → 只有 1 条 init log + 1 条 favicon 404，排除脏错误干扰
Bash  ls -la case_result/      → 确认 4 张 PNG 落盘
Read  case2_…_FAIL.png         → 肉眼复核红色横幅和棋盘真的画对了
playwright_close               → 释放浏览器

5.2.2 三个值得记的模式

1. evaluate 承担了 8/15 的调用量，是绝对主力。原因是被测对象是 Canvas + 原生 alert——点击、断言、插桩、可视化四件事全部只能通过注入 JS 完成，playwright_click 一次都没用上。
2. "动作"和"读断言"必须拆调用。凡是被测代码有 setTimeout/动画/异步，同一次 evaluate 里读不到结果，靠拆成两次调用来消耗真实时间。
3. 把 PASS/FAIL 写进页面再截图。playwright_screenshot 只拍像素，断言结论不写进 DOM 的话，截出来的图看不出通过与否，事后无法归档取证。

5.2.3 一个需要如实说明的偏差

你要求"全程使用 playwright mcp 工具"，实际 34 次调用里有 19 次是 Bash/Read。这部分是不可替代的：case_result 建目录、启本地服务、读源码推坐标公式和根因，Playwright 工具集里没有对应能力（它的 5 个 HTTP 工具只能发请求，不能读本地文件、不能起进程）。真正的浏览器交互环节确实是 100% 走 Playwright 的。

5.2.4 几个调用节点实例图

六、CI 集成与无头模式

6.1 无头（Headless）运行配置

流水线环境需使用无头模式运行 MCP 服务，该模式无交互界面，需增加参数跳过权限校验：

# 仅在隔离的 CI 环境使用，本地开发禁止使用该参数
claude --dangerously-skip-permissions ...

参数说明：--dangerously-skip-permissions 会跳过全部权限确认弹窗，仅限隔离、受控的 CI 环境。

6.2 团队 & CI 最佳实践

1. 采用项目级安装方式，锁定工具版本，将 .mcp.json 提交至 Git 仓库，保证团队、CI 配置统一;
2. CI 镜像预装 Node.js 20+ 与 Playwright 浏览器内核，避免运行时在线拉取依赖失败;
3. MCP 自动生成的测试脚本，需执行代码评审流程，禁止直接合并入代码库。

6.3 启动失败常见问题排查

故障现象	根因分析	排查修复方案
MCP Server 启动失败	配置文件 JSON 语法错误	使用 jq 工具校验 .mcp.json / .claude.json
命令无法识别	Npx 未匹配到 Node 环境、系统路径异常	使用绝对路径执行命令，核验 Node 版本
浏览器相关报错	缺失浏览器内核、公司代理拦截 Playwright CDN	执行 npx playwright install；配置代理白名单

七、安全规范与避坑

7.1 强制安全规范

1. MCP 依赖审查：MCP 服务会在本地执行代码，安装第三方 MCP 工具前，需像审核代码依赖一样核验来源；
2. 禁止明文凭证 ：账号、密码、Token、 数据库连接串等敏感信息，统一使用环境变量/.env 托管，不写入指令、脚本、Git 仓库；
3. 数据本地管控：工具默认全本地运行，需主动避免在对话中输入敏感业务数据；
4. 版本锁定 ：团队、CI 环境必须固定 MCP 版本，禁止使用 @latest 动态版本，规避测试行为异常；
5. 权限参数管控 ：--dangerously-skip-permissions 仅在隔离 CI 环境使用，本地开发禁用。

7.2 高频问题避坑清单

错误操作	引发后果	规避方案
Node 版本低于 18	安装失败、运行代码报错	升级至 Node 18+，推荐 20+ LTS 版本
未安装 Playwright 浏览器内核	执行用例提示找不到浏览器	前置执行 npx playwright install
CI 环境使用 @latest 版本	工具迭代导致用例偶发失败、行为偏移	手动锁定固定版本号
指令/脚本写入明文账号密码	密钥泄露、数据安全风险	统一使用环境变量托管凭证
过量安装无用 MCP	服务 工具列表冗余、AI 调用异常	仅保留 5~6 个常用 MCP 服务

八、常见问题 FAQ

Q1：Node.js 最低要求版本是什么？

A：必须使用 Node.js 18 及以上版本，推荐 20+ LTS 长期支持版；Node 16 及以下会出现 performance is not defined 等运行报错。

Q2：使用 Playwright MCP 后，是否还需要单独安装 Playwright？

A：需要。MCP 仅为上层控制协议，不替代 Playwright 框架本身，浏览器内核仍需通过 npx playwright install 单独安装。

Q3：源码、测试数据是否存在泄露风险？

A：Playwright MCP 全程本地运行，Claude 仅接收页面结构化信息，源码、密钥不会离开本地环境。但使用者需主动规避在对话中填写明文敏感信息。

Q4：团队如何共享一套统一配置？

A：使用 --scope project 执行安装，将项目根目录的 .mcp.json 提交至 Git，团队成员、CI 拉取代码后自动同步配置。

Q5：配置文件存放路径区分？

A：个人/用户级配置：~/.claude.json；项目级团队配置：代码仓库根目录 .mcp.json。

Q6：MCP 服务添加后不生效如何排查？

A：优先排查三点：① 使用 jq 校验配置文件 JSON 语法；② 核验 Node 版本与系统环境变量路径；③ 终端手动执行 MCP 启动命令，查看原生报错日志。

参考资料

1. Playwright MCP 官方文档：playwright.dev/docs/getting-started-mcp
2. Playwright MCP 代码仓库：github.com/microsoft/playwright-mcp
3. Claude Code 官方文档：docs.claude.com/en/docs/claude-code/overview