Playwright MCP项目实战：基于提示的浏览器测试与代码生成

1. 为什么我把 Playwright MCP 接进了日常测试流Playwright MCP 是一套把浏览器自动化能力通过 Model Context Protocol 暴露给 AI 客户端的服务它能让 Cline、Windsurf 这类支持 MCP 的编辑器用自然语言直接驱动 Chromium 打开页面、点击元素、填表单、抓断言结果。适合谁适合已经在写 Playwright 脚本、但厌倦了每次改选择器都要重跑一遍的测试同学也适合想用提示词快速生成可跑测试代码的前端和 QA。我之前的痛点很具体一个后台登录用例页面改一次 class 名脚本就红一次想临时验证一个边界场景又得新建文件、写 fixture、配断言十分钟起步。Playwright MCP 把这段压缩成一句话——打开登录页用 testexample.com 登录确认跳转到 dashboard——AI 自己调工具完成操作还能把过程整理成 Playwright 代码。但真正落地时会撞上两个坑一是 MCP 服务本地起不来或客户端连不上报local proxy failed二是模型通道不稳定401 或reading choices直接中断。这篇就按起服务 → 接客户端 → 跑三类用例 → 排错 → 统一 Key 通道的顺序写配置都能直接复制。2. 起本地 Playwright MCP 服务与客户端接入前置2.1 环境与安装Node.js 18 是硬要求低于这个版本playwright/mcp会报模块解析错误。先装 MCP 服务本体和浏览器npm install -g playwright/mcplatest npx playwright install chromium国内网络下载浏览器慢的话加镜像变量再装export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromium装完验证一下服务能起来npx playwright/mcplatest --help能看到--headless、--browser、--viewport-size这些参数就说明本体没问题。默认它以 stdio 方式通信客户端负责拉起进程不需要你手动常驻。2.2 Cline MCP 配置Cline 的 MCP 配置在设置面板的 MCP Servers 里本质是写一个 JSON。路径通常在~/.cline/mcp_settings.json不同版本可能落在插件目录下以界面显示的路径为准。写入{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest, --headless], env: { PLAYWRIGHT_DOWNLOAD_HOST: https://npmmirror.com/mirrors/playwright }, timeout: 300 } } }-y很关键避免 npx 首次运行时弹交互确认卡住进程。timeout给到 300 秒因为首次拉起浏览器实例会慢。2.3 Windsurf BYOK 接入Windsurf 走 BYOKBring Your Own Key时MCP 配置写在~/.codeium/windsurf/mcp_config.json。结构类似但要注意它要求显式声明传输方式{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest], transport: stdio } } }Windsurf 里模型通道和 MCP 是两套配置MCP 管工具模型管推理。BYOK 的 Base URL 和 Key 在模型设置里填下一节讲怎么把 endpoint 指到统一通道。2.4 三件套Base URL Key Model ID不管 Cline 还是 Windsurf只要涉及模型调用都要凑齐这三样缺一个就连不上配置项填什么说明Base URLhttps://taotoken.net/api统一入口末尾不要带斜杠API Key控制台生成的sk-开头串在 API Keys 页面创建Model ID如claude-sonnet-4-5等以文档模型列表为准Cline 里选 OpenAI Compatible 提供商把 Base URL 填进去Windsurf BYOK 选自定义 endpoint同样填这个地址。Key 只填一次MCP 工具调用和模型推理共用这条通道省得来回切。3. 可复制的 MCP 配置与提示词模板3.1 完整 settings 片段把下面这段直接贴进 Cline 的 MCP 配置同时把模型通道也配好。注意env里可以塞统一通道的地址方便后续切换{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest, --headless, --viewport-size1280,800], env: { PLAYWRIGHT_DOWNLOAD_HOST: https://npmmirror.com/mirrors/playwright }, timeout: 300 } } }模型侧以 OpenAI Compatible 为例在 Cline 的 API 配置里填{ provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-5 }3.2 三类用例的提示词模板登录类重点是给出账号和成功标志打开 https://example.com/login在用户名框输入 testexample.com 密码框输入 123456点击登录按钮等待跳转后确认页面出现 Dashboard 文本。 把整个过程整理成 Playwright Python 测试函数。表单类强调字段和提交后校验访问 https://example.com/signup填写邮箱、昵称、密码三个字段 勾选同意条款提交表单断言出现 注册成功 提示。 如果某个字段有校验错误把错误文本抓出来。断言类让 AI 明确比对目标打开 https://example.com/pricing抓取三个套餐的价格文本 断言 Pro 套餐价格等于 $29并截图保存到 ./shots/pricing.png。提示词里带上整理成 Playwright 代码这句AI 会在操作完成后输出可复用的脚本而不是只给一段执行日志。3.3 把 endpoint 改到统一 Key 通道如果你在多个客户端之间切换最省事的做法是让所有模型请求都走同一个 Base URL。Cline 里改baseUrl为https://taotoken.net/apiWindsurf BYOK 里改自定义 endpoint 为同一地址Key 用同一个。这样 MCP 工具调用触发的模型推理不会因为通道不同而报 401。改完记得重启客户端让配置重新加载。4. 验证请求与成功结果4.1 跑通登录用例在 Cline 对话框里贴登录提示词回车。正常流程是AI 先调browser_navigate打开页面再调browser_snapshot拿可访问性树然后browser_type填两个输入框browser_click点按钮最后browser_wait_for等 Dashboard 文本。整个过程在 Cline 的工具调用面板里能看到每一步。成功时你会看到类似输出✓ Navigated to https://example.com/login ✓ Typed testexample.com into #username ✓ Typed 123456 into #password ✓ Clicked button 登录 ✓ Found text Dashboard并且 AI 会附上一段生成的 Playwright 代码from playwright.sync_api import sync_playwright def test_login(): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page() page.goto(https://example.com/login) page.fill(#username, testexample.com) page.fill(#password, 123456) page.click(button:has-text(登录)) page.wait_for_selector(textDashboard) assert page.is_visible(textDashboard) browser.close()4.2 表单与断言用例表单用例跑通后AI 会返回提交结果和字段校验信息。断言用例则会输出抓到的价格文本和截图路径。截图默认落在 MCP 工作目录下的./shots/如果目录不存在会报错提前mkdir -p shots即可。4.3 一次失败重试的验证动作故意把密码改错观察 AI 怎么处理。它会点登录后等不到 Dashboardbrowser_wait_for超时然后调browser_snapshot重新看页面发现出现 密码错误 文本于是报告失败原因。这个重试动作是 MCP 的价值点——它不盲目重跑而是先观察再决策。你可以接着发一句把错误提示抓出来并生成一个断言失败的测试AI 会补上assert page.is_visible(text密码错误)5. 本篇常见错排查5.1 401 Unauthorized模型通道的 Key 不对或过期。检查 Cline/Windsurf 里填的apiKey是否和控制台一致Base URL 是否为https://taotoken.net/api。如果 Key 刚创建等几秒再试避免缓存。401 只跟模型通道有关跟 MCP 服务本身无关别去重装 Playwright。5.2 local proxy failed这个报错通常出现在客户端拉起 MCP 进程时。原因有三npx 首次运行卡在交互确认、Node 版本过低、或command路径不对。解决args 里加-y确认node -v在 18 以上把command从npx换成绝对路径which npx查出来填进去。改完重启客户端。5.3 reading choices 报错这是模型返回体结构不符合预期多半是 Base URL 末尾多了斜杠或少了/api。正确写法是https://taotoken.net/api不要写成https://taotoken.net/api/或https://taotoken.net。改完在 Cline 里点一下测试连接通了再跑用例。5.4 OAuth 相关报错Windsurf BYOK 有时会弹 OAuth 登录如果你用的是自定义 endpoint需要在设置里关掉官方登录态选 Custom 或 BYOK 模式。否则它会拿官方 token 去请求你的 endpoint直接 403。关掉后重新填 Base URL 和 Key。5.5 浏览器起不来--headless模式下如果报缺少系统依赖Linux 上跑npx playwright install-deps chromium补依赖。macOS 一般不会遇到。另外--viewport-size参数格式是宽,高中间是英文逗号写成中文逗号会解析失败。6. 把通道固定下来让 MCP 跑得更稳跑通三类用例后我做的第一件事是把所有客户端的模型通道统一到同一个 Base URL 和 Key。Cline、Windsurf、以及后续可能加的 Claude Code全部指向https://taotoken.net/api。这样 MCP 工具调用触发的推理不会因为通道切换而中断排错时也只需要看一个地方。如果你要长期跑编码和 Agent 任务可以考虑 Coding Plan额度更稳只是临时验证模型行为用模型对话页面就够。Key 在 API Keys 页面管理接入细节看文档。把 endpoint 固定下来之后Playwright MCP 的提示词测试和代码生成就能稳定串起来剩下的就是攒你自己的提示词模板库了。