一、claude code 配置playwrite mcp步骤 1安装必要组件# 安装 Playwright 测试框架npminstall-gplaywright/test# 安装 Playwright MCP 服务端npminstall-gexecuteautomation/playwright-mcp-server# 安装浏览器依赖会下载 Chromium、Firefox 等npx playwrightinstall此步骤确保本地具备运行 Playwright MCP 所需的环境。步骤 2移除旧配置如有claude mcp remove playwright-slocal步骤 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验证配置是否成功查看已注册 MCP 服务列表#查看配置是否正确claude mcp list测试连接这里我测试成功# 测试连接会看到很多调试信息找到这一行就是成功了# windows 方法claude--print测试playwright--debug|findstrconnected# mac 方法claude--print测试playwright--debug|grepconnected网上说如果输出中包含 connected说明 Claude 已成功连接到 Playwright MCP像图片中这样实际我操作过程中等了很长时间都没有日志打印我也不知道我到底安装成功没so我只能另辟蹊径了。我的测试进入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--browserchrome--port8931然后在配置中使用 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.json2.1.x我的版本Linux/macOS: 在~/.claude.jsoncat ~/.claude.json三、标准测试工作流配置 MCP 服务:参照前面完成 MCP 注册执行claude mcp list确认playwright服务正常加载。明确测试需求:指令信息需完整包含以下关键内容指令越精准生成用例质量越高被测页面完整 URL测试环境/本地环境;元素定位线索id、class、文本内容、角色属性等;结果判定标准通过/失败的明确规则;规划测试策略:使用自然语言拆分测试场景覆盖正常流程、异常场景、边界场景优先让 AI 输出测试计划再执行操作。浏览器执行 实时校验:Claude Code 通过 Playwright MCP 操控浏览器执行用例实时获取页面状态并校验出现异常自动反馈问题。导出用例并纳入回归:流程验证稳定后指令 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 - 导航到URLplaywright: 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/测试如下场景测试黑棋成功连接了五个子再次点击鼠标提示“黑棋已胜利”提示语大概符合场景就行再多次点击还是依然提示“黑棋已胜利”提示语大概符合场景就行无聊测试案例通过与否都截图到wuziqi-demo/case_result路径下如没有case_result目录自行创建图片的名字尽量携带案例以及是否通过信息最终确实是完成了目标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无 PlaywrightBashls.mcp.json … ┐ Read .claude/settings.local.json│ 前一轮列 MCP任务的遗留 Read .mcp.json │ Bash claude mcp list ┘ Bashls-lalscase_result → 发现 case_result 不存在 Bashcurl127.0.0.1:8000 → HTTP 000服务没起 Read package.json → 找到 serve 脚本 Read index.html → 拿到#gameBoard / #currentPlayerBashfindassets-typef Read config.js →CELL_SIZE40,PADDING30,WIN_COUNT5Read main.js Read game.js ★ 读出根因gameState≠playing 就returnRead board.js ★ 读出 screenToBoard/boardToScreen 换算 Bashmkdir-pcase_result grepmain.css → 建目录发现 :hover scale(1.01)坐标陷阱 Bashnohuppython3-mhttp.server8000→ HTTP200这一段是先读源码再动浏览器拿到坐标公式才能点Canvas读到_handleWin才知道提示是原生 alert——在打开浏览器之前就已经预判本次测试会 FAIL。阶段 1打开页面 注入插桩#16~#17playwright_navigate http://127.0.0.1:8000/ ↓ playwright_evaluate 注入三件套 ① window.__alerts[] 覆写 window.alert不调原生避免阻塞 ② 页面顶部固定横幅#__alertBox让提示语可截图③ window.__clickCell(row,col)→ dispatchEvent(MouseEvent)clientXrect.left (30 col*40)阶段 2前置条件——做出黑棋五连#18~#22playwright_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~#25playwright_evaluate 记录 before__alerts.length点击空位(9,9)↓ playwright_evaluate 断言 把结论写进横幅 新增提示[]→ FAIL横幅刷红#f44336↓ playwright_screenshot case1_…_FAIL ← 红色横幅进了图截图自解释阶段 5收尾#29~#33playwright_console_logs all → 只有1条 init log 1条 favicon404排除脏错误干扰 Bashls-lacase_result/ → 确认4张 PNG 落盘 Read case2_…_FAIL.png → 肉眼复核红色横幅和棋盘真的画对了 playwright_close → 释放浏览器5.2.2 三个值得记的模式evaluate承担了 8/15 的调用量是绝对主力。原因是被测对象是 Canvas 原生alert——点击、断言、插桩、可视化四件事全部只能通过注入 JS 完成playwright_click一次都没用上。动作和读断言必须拆调用。凡是被测代码有setTimeout/动画/异步同一次evaluate里读不到结果靠拆成两次调用来消耗真实时间。把 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 最佳实践采用项目级安装方式锁定工具版本将.mcp.json提交至 Git 仓库保证团队、CI 配置统一;CI 镜像预装 Node.js 20 与 Playwright 浏览器内核避免运行时在线拉取依赖失败;MCP 自动生成的测试脚本需执行代码评审流程禁止直接合并入代码库。6.3 启动失败常见问题排查故障现象根因分析排查修复方案MCP Server 启动失败配置文件 JSON 语法错误使用 jq 工具校验 .mcp.json / .claude.json命令无法识别Npx 未匹配到 Node 环境、系统路径异常使用绝对路径执行命令核验 Node 版本浏览器相关报错缺失浏览器内核、公司代理拦截 Playwright CDN执行 npx playwright install配置代理白名单七、安全规范与避坑7.1 强制安全规范MCP 依赖审查MCP 服务会在本地执行代码安装第三方 MCP 工具前需像审核代码依赖一样核验来源禁止明文凭证账号、密码、Token、 数据库连接串等敏感信息统一使用环境变量/.env 托管不写入指令、脚本、Git 仓库数据本地管控工具默认全本地运行需主动避免在对话中输入敏感业务数据版本锁定团队、CI 环境必须固定 MCP 版本禁止使用latest动态版本规避测试行为异常权限参数管控--dangerously-skip-permissions仅在隔离 CI 环境使用本地开发禁用。7.2 高频问题避坑清单错误操作引发后果规避方案Node 版本低于 18安装失败、运行代码报错升级至 Node 18推荐 20 LTS 版本未安装 Playwright 浏览器内核执行用例提示找不到浏览器前置执行npx playwright installCI 环境使用latest版本工具迭代导致用例偶发失败、行为偏移手动锁定固定版本号指令/脚本写入明文账号密码密钥泄露、数据安全风险统一使用环境变量托管凭证过量安装无用 MCP服务 工具列表冗余、AI 调用异常仅保留 5~6 个常用 MCP 服务八、常见问题 FAQQ1Node.js 最低要求版本是什么A必须使用 Node.js 18 及以上版本推荐 20 LTS 长期支持版Node 16 及以下会出现 performance is not defined 等运行报错。Q2使用 Playwright MCP 后是否还需要单独安装 PlaywrightA需要。MCP 仅为上层控制协议不替代 Playwright 框架本身浏览器内核仍需通过npx playwright install单独安装。Q3源码、测试数据是否存在泄露风险APlaywright MCP 全程本地运行Claude 仅接收页面结构化信息源码、密钥不会离开本地环境。但使用者需主动规避在对话中填写明文敏感信息。Q4团队如何共享一套统一配置A使用--scope project执行安装将项目根目录的.mcp.json提交至 Git团队成员、CI 拉取代码后自动同步配置。Q5配置文件存放路径区分A个人/用户级配置~/.claude.json项目级团队配置代码仓库根目录.mcp.json。Q6MCP 服务添加后不生效如何排查A优先排查三点① 使用 jq 校验配置文件 JSON 语法② 核验 Node 版本与系统环境变量路径③ 终端手动执行 MCP 启动命令查看原生报错日志。参考资料Playwright MCP 官方文档playwright.dev/docs/getting-started-mcpPlaywright MCP 代码仓库github.com/microsoft/playwright-mcpClaude Code 官方文档docs.claude.com/en/docs/claude-code/overview