Playwright与MCP协议结合：构建智能UI自动化测试新范式

1. 项目概述：当Playwright遇上MCP，UI自动化测试的范式革新

最近在搞UI自动化测试的朋友，估计都绕不开Playwright这个明星框架。它确实好用，跨浏览器、速度快、API设计优雅。但不知道你有没有遇到过这样的场景：测试脚本越写越多，维护成本越来越高；不同项目间的测试用例复用困难；或者，你看着那些复杂的业务流，心里琢磨着“要是能有个更智能的方式来描述和执行测试就好了”。如果你有这些痛点，那么“Playwright MCP实现UI自动化测试”这个组合，可能会给你打开一扇新的大门。

简单来说，这个项目探讨的是如何用MCP（Model Context Protocol）协议来“赋能”Playwright，构建一个更智能、更灵活、更易于管理的UI自动化测试体系。它不是要取代Playwright，而是为它加上一个“大脑”和“协调中枢”。MCP本身是一个新兴的、旨在标准化AI模型与外部工具/数据源交互的协议。把它引入UI自动化领域，意味着我们可以让大语言模型（LLM）直接理解并操作浏览器，或者让测试脚本的生成、维护、执行变得更具“语义化”和“意图驱动”。

这解决了什么问题？传统UI自动化测试往往是“脚本驱动”的：工程师需要精确地编写每一步操作（点击哪个按钮、在哪个输入框填什么值）。而MCP的引入，可以转向“意图驱动”或“自然语言驱动”。比如，你可以对AI说：“帮我在购物网站上完成一次从搜索‘手机’到加入购物车的完整流程测试”，AI通过MCP理解你的意图，调用封装好的Playwright能力块去执行，并返回结果。这极大地降低了编写和维护复杂端到端（E2E）测试用例的门槛和心智负担。无论是测试工程师、开发人员，还是对自动化感兴趣但编码能力稍弱的产品经理，都能从中受益，以一种更自然的方式参与到自动化测试的构建中。

2. 核心架构与设计思路拆解

2.1 为什么是Playwright + MCP？

首先得说说为什么选这两个技术栈。Playwright的优势显而易见：它支持Chromium、Firefox、WebKit三大浏览器引擎，提供了同步和异步API，内置了自动等待、网络拦截、移动端模拟等强大功能，并且录制生成脚本的功能对新手友好。它的稳定性和功能完整性，使其成为现代Web自动化测试的首选工具之一。

而MCP，你可以把它想象成AI模型的“USB标准接口”。在MCP出现之前，如果你想让人工智能（比如Claude、GPT）去操作一个具体软件或访问特定数据，需要为每个AI模型和每个工具单独开发适配器，工作量大且不通用。MCP定义了一套标准的协议，让任何兼容MCP的AI模型（作为客户端）都能通过标准化的方式，去发现、调用任何同样兼容MCP的工具或数据源（作为服务器端）提供的“能力”。

把两者结合，其核心设计思路就是：将Playwright强大的浏览器操控能力，封装成一系列标准的、语义化的“工具”（Tools），并通过一个MCP服务器（MCP Server）暴露出来。这样，任何兼容MCP的AI客户端（如Claude Desktop、Cursor等集成了AI的IDE）都能直接“看到”并“使用”这些工具。

举个例子，没有MCP时，你需要直接写Playwright代码：await page.click(‘button#submit’)。有了MCP，你可以在AI对话中描述：“点击提交按钮”。AI客户端会理解你的意图，通过MCP协议询问Playwright MCP服务器：“你有‘点击元素’这个工具吗？”服务器回答：“有，这是它的使用说明（参数、格式）。”然后AI客户端就会构造一个格式化的请求给服务器：“调用‘点击元素’工具，参数是选择器‘button#submit’。”服务器收到后，执行真正的page.click()操作，并将结果（成功或失败）返回给AI客户端，最终呈现给你。

2.2 整体架构与数据流

一个典型的Playwright MCP UI自动化测试系统的架构可以分为三层：

1. MCP客户端层：通常是用户直接交互的界面，比如集成了Claude AI的Claude Desktop应用，或者配置了MCP客户端的代码编辑器（如Cursor）。用户在这里用自然语言提出测试需求。
2. MCP服务器层（核心枢纽）：这是我们项目需要实现的部分。它是一个独立的进程或服务，主要职责包括：
   • 实现MCP协议：处理来自客户端的连接、资源发现请求、工具调用请求。
   • 封装Playwright操作：将Playwright的API（打开浏览器、导航、定位、点击、输入、断言等）包装成一个个MCP工具。每个工具都有清晰的名称、描述和参数定义。
   • 管理浏览器上下文：维护Playwright的Browser、BrowserContext、Page等实例的生命周期。通常，一个MCP服务器会话会对应一个浏览器实例和一个主页面。
   • 执行与反馈：接收客户端发来的工具调用指令，翻译成Playwright代码执行，并将执行结果（成功、失败、返回数据、截图等）格式化成MCP协议要求的格式返回给客户端。
3. 浏览器层：由Playwright驱动和控制的真实或无头浏览器实例，执行具体的页面渲染和用户交互。

数据流非常清晰：用户自然语言指令 -> AI客户端理解并转化为工具调用请求 -> MCP服务器接收并执行对应Playwright操作 -> 操作结果经由MCP服务器返回给AI客户端 -> AI客户端组织语言向用户汇报结果。这个闭环使得用对话进行自动化测试成为可能。

注意：这里存在一个关键设计抉择：MCP服务器是提供“原子操作工具”（如click, type, get_text）让AI组合，还是提供“高阶业务流工具”（如login, search_product, checkout）？实践中，初期建议从原子工具开始，保证灵活性。随着积累，可以同时提供一些封装好的常用业务流工具，形成工具库。AI的强大之处在于它能根据你的需求，自动组合调用这些原子工具来完成复杂任务。

3. 搭建你的第一个Playwright MCP服务器

3.1 环境准备与依赖安装

让我们从零开始，动手搭建一个最简单的Playwright MCP服务器。你需要准备以下环境：

• Node.js：建议使用最新的LTS版本（如18.x或20.x），因为Playwright和相关的MCP库对Node版本有一定要求。
• 包管理工具：npm或yarn、pnpm均可。

首先，创建一个新的项目目录并初始化：

mkdir playwright-mcp-server && cd playwright-mcp-server npm init -y

接着，安装核心依赖。我们需要两个关键的npm包：

1. @modelcontextprotocol/sdk：这是官方提供的MCP服务器开发工具包（SDK），它封装了协议细节，让我们能专注于工具的实现。
2. playwright：当然是我们的主角，浏览器自动化库。

npm install @modelcontextprotocol/sdk playwright

安装Playwright时，它会默认下载Chromium、Firefox和WebKit的二进制文件。如果你只想测试特定浏览器，可以使用参数，比如npm install playwright-chromium。但为了演示的通用性，我们安装完整版。

实操心得：在国内网络环境下，Playwright浏览器二进制文件的下载可能会非常慢甚至失败。除了配置镜像源，更稳妥的方法是使用npx playwright install命令时加上--with-deps参数，并设置环境变量PLAYWRIGHT_DOWNLOAD_HOST为国内镜像站。例如：

PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install --with-deps chromium

先单独安装好所需的浏览器，可以避免后续运行时报错。

3.2 构建MCP服务器骨架

MCP SDK使用起来相对直观。我们在项目根目录创建一个名为server.js的文件。

// server.js import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { chromium } from 'playwright'; // 这里我们以Chromium为例 // 1. 创建MCP服务器实例 const server = new Server( { name: 'playwright-mcp-server', version: '0.1.0', }, { capabilities: { tools: {}, // 声明我们支持提供工具 }, } ); // 2. 初始化Playwright资源（稍后填充） let browser; let page; // 3. 定义工具（Tools）（稍后填充） // 4. 设置请求处理（稍后填充） // 5. 启动服务器，使用标准输入输出作为传输层 // 这使得它可以被任何MCP客户端（如Claude Desktop）通过命令行调用 const transport = new StdioServerTransport(); await server.connect(transport); console.error('Playwright MCP Server is running on stdio...');

这段代码搭建了服务器的基本骨架：引入必要的模块，创建Server实例，并准备通过标准输入输出（stdio）进行通信。这是MCP服务器最常见的一种运行方式，客户端（如Claude Desktop）会以子进程形式启动这个服务器，并通过管道进行通信。

3.3 实现核心Playwright工具

现在我们来填充核心部分：将Playwright操作定义为MCP工具。MCP协议中，一个工具需要定义name、description和inputSchema（输入参数的模式定义）。我们实现几个最常用的。

首先，在创建服务器实例后，定义启动浏览器的工具：

// ... 接上文 server.js ... // 工具：启动浏览器并打开新页面 server.setRequestHandler('tools/list', async () => { return { tools: [ { name: 'start_browser', description: '启动一个无头Chromium浏览器并创建一个新页面。', inputSchema: { type: 'object', properties: { headless: { type: 'boolean', description: '是否以无头模式运行（不显示GUI），默认为true。', default: true, }, }, }, }, // 其他工具将在这里添加 ], }; });

然后，我们需要处理客户端的工具调用请求。在server.setRequestHandler中为tools/call添加处理逻辑：

// ... 接上文 server.js ... server.setRequestHandler('tools/call', async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case 'start_browser': { const headless = args?.headless !== false; // 默认true browser = await chromium.launch({ headless }); const context = await browser.newContext(); page = await context.newPage(); return { content: [ { type: 'text', text: `浏览器已启动（无头模式：${headless}）。页面已创建。`, }, ], }; } case 'navigate': { if (!page) { throw new Error('请先使用 start_browser 工具启动浏览器。'); } const url = args?.url; if (!url || typeof url !== 'string') { throw new Error('参数“url”是必须的，且应为字符串。'); } await page.goto(url, { waitUntil: 'networkidle' }); // 等待页面加载完成 return { content: [ { type: 'text', text: `已导航至：${url}`, }, ], }; } case 'click': { if (!page) { throw new Error('请先使用 start_browser 工具启动浏览器。'); } const selector = args?.selector; if (!selector || typeof selector !== 'string') { throw new Error('参数“selector”是必须的，且应为字符串（CSS选择器）。'); } await page.click(selector); return { content: [ { type: 'text', text: `已点击元素：${selector}`, }, ], }; } case 'type_text': { if (!page) { throw new Error('请先使用 start_browser 工具启动浏览器。'); } const selector = args?.selector; const text = args?.text; if (!selector || !text) { throw new Error('参数“selector”和“text”都是必须的。'); } await page.fill(selector, text); return { content: [ { type: 'text', text: `已在元素 ${selector} 中输入文本：“${text}”`, }, ], }; } case 'get_text': { if (!page) { throw new Error('请先使用 start_browser 工具启动浏览器。'); } const selector = args?.selector; if (!selector) { throw new Error('参数“selector”是必须的。'); } const elementText = await page.textContent(selector); return { content: [ { type: 'text', text: `元素 ${selector} 的文本内容是：“${elementText}”`, }, ], }; } case 'screenshot': { if (!page) { throw new Error('请先使用 start_browser 工具启动浏览器。'); } const path = args?.path || `screenshot-${Date.now()}.png`; await page.screenshot({ path }); return { content: [ { type: 'text', text: `页面截图已保存至：${path}`, }, ], }; } case 'close_browser': { if (browser) { await browser.close(); browser = null; page = null; return { content: [ { type: 'text', text: '浏览器已关闭。', }, ], }; } return { content: [ { type: 'text', text: '浏览器未运行。', }, ], }; } default: throw new Error(`未知工具：${name}`); } } catch (error) { // 将错误信息返回给客户端 return { content: [ { type: 'text', text: `工具调用失败：${error.message}`, }, ], isError: true, }; } });

别忘了在之前tools/list处理器的tools数组中，把这些新工具的描述也加进去：

// 在 tools/list 处理器的返回数组中，补充完整： tools: [ { name: 'start_browser', description: '启动一个无头Chromium浏览器并创建一个新页面。', // ... inputSchema ... }, { name: 'navigate', description: '让当前页面导航到指定的URL。', inputSchema: { type: 'object', properties: { url: { type: 'string', description: '要导航到的完整URL地址。', }, }, required: ['url'], }, }, { name: 'click', description: '点击页面上的一个元素。', inputSchema: { type: 'object', properties: { selector: { type: 'string', description: '要点击元素的CSS选择器。', }, }, required: ['selector'], }, }, // ... 类似地添加 type_text, get_text, screenshot, close_browser 的定义 ]

现在，一个具备基本浏览器操作能力的Playwright MCP服务器就完成了。它可以通过MCP协议，响应来自客户端的指令，执行打开浏览器、访问网页、点击、输入、获取文本和截图等操作。

4. 配置客户端并运行测试

4.1 配置Claude Desktop连接MCP服务器

目前，Anthropic的Claude Desktop应用是对MCP支持最友好、也是最容易上手的客户端之一。我们需要配置Claude Desktop，让它知道我们的Playwright MCP服务器在哪里。

1. 找到Claude Desktop的配置目录：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件：如果文件不存在，就创建它。在其中添加mcpServers配置项，指向我们刚刚写的server.js。注意，你需要使用node命令来运行它，并给出绝对路径。

{ "mcpServers": { "playwright": { "command": "node", "args": ["/你的/绝对/路径/playwright-mcp-server/server.js"] } } }

3. 重启Claude Desktop：保存配置文件后，完全退出并重新启动Claude Desktop应用。

4.2 进行第一次自然语言自动化测试

重启后，在Claude Desktop的新对话窗口中，你应该能直接使用我们定义的工具了。尝试进行如下对话：

你：“请启动浏览器，访问百度首页，在搜索框里输入‘Playwright’，然后点击‘百度一下’按钮，最后截一张图保存。”

Claude（思考后）：它会识别出需要调用一系列工具。它的回复可能类似于： “我将帮你完成这个任务。首先，启动浏览器...（调用start_browser工具） 浏览器已启动。现在导航到百度...（调用navigate工具，参数url: 'https://www.baidu.com'） 已导航到百度。接下来，在搜索框输入‘Playwright’...（调用type_text工具，参数selector: '#kw', text: 'Playwright'） 输入完成。现在点击‘百度一下’按钮...（调用click工具，参数selector: '#su'） 点击完成。最后，截取当前页面...（调用screenshot工具，参数path: 'baidu-search.png'） 所有操作已完成。截图已保存为‘baidu-search.png’。”

在这个过程中，Claude作为MCP客户端，负责理解你的自然语言指令，将其分解为一系列有序的MCP工具调用请求。我们的Playwright MCP服务器在后台接收这些请求，执行真实的浏览器操作，并将每一步的结果返回。你无需编写一行脚本代码，就完成了一次完整的UI自动化操作。

注意事项：选择器的准确性是UI自动化的关键。Claude可能无法精确知道百度搜索框的CSS选择器是#kw。在实际协作中，有几种解决思路：1）你可以在指令中明确告诉它选择器（“用选择器#kw定位搜索框”）；2）你可以先实现一个get_page_html或inspect_element工具，让AI先获取页面结构；3）更高级的做法是结合计算机视觉（CV）或AI元素定位，但这超出了基础MCP服务器的范畴。初期，明确的选择器指令是最高效的方式。

5. 进阶功能与工程化实践

5.1 增强工具：断言、等待与复杂交互

基础的点击输入远远不够。一个健壮的测试框架需要断言和更智能的等待。我们可以扩展我们的工具集：

• 断言工具：assert_text_contains，用于验证页面某处是否包含特定文本。
• 智能等待工具：wait_for_selector，等待某个元素出现，这对于动态加载的页面至关重要。
• 文件上传工具：upload_file，处理<input type="file">元素。
• 下拉框选择工具：select_option。
• 鼠标悬停工具：hover。
• 获取页面信息工具：get_page_title,get_page_url。

以assert_text_contains为例，看看如何实现：

// 在 tools/call 的 switch-case 中添加新的 case case 'assert_text_contains': { if (!page) throw new Error('请先启动浏览器。'); const selector = args?.selector; const expectedText = args?.expectedText; if (!selector || !expectedText) { throw new Error('参数“selector”和“expectedText”都是必须的。'); } const actualText = await page.textContent(selector); if (actualText && actualText.includes(expectedText)) { return { content: [{ type: 'text', text: `断言成功：元素 ${selector} 包含文本“${expectedText}”。` }], }; } else { // 注意：这里我们返回错误，MCP协议中 isError: true 表示工具执行失败 return { content: [{ type: 'text', text: `断言失败：元素 ${selector} 的文本“${actualText}”不包含“${expectedText}”。` }], isError: true, }; } }

在tools/list中也要相应添加这个工具的描述。这样，AI就可以在测试流程中插入验证点了。

5.2 状态管理与多页面/上下文支持

我们之前的简单实现只维护了一个全局的browser和page。这在单任务流中没问题，但如果想同时进行多个独立测试，或者需要操作多个标签页，就需要引入状态管理。

一个常见的做法是，为每个“会话”或“任务”创建一个唯一的sessionId。MCP服务器维护一个映射表（Map），将sessionId与对应的PlaywrightBrowserContext和Page关联起来。客户端在调用工具时，需要传入sessionId参数来指定操作哪个浏览器实例。

这涉及到更复杂的MCP服务器设计，可能还需要引入“资源”（Resources）的概念。例如，将“打开的浏览器页面”作为一种资源暴露给客户端，客户端可以列出当前所有活跃的页面资源，然后选择其中一个进行操作。这是MCP协议更高级的用法，能让工具系统更加清晰和强大。

5.3 集成到CI/CD流水线

虽然通过Claude Desktop交互很酷，但自动化测试最终要融入研发流程。我们可以将“Playwright MCP服务器 + AI客户端”的组合脚本化。

思路是：编写一个Node.js脚本，这个脚本既启动MCP服务器，又模拟一个“AI客户端”（可以使用OpenAI/Anthropic的API，或者本地运行的LLM），向服务器发送一系列预定义或动态生成的工具调用指令，来执行完整的测试用例。这个脚本可以被Jenkins、GitHub Actions、GitLab CI等CI/CD工具调用。

// ci-test-runner.js 示例 import { spawn } from 'child_process'; import { OpenAI } from 'openai'; // 假设使用OpenAI API async function runTest() { // 1. 启动Playwright MCP服务器子进程 const serverProcess = spawn('node', ['server.js'], { stdio: ['pipe', 'pipe', 'inherit'] }); // 2. 这里需要实现一个简单的MCP客户端，通过stdio与服务器进程通信 // 3. 使用LLM API（如OpenAI）生成测试步骤，或直接发送硬编码的工具调用序列 // 4. 解析服务器的响应，判断测试是否通过 // 5. 测试结束，关闭服务器进程 serverProcess.kill(); }

这要求你实现一个简易的、能处理MCP协议帧（JSON-RPC over stdio）的客户端。虽然有一定工作量，但它实现了将自然语言描述的测试用例自动转化为可执行脚本并集成到CI中的愿景。

5.4 错误处理与调试增强

在tools/call的catch块中，我们返回了错误信息。但为了更好的调试体验，我们可以增强错误处理：

• 自动截图：在任何工具调用失败时，自动调用screenshot工具，并将图片路径或base64编码的图片数据附加到错误信息中，返回给客户端。这对于定位元素找不到、页面状态异常等问题至关重要。
• 详细日志：服务器端应该记录详细的日志，包括收到的请求、执行的Playwright操作、页面URL变化等。可以将日志写入文件，方便离线分析。
• 超时控制：为每个工具调用设置合理的超时时间，特别是wait_for_selector、navigate这类操作，避免因网络或页面问题导致进程挂起。

6. 常见问题、排查技巧与未来展望

6.1 常见问题速查表

6.2 调试技巧与心得

• 独立运行服务器：在开发阶段，不要总依赖Claude Desktop来测试。可以写一个简单的测试脚本，模拟MCP客户端向你的服务器进程（通过stdio）发送JSON-RPC请求，这样能更快地定位是协议问题还是Playwright操作问题。
• 启用Playwright Debug日志：在启动浏览器时，设置环境变量DEBUG=pw:api，可以看到Playwright内部详细的API调用日志，对理解执行流程非常有帮助。
• 善用“非无头”模式：在调试元素定位或复杂交互问题时，将headless设为false，亲眼看着浏览器执行操作，是最直观的调试方式。
• 从简单到复杂：先确保start_browser和navigate这两个最基本的工具能稳定工作，再逐步添加点击、输入等操作。每添加一个工具，都进行验证。

6.3 未来可能的演进方向

Playwright MCP的玩法远不止于此，它开启了许多有趣的可能性：

1. 与低代码/无代码测试平台结合：平台后台可以运行MCP服务器，前端通过拖拽生成测试步骤图，实际上就是生成一系列工具调用指令发送给服务器执行。
2. 智能测试用例生成与修复：AI不仅可以执行测试，还可以分析产品需求文档或用户故事，自动生成初步的测试用例（即工具调用序列）。当UI发生变化导致选择器失效时，AI可以分析错误截图或DOM变化，尝试推荐新的选择器或自动修复测试脚本。
3. 跨应用流程自动化：MCP协议不限于Playwright。可以同时运行多个MCP服务器，一个管浏览器（Playwright），一个管桌面应用（也许通过AutoIt或PyAutoGUI封装），另一个管数据库查询。AI客户端就能协调这些服务器，完成涉及多个系统的端到端业务流程自动化。
4. 测试结果的自然语言分析与报告：将测试执行过程中所有的步骤、截图、断言结果通过MCP反馈给AI，让其生成一份人类可读的、带问题分析和建议的测试报告。

我个人在实际搭建和实验这个过程后，最大的体会是：MCP像是一把钥匙，它把AI的“思考”能力与各种具体的“执行”能力（如Playwright）标准地连接了起来。它降低了AI应用开发的门槛，让我们可以更专注于“要做什么”（定义工具），而不是“怎么让AI去做”（适配各种模型接口）。对于UI自动化测试领域，它未必会立刻取代所有传统的脚本编写，但它无疑提供了一种更灵活、更智能、更具探索性的新范式。尤其是对于快速验证想法、编写一次性测试脚本、或者构建智能测试助手这类场景，它的优势非常明显。你可以先从一个小工具集开始，比如封装你们公司登录模块的几个操作，让团队成员都能通过对话来验证登录功能是否正常，感受一下这种“对话式自动化”带来的效率提升。