# Claude Code + Playwright MCP 使用
目录
一、概述与适用场景 … 3
二、工作原理 … 4
三、环境准备与安装配置 … 5
四、标准测试工作流 … 7
五、实战示例 … 8
六、CI 集成与无头模式 … 10
七、安全规范与避坑 … 11
八、常见问题 FAQ … 12
一、概述与适用场景
1.1 组件介绍
Claude Code
Anthropic 推出的终端原生 AI 编码代理，运行于代码仓库本地。支持分析代码、规划多步改造、跨文件执行任务，同时可通过MCP 协议对接各类外部工具。
Playwright MCP
微软官方@playwright/mcp工具包，基于Model Context Protocol为 AI 代理提供浏览器直接控制能力。
该组件依托页面无障碍树完成元素交互，而非图像识别，相比视觉类方案运行速度更快、Token 消耗更低。
组合能力说明
二者搭配可实现：在终端内通过自然语言驱动真实浏览器、完成页面行为校验，并自动将稳定流程生成标准 Playwright 测试代码。打通「需求梳理 → 流程验证 → 回归用例落地」全流程。
1.2 适用场景
- 自助 QA：指向线上/测试环境应用，AI 自动遍历核心流程并输出问题报告
- 探索式测试：自然语言描述测试场景，AI 操控浏览器完成全流程验证
- 不稳定用例复现：反复执行偶发失败流程，定位时序、元素选择器等问题
- 自动化用例生成：流程验证通过后，一键生成 E2E 测试脚本，纳入回归套件
- 流水线自动化：以无头模式运行在 CI 流水线，自动执行测试、补充用例
1.3 CLI codegen 与 MCP 方案取舍
Playwright 原生codegen/CLI适用于手动录制、编写基础脚本；
Playwright MCP 核心能力是让 AI 通过自然语言驱动浏览器，跳过纯手工编写环节。
两种方案互补：
- MCP：快速探索业务流程、验证场景、生成初始测试代码
- Playwright 原生 CLI：承接已稳定脚本，在 CI 中执行常态化回归
定位总结：MCP 为上层控制能力，不会替代 Playwright 框架本身。
二、工作原理
2.1 三层架构
整套链路分为推理层、协议层、执行层，分层职责如下：
| 层级 | 组件 | 核心职责 |
|---|---|---|
| 推理层 | Claude Code | 理解测试需求、制定测试策略、生成代码、解析执行结果 |
| 协议层 | MCP(Model Context Protocol) | 标准化工具调用通道，转发页面导航、点击、输入等指令 |
| 执行层 | Playwright MCP Server | 启动并操控浏览器（Chromium/Firefox/WebKit），执行指令并回传结构化结果 |
2.2 核心运行机制
- 基于无障碍树交互
读取页面结构化快照定位操作元素，不依赖截图/视觉识别，具备速度快、低 Token、稳定性强的特点。 - Stdio 传输模式
Playwright MCP 默认采用 stdio 通信，完美适配 Claude Code 传输要求，无需额外配置端口、独立服务。 - 全本地执行
浏览器、源码、测试数据、密钥均保留在本地环境，Claude 仅获取结构化执行上下文，敏感信息不会向外泄露。
三、环境准备与安装配置
3.1 前置条件
- Node.js 18.0 及以上版本（推荐 LTS 版本），执行
node --version核验版本；Node 16 及以下会出现performance is not defined等报错。 - 已完成 Claude Code 安装与登录，终端可正常执行
claude进入交互会话。 - 已安装 Playwright 浏览器内核，首次部署执行命令：
npx playwrightinstall
3.2 快速注册 Playwright MCP
启动 Claude Code 会话前，执行以下命令完成注册：
claude mcpaddplaywright npx @playwright/mcp@latest配置会自动持久化至~/.claude.json，标准网络环境下整体安装时长不超过 5 分钟。
3.3 安装范围（Scope）说明
通过--scope参数控制配置生效范围，--transport、--scope、--env等参数需写在服务名称前。
| 范围参数 | 配置文件位置 | 生效范围 | 适用场景 |
|---|---|---|---|
| local（默认） | ~/.claude.json | 当前项目、当前用户 | 临时功能试用 |
| user | ~/.claude.json | 本机全部项目、当前用户 | 个人长期使用 |
| project | 项目根目录.mcp.json | 提交 Git 后全团队共享 | 团队协作、CI 流水线 |
团队/CI 标准配置示例
将配置写入项目级文件并同步至代码仓库，建议锁定版本号，禁止直接使用@latest，避免测试环境异常：
claude mcpaddplaywright--scopeproject npx @playwright/mcp@<指定版本号>补充说明：团队统一版本号可查阅 Playwright MCP 官方仓库确认。
3.4 安装验证
- 查看已注册 MCP 服务列表：
claude mcp list - 启动 Claude Code 会话，输入自然语言指令验证连通性：
用 playwright 打开 https://example.com，页面加载完成后截取首屏图片。 - 校验标准：浏览器自动拉起、页面正常加载、成功生成截图，代表配置生效。
四、标准测试工作流
标准化测试流程分为 5 个阶段，熟悉后可常态化复用：
配置 MCP 服务
参照第三章完成 MCP 注册，执行claude mcp list确认playwright服务正常加载。明确测试需求
指令信息需完整，包含以下关键内容，指令越精准，生成用例质量越高：- 被测页面完整 URL（测试环境/本地环境）
- 元素定位线索：id、class、文本内容、角色属性等
- 结果判定标准：通过/失败的明确规则
规划测试策略
使用自然语言拆分测试场景，覆盖正常流程、异常场景、边界场景，优先让 AI 输出测试计划，再执行操作。浏览器执行 + 实时校验
Claude Code 通过 Playwright MCP 操控浏览器执行用例，实时获取页面状态并校验，出现异常自动反馈问题。导出用例并纳入回归
流程验证稳定后，指令 AI 将执行流程导出为.spec.ts格式 Playwright 标准用例，并入测试套件，由 Playwright 在 CI 中完成常态化回归。
五、实战示例
以下指令可直接在 Claude Code 交互会话中使用，按需替换 URL、账号、校验规则等内容。
5.1 冒烟测试：页面可达性 + 首屏截图
适用场景：版本部署后快速核验环境可用性
用 playwright 打开 {测试环境首页URL}，等待页面全部加载、加载动画结束，截取首屏截图，并核对页面标题是否符合预期。5.2 登录流程 E2E 自动化
适用场景：核心登录链路全流程测试 + 自动生成回归脚本
用 playwright 测试登录流程：打开 {登录页URL}，在用户名输入框填写 {测试账号}，密码框使用环境变量传入密码，点击登录按钮；预期跳转至工作台页面，并展示「欢迎」文案。 流程验证通过后，将该流程导出为 Playwright 测试脚本，保存至 tests/login.spec.ts。安全提醒：禁止在指令、脚本中填写明文账号密码，统一使用环境变量/
.env文件托管。
5.3 复现定位不稳定用例（Flaky Case）
适用场景：CI 偶发失败、排查时序/选择器问题
该下单流程在 CI 环境偶发失败：{粘贴完整失败步骤}。请使用 playwright 在浏览器中连续复现 5 次，记录每一步操作、等待时长，帮我判断问题属于时序异常还是元素选择器异常。5.4 Playwright MCP 常用操作能力
支持通过自然语言触发以下操作，无需记忆代码指令：
| 操作能力 | 功能说明 | 典型使用场景 |
|---|---|---|
| 导航 | 打开URL、页面前进/后退、刷新 | 进入被测页面、页面链路跳转 |
| 快照 | 获取页面无障碍树结构 | 元素定位、文案/页面结构断言 |
| 交互 | 点击、输入、下拉选择、悬浮、拖拽 | 模拟人工用户操作 |
| 等待 | 等待元素出现/消失、等待网络空闲 | 处理异步加载，降低用例不稳定概率 |
| 截图 | 整页截图、局部区域截图 | 问题留存、视觉效果核对 |
六、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 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 启动命令，查看原生报错日志。
参考资料
- Playwright MCP 官方文档：playwright.dev/docs/getting-started-mcp
- Playwright MCP 代码仓库：github.com/microsoft/playwright-mcp
- Claude Code 官方文档：docs.claude.com/en/docs/claude-code/overview