做 Web 自动化测试很多团队在 Selenium、Cypress、Playwright 之间反复对比做 AI Agent 相关开发时又面临“让大模型操作浏览器”的新需求。Playwright 作为这几年社区中主流的端到端测试工具不仅把录制脚本、定位元素、断言、无头浏览器这些基础能力做得比较完善还通过 MCP 协议、CLI 生态和 Agent Browser 方向衍生出一套面向 AI 的自动化链路。本文会围绕 Playwright 展开从核心 API 和完整实战项目讲起再到 MCP Server 配置、CLI 命令以及 Agent Browser 的接入方式最后补充常见问题和工程最佳实践。无论你是刚开始学自动化测试的新手还是准备从 Selenium 迁移的团队都能从这篇文章里拿到一套可以直接落地的方案。1. 背景为什么 Web 自动化领域越来越多人选择 Playwright1.1 从 Selenium 到 PlaywrightWeb 自动化测试的演进早期做 Web 自动化绕不开 Selenium。Selenium 通过 WebDriver 协议与浏览器通信生态成熟、语言支持广很多团队的自动化框架都是基于它搭建的。但 Selenium 也存在一些痛点定位元素后需要自己处理等待逻辑多标签页、多页面切换比较繁琐iframe 和 Shadow DOM 的兼容处理也常常让人头疼。Cypress 的出现解决了一部分体验问题它内置自动重试、实时 reload测试写起来很直观。但 Cypress 的浏览器支持范围相对窄多标签页切换也有历史限制在复杂的业务系统里会遇到一些边界情况。Playwright 在 2020 年前后发布由微软团队维护。它采用了不同的架构思路通过浏览器自身的调试协议直接驱动浏览器而不是统一走 WebDriver。这个设计让 Playwright 拥有更强的页面控制能力也让自动等待、多页面管理、网络拦截、移动端模拟等能力变得非常自然。1.2 Playwright 的核心特性从实际使用体验来看Playwright 最值得关注的特性可以分成这几类多浏览器支持Chromium、Firefox、WebKit 都能跑一套 API 走天下还能做跨浏览器兼容测试。自动等待大多数操作会自动等待元素可交互不需要像 Selenium 那样写大量显式等待。浏览器上下文隔离每个 Context 相当于一个独立的会话Cookie、存储、权限相互隔离非常适合测试数据隔离。原生支持多页面、多 Tab、iframe、Shadow DOM定位和切换都直接在 API 层解决。强大的调试体系录制脚本的 codegen、回放调试的 Trace Viewer、失败自动截图和录屏出了问题能快速定位。网络拦截与 mock可以拦截请求、伪造接口响应、模拟弱网方便做异常场景测试。这些特性并不只是“方便”而是在真实项目中能直接降低维护成本。后面章节我会用代码演示其中最常用的部分。1.3 Playwright、Selenium、Cypress 该怎么选选型没有标准答案关键看团队技术栈和场景。下面这张对比表可以帮你快速判断对比项SeleniumCypressPlaywright驱动架构WebDriver 协议驱动浏览器在浏览器内注入执行通过浏览器调试协议直接驱动支持语言Java、Python、JS、C# 等JavaScript / TypeScriptJS / TS、Python、Java、.NET自动等待需要自己处理显式等待内置等待与重试内置自动等待可调整超时多标签页/多页面需要手动切换窗口句柄多标签支持较弱原生支持 Page 与 Context 管理iframe / Shadow DOM处理方式相对繁琐iframe 支持尚可提供 frameLocator 等专用 API录制与调试依赖第三方工具交互式调试体验好codegen 录制 Trace Viewer适合场景老项目、多语言团队前端开发者快速写 E2E跨浏览器、复杂业务、AI 自动化如果你的项目是遗留系统且已经重度使用 Selenium不一定要迁移如果是新项目或者想构建面向 AI 的自动化测试链路Playwright 的性价比会更高。2. 环境准备与安装2.1 运行环境说明Playwright 支持 Windows、macOS、Linux。运行环境需要满足以下条件之一Node.js 环境建议 Node.js 18 及以上。Python 环境建议 Python 3.8 及以上。本文主要用 Node.js TypeScript 演示Python 的安装方式会在小节末尾补充。示例中的版本信息以常见环境为准具体版本需要根据你的项目实际情况调整。2.2 Node.js 环境安装 Playwright创建一个新项目并初始化mkdir playwright-demo cd playwright-demo npm init -y安装 Playwright 测试库npm install -D playwright/test安装浏览器。浏览器会下载到本地缓存目录建议使用带--with-deps的参数它会自动补齐 Linux 系统依赖npx playwright install --with-deps chromium如果只想安装 Chromium上面命令已经满足需要 Firefox 和 WebKit 时可以这样npx playwright install --with-deps firefox webkit验证安装是否成功npx playwright --version如果能输出版本号说明核心库已经装好。在部分网络环境下浏览器下载可能比较慢Playwright 社区常用的做法是配置镜像加速export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ npx playwright install chromium2.3 Python 环境安装可选如果你更习惯 Python 生态可以这样安装pip install playwright playwright install chromiumPython 版同样支持--with-deps在 Linux 环境下需要时使用playwright install --with-deps chromium2.4 项目结构规划本文的实战案例会按照下面的目录组织playwright-demo/ ├── package.json ├── playwright.config.ts ├── .env └── tests/ ├── login.spec.ts └── profile.spec.tsplaywright.config.ts是 Playwright Test 的配置文件tests目录存放测试用例.env用于存测试环境地址和测试账号。3. Playwright 核心 API 与定位方法3.1 浏览器、上下文、页面三层结构理解 Playwright 的 API 层级是写脚本的前提Browser浏览器实例可以启动 Chromium、Firefox、WebKit。BrowserContext相当于一个独立的匿名会话Cookie、缓存、权限都是隔离的。Page一个页面标签页实际执行自动化操作的对象。画成示意图就是Browser ├── BrowserContext A │ ├── Page A1 │ └── Page A2 └── BrowserContext B └── Page B1在测试中每个测试用例默认会拿到一个全新的 Context这能保证测试之间互不污染。3.2 定位元素方法大全定位元素是自动化测试的日常操作Playwright 提供了非常丰富的定位器 API。基础定位// 按文本定位适合按钮、链接、标题 await page.getByText(登录).click(); // 按占位符定位适合输入框 await page.getByPlaceholder(请输入用户名).fill(tester); // 按标签名和名称定位适合按钮、链接等可访问元素 await page.getByRole(button, { name: 登录 }).click(); // 按 testid 定位 await page.getByTestId(submit-btn).click();CSS 与 XPath// CSS 选择器 await page.locator(.login-form input[nameusername]).fill(tester); await page.locator(#main-content .card button).click(); // XPath await page.locator(//button[contains(text(), 确定)]).click();文本模糊与正则// 包含“注册”两个字的元素注意这种方式推荐用 getByText 更规范 await page.getByText(/注册|创建账号/).click(); // 与 CSS 组合精确控制范围 await page.locator(button).filter({ hasText: 确认 }).click(); // 配合 nth 取第几个匹配元素 await page.locator(.list-item).nth(1).click();iframe 内元素const frame page.frameLocator(#iframe-id); await frame.getByPlaceholder(请输入验证码).fill(1234); await frame.getByRole(button, { name: 提交 }).click();多页面管理const [newPage] await Promise.all([ context.waitForEvent(page), page.getByText(在新窗口打开).click(), ]); await newPage.waitForLoadState(domcontentloaded); console.log(newPage.url());关于getByText和locator的使用建议能使用语义化定位器Role、Label、Placeholder时优先使用复杂的业务组件再考虑 CSS 与文本组合。这样写出来的脚本更接近用户视角出问题时也容易排查。3.3 自动等待机制Playwright 的操作会自动等待元素出现在 DOM 中并且可交互比如click会等待元素可见、稳定、接收事件。这个机制来自“Actionability”检查但并不意味着完全不需要配置超时。在playwright.config.ts中可以通过use.timeout控制全局超时use: { timeout: 30_000, }单条断言也可以单独设置超时await expect(page.getByText(操作成功)).toBeVisible({ timeout: 10_000 });注意自动等待不等于无限等待只是把“轮询”内置化了。如果你在真实项目中遇到元素定位不到重点还是先检查选择器是否正确而不是盲目增大超时。3.4 用 codegen 快速录制脚本写定位器比较头疼的情况下可以用 Playwright 自带的 codegen 录制器npx playwright codegen https://example.com/login执行后会自动打开一个浏览器窗口和一个脚本面板。你在浏览器上手动点击、输入Playwright 会同步生成代码可以直接复制到测试文件里。这个功能对新手特别友好也是我在接手新项目时快速摸清页面结构的首选方式。4. 完整实战登录流程自动化与报告生成4.1 需求背景以一个常见的后台管理系统为例需求如下用户输入手机号和密码点击登录。登录成功后跳转个人中心显示用户名。密码错误时提示错误信息。失败时自动截图方便定位问题。4.2 创建项目结构在playwright-demo中创建配置文件touch playwright.config.ts文件路径playwright-demo/playwright.config.tsimport { defineConfig, devices } from playwright/test; export default defineConfig({ testDir: ./tests, timeout: 30_000, retries: 1, reporter: [ [list], [html, { open: never }], ], use: { baseURL: process.env.BASE_URL || https://example.com, headless: true, screenshot: only-on-failure, video: retain-on-failure, trace: retain-on-failure, }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] }, }, ], });配置说明baseURL所有page.goto(/login)会自动拼接域名方便切换环境。screenshot: only-on-failure失败时自动截图。video和trace保留失败用例的录屏和调试追踪排查问题非常有用。reporter使用list输出命令行日志使用html生成测试报告。4.3 编写登录测试用例文件路径playwright-demo/tests/login.spec.tsimport { test, expect } from playwright/test; test.describe(登录流程, () { test(输入正确账号密码后进入个人中心, async ({ page }) { await page.goto(/login); await page.getByPlaceholder(请输入手机号).fill(13800000000); await page.getByPlaceholder(请输入密码).fill(test123456); await page.getByRole(button, { name: 登录 }).click(); await expect(page).toHaveURL(/\/profile/); await expect(page.getByTestId(username)).toHaveText(tester); await page.screenshot({ path: reports/login-success.png, fullPage: true }); }); test(密码错误时提示错误信息, async ({ page }) { await page.goto(/login); await page.getByPlaceholder(请输入手机号).fill(13800000000); await page.getByPlaceholder(请输入密码).fill(wrong-password); await page.getByRole(button, { name: 登录 }).click(); await expect(page.getByText(手机号或密码错误)).toBeVisible(); }); });补充说明测试用例中的手机号和密码正式项目中应该通过环境变量或配置文件注入不要写死在代码里。page.goto(/login)之所以不需要写完整域名是因为baseURL已经配置。第二个用例断言错误提示可见这是比较典型的交互验证方式。4.4 运行与查看报告执行全部用例npx playwright test执行时如果希望浏览器非无头模式方便观察npx playwright test --headed只运行某个文件npx playwright test tests/login.spec.ts运行完成后控制台会输出每个用例的通过情况。HTML 报告需要单独打开npx playwright show-report在报告页面里你可以看到每个用例的执行时间、失败截图、视频回放和 Trace 面板。对于失败用例Trace 面板会展示每一步操作前后的 DOM 快照排查问题比看日志直观得多。4.5 结果说明正常情况下第一个用例会登录成功并跳转到/profile同时生成reports/login-success.png第二个用例会验证错误提示是否出现。如果页面结构或选择器与你的项目不一致可以先运行 codegen 重新生成定位器再替换到测试用例中。5. MCP 与 AI 浏览器自动化5.1 什么是 MCPMCP 全称 Model Context Protocol是大模型应用与外部工具之间的标准化协议。它的作用是让大模型可以“调用工具”而不是只能生成文本回复。在没有 MCP 之前每个 AI 应用都需要自己对接不同的数据源和工具接口各不相同。引入 MCP 之后工具提供方把能力封装成标准化的 Server大模型客户端通过同一套协议读取工具列表并调用工具相当于给 AI 打了一个通用的“工具接口”。在浏览器自动化场景中MCP 的意义在于AI 不再只是帮你写脚本而是可以像一个真实用户一样操作浏览器执行点击、输入、截图、读取控制台日志等操作。5.2 安装 Playwright MCP ServerPlaywright 官方提供了 MCP 服务包安装和使用方式如下npx playwright/mcplatest常用参数示例npx playwright/mcplatest --headless --browser chromium启动后MCP Server 会暴露一组浏览器操作工具名称通常类似browser_navigate、browser_click、browser_snapshot、browser_fill等。不同版本的工具命名可能有细微差异实际使用时可以先查看 MCP 客户端提供的工具列表。如果希望在支持 MCP 的桌面客户端中使用以 Claude Desktop 为例可以在配置文件中添加{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] } } }其他支持 MCP 的客户端如 Cursor、Trae、各种 CLI 工具配置方式大同小异核心都是指定命令和参数。5.3 通过 MCP 让 AI 操作页面配置好 MCP Server 后你可以直接在 AI 对话中输入自然语言指令例如“打开 https://example.com/login”“在手机号输入框填入 13800000000”“点击登录按钮”“截图保存到当前目录”AI 会通过 MCP 工具逐个执行这些步骤并返回结果。这种方式适合快速验证页面功能和排查问题也可以用于让 AI 帮你执行一轮冒烟测试。需要注意MCP 模式下 AI 的每一步操作都需要时间复杂业务场景下建议拆分成小任务。对 AI 操作范围不熟悉的团队先在小范围页面上验证再推广到核心流程。5.4 自定义一个简单的 MCP Server如果你的项目希望把内部系统能力封装给 AI 使用可以自己写一个 MCP Server。下面用 Python 的fastmcp库演示思路pip install fastmcp playwright文件路径mcp_server.pyfrom fastmcp import FastMCP from playwright.sync_api import sync_playwright mcp FastMCP(web-demo) mcp.tool() def open_page(url: str) - str: 打开指定 URL并返回页面标题 with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.goto(url, timeout15000) title page.title() browser.close() return title mcp.tool() def get_page_text(url: str, selector: str) - str: 打开页面并提取指定选择器内的文本内容 with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.goto(url, timeout15000) content page.locator(selector).first.text_content() or browser.close() return content if __name__ __main__: mcp.run()这段代码属于演示思路正式项目中需要复用浏览器实例避免每次调用都启动和关闭浏览器。定义好之后你可以在支持 MCP 的客户端中加载这个 Python 服务AI 就能调用open_page和get_page_text两个工具。5.5 MCP 的适用边界MCP 让 AI 操作浏览器变得简单但不要把它当成“万能自动化工具”。适合 MCP 的场景包括AI 辅助测试让 AI 按自然语言描述执行页面操作。快速验证 UI 问题AI 打开页面、截图、读取控制台错误。内部工具集成把内部系统功能封装成 MCP 工具。不适合的场景对实时性要求极高的高频操作。需要复杂断言和精细流程控制的回归测试此时还是 Playwright Test 更稳。涉及未授权系统访问、验证码绕过等行为应当直接禁止。6. CLI 与 Agent Browser 实战6.1 Playwright CLI 常用命令除了跑测试Playwright 本身提供了很多实用命令行工具# 打开浏览器并录制操作脚本 npx playwright codegen https://example.com # 对页面截图 npx playwright screenshot --viewport-size1280,720 https://example.com home.png # 将页面导出为 PDF只支持 Chromium npx playwright pdf https://example.com page.pdf # 打开已保存的 Trace 文件 npx playwright show-trace trace.zip # 打开 HTML 测试报告 npx playwright show-report # 查看已安装的浏览器 npx playwright install --list截图和 PDF 适合做快速验证codegen 适合生成用例雏形trace 和 report 则是在排障时最常用的两个命令。6.2 外部 AI CLI 与浏览器自动化的组合目前在终端领域出现了不少 AI CLI 工具比如 Codex CLI、Claude Code CLI 等。它们本身负责“理解任务、规划步骤、生成代码”但终端工具很难直接控制图形浏览器。解决办法是利用前面提到的 MCP 协议在 AI CLI 中配置 Playwright MCP Server让 AI 既能在终端里写代码又能操作浏览器做验证。有用户在使用这类 CLI 时遇到过类似报错unable to locate the codex cli binary. set codex cli path or ensure the executable is available in your PATH.这类问题的根因基本是环境变量 PATH 未包含 CLI 可执行文件路径。排查思路如下确认 CLI 是否安装成功。检查安装目录是否已加入 PATH。重启终端让环境变量生效。如果 CLI 是从 npm 全局安装的确认 npm 全局 bin 目录在 PATH 中。这些 AI CLI 工具更新很快不同项目的接入方式存在差异。以官方文档为准即可重点是理解“AI 负责任务规划Playwright MCP 负责浏览器执行”这个协作模式。6.3 Agent Browser 是什么Agent Browser 指的是能够自主在浏览器中操作页面来完成任务的应用通常由两部分组成大模型负责理解用户意图、拆解步骤、决定下一步操作。浏览器控制层负责执行点击、输入、导航、读取页面状态这部分通常由 Playwright、CDP 或类似底层能力实现。Agent Browser 与我们熟悉的自动化测试脚本相比区别在于“自主性”脚本是固定流程Agent 可以根据页面状态动态调整下一步动作。它很适合做开放式的调研类任务比如“帮我在官网找到客服邮箱”“浏览这个数据看板并把核心指标总结出来”。不过要理性看待 Agent Browser 的能力边界。遇到验证码、文件上传、复杂的拖拽交互、需要人工审核的流程时Agent 仍然会有较高失败率。实际落地时比较好的策略是“人工拆解 Agent 执行”把复杂任务切成多个明确的小步骤。6.4 Agent Browser 落地的合规提醒自动化操作浏览器无论出于测试还是 AI Agent 目的都要注意边界只操作你拥有权限的系统或测试环境。被测系统如果存在风控或反爬策略应在测试环境关闭相关限制或在白名单中配置测试账号而不是在线上通过自动化手段绕过风控。不要利用 Playwright 或 Agent 批量抓取未授权数据也不要编写绕过验证码、登录限制的脚本。涉及生产系统的任何自动化操作都需要审批、备份、可回滚。这些原则与测试行业的基础准则一致自动化的价值在于提高效率而不是突破边界。7. 常见问题与排查思路7.1 典型报错与解决方案下面整理了我日常使用 Playwright 过程中遇到的高频问题问题现象常见原因解决思路浏览器启动失败提示target closed页面被关闭或 Context 被浏览器回收组件打断检查代码里是否有browser.close()或异常跳转多页面场景用context.waitForEvent(page)元素定位超时报TimeoutError选择器不正确、元素在 iframe 或新窗口中、页面未加载完成先跑 codegen 验证选择器iframe 用frameLocator新开页面用Promise.all方式等待Linux 安装后启动失败缺少libnss3等依赖系统缺少图形库依赖使用npx playwright install --with-deps安装依赖浏览器下载慢或失败网络环境问题配置PLAYWRIGHT_DOWNLOAD_HOST镜像加速测试用例之间数据污染未使用独立 Context或登录态被共享每个测试使用独立测试账号用test.beforeEach创建数据定位到的元素不在可视区域元素被折叠、覆盖或滚动未到位使用scrollIntoViewIfNeeded()或用locator.click()自动滚动无法定位span内文本文本被拆分到多个子节点使用getByText(关键词, { exact: false })或直接定位父级并发跑用例不稳定用例共享数据库或外部服务状态隔离测试数据使用 Playwright Shard 分片并发断言偶尔失败重跑就通过页面存在异步渲染等待时机不够使用expect自动重试避免固定sleep项目同时用 Selenium 和 Playwright浏览器驱动版本冲突尽量隔离运行环境统一使用 Playwright 管理的浏览器路径7.2 定位问题的高效排查流程如果遇到“脚本找不到元素”的问题不要一直加超时而是按下面的顺序排查打开被测页面用浏览器 DevTools 检查元素是否真的存在。运行npx playwright codegen url在录制器里手动操作一次观察生成的选择器。在测试脚本中先用page.locator(...).waitFor()确认元素是否出现。检查元素是否在 iframe、Shadow DOM、或者新打开的 Tab 中。确认页面是否有异步渲染、骨架屏、动态类名等影响因素。大部分定位问题都能在步骤 2 和步骤 3 之间解决。7.3 避免固定等待很多从 Selenium 转过来的同学习惯写sleep(3000)来等页面加载。在 Playwright 中应尽量避免这种做法。它的代价是设置太短容易失败设置太长会拖慢整个测试套件。更好的方式是// 等待特定元素出现 await page.getByTestId(loading).waitFor();// 等待某个请求完成 await page.waitForResponse((resp) resp.url().includes(/api/login) resp.status() 200);固定等待不是完全不能用但应该只用在极少数确实无法预测的动画场景而且时间要尽量短。8. 最佳实践与工程建议8.1 CI / CD 集成Playwright 非常适合接入 CI。以 GitHub Actions 为例常见配置思路是name: Playwright Tests on: push: branches: [ main ] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install - run: npx playwright install --with-deps chromium - run: npx playwright test - uses: actions/upload-artifactv4 if: always() with: name: playwright-report path: playwright-report/要点浏览器安装可以开启缓存避免每次 CI 都重新下载。测试报告上传为 artifact方便失败后回看。对大型项目可以用--shard分片并行缩短整体执行时间。8.2 环境与数据管理测试环境信息、账号密码不要硬编码在测试代码里。推荐用.env文件加环境变量管理BASE_URLhttps://staging.example.com ADMIN_USERadmin ADMIN_PASStest-passwordNode.js 中可以用process.env读取配合 dotenv 库加载。更重要的是测试数据要做到“每个用例独立”不要在用例之间共享状态。8.3 稳定性与超时策略自动化测试最怕不稳定。提高稳定性的几个关键手段依赖自动等待少用固定sleep。对异步操作使用expect的自动重试。合理配置timeout区分慢接口和真实卡死。失败用例保留视频和 Trace方便回放定位问题。不要在测试中依赖外部网络服务的稳定性必要时用路由拦截 mock 数据。8.4 权限与安全边界自动化脚本拥有浏览器操作能力因此同样需要权限管理测试脚本仓库避免提交真实密码和 Token。涉及敏感业务时最小化账号权限不要使用管理员账号跑全量用例。只对测试环境执行高风险的自动化操作。使用 MCP 或 Agent 时不要让 AI 无限制访问内网资源。合规这块没有商量余地自动化是为了提升效率不能用来绕过系统保护措施。8.5 可维护性设计当测试用例数量增长到一定程度建议把通用操作抽成 Page Object 模式// page-objects/LoginPage.ts import { Page } from playwright/test; export class LoginPage { constructor(private page: Page) {} async goto() { await this.page.goto(/login); } async login(username: string, password: string) { await this.page.getByPlaceholder(请输入手机号).fill(username); await this.page.getByPlaceholder(请输入密码).fill(password); await this.page.getByRole(button, { name: 登录 }).click(); } }使用时import { test } from playwright/test; import { LoginPage } from ../page-objects/LoginPage; test(登录后进入个人中心, async ({ page }) { const loginPage new LoginPage(page); await loginPage.goto(); await loginPage.login(13800000000, test123456); });Page Object 的好处是页面变更时只需要改一个文件而不是每个用例都改一遍。9. 总结与下一步学习建议本篇文章从 Playwright 的选型背景开始讲解了核心 API、定位方法、完整登录项目的搭建又延伸到 MCP Server、AI CLI 与 Agent Browser 的协作方式最后补充了常见问题与工程实践。到这里你已经能完成这些事独立安装 Playwright 环境并运行第一个测试。使用 codegen 快速生成脚本掌握常用定位器。搭建包含配置、报告、截图、Trace 的项目。接入 Playwright MCP Server让 AI 通过自然语言操作浏览器。分清楚 CLI、Agent Browser 在不同场景下的使用边界。下一步建议你从自己负责的前端项目开始先跑通一个登录流程再加一个核心业务链路比如“搜索商品 → 加入购物车 → 提交订单”。跑通之后再试试把 MCP 接入你的 AI 编程工具观察 AI 是如何理解页面状态并完成操作的。Web 自动化工具只是手段真正有价值的是你对业务的理解和对边界的判断。打开终端把npx playwright codegen用起来比看十遍教程更有用。