如果你所在团队的 Web 自动化测试还停留在 Selenium 时代下面这些场景应该不陌生脚本昨天还全绿今天一跑就挂定位元素要写各种等待时间最后干脆sleep(3)横行CI 里跑 50 条用例经常因为一条不稳定用例拖垮整个流水线。这些问题的根源往往不是用例写得不够多而是测试框架把最关键的稳定性责任交给了开发者。Playwright 出现之后这个局面被重新定义了一次。它不只是一个替代 Selenium 的自动化测试库而是把“等元素出现、可点击、可操作”这件事从开发者手动处理变成了框架内置能力。更关键的是这几年 AI 编程工具集中爆发Playwright 通过 MCP 协议和 Agent Skills 可以直接让 AI 智能体接管浏览器做自动化验证。换句话说它既是当前 Web 自动化测试的“默认选项”也是 AI Agent 落地到测试领域的最短路径之一。这篇文章不讲玄学。我会从零开始带你用大约 1 小时跑通一个完整的 Playwright 自动化测试项目包括环境安装、配置文件、用例编写、报告生成再讲清楚怎么结合 AI skills 提高测试编写效率。读完你可以直接照着搭一个能用在日常项目里的 Web 自动化测试工程。1. 为什么 Web 自动化测试绕不开 Playwright先给一个明确判断Playwright 真正降低的不是“写用例”的成本而是“维护用例”的成本。很多团队自动化测试做不下去不是因为没人写脚本而是脚本太容易挂一个月后没人愿意管。传统 Selenium 方案通过 WebDriver 协议和浏览器通信每一条定位、点击、取值命令都要走一遍 HTTP 往返。为了等元素出现你需要在代码里反复写WebDriverWait写少了脚本不稳定写多了用例越来越慢。Playwright 改变了这个模式它通过浏览器原生调试协议通信Chromium 走 CDPFirefox 和 WebKit 走各自的远程调试协议并且把自动等待内置到每一个操作里。你调用click()时框架会自动等待元素可见、稳定、可被点击直到超时。这一条改进直接消灭了开发中最多的一类不确定性。再对比一下测试运行器的体验。Selenium 本身不带测试框架你需要自己拼 JUnit、TestNG 或者 pytest断言失败时想看现场要么自己写截图逻辑要么装第三方库。Playwright 开箱自带测试运行器、断言库、HTML 报告、Trace 录制、失败截图、视频回放还有测试隔离的 BrowserContext。新手不需要理解这一整套生态是怎么拼起来的装完就能跑。下面是三款常用框架的快速对比方便你判断选型对比维度SeleniumCypressPlaywright通信方式WebDriver HTTP 协议与浏览器同进程注入浏览器原生调试协议等待机制需要手动显式等待自动重试查询自动等待可操作状态多标签页支持较弱需要切换句柄不支持原生支持 Page 对象iframe 处理需要切 frame较好frameLocator()原生支持网络请求拦截较弱支持支持 Mock、拦截、路由自带测试运行器无有有失败现场保留需自行开发自动截图视频Trace、截图、视频齐全AI/MCP 生态弱一般官方 MCP Server这张表不是要否定 Selenium。Selenium 胜在生态成熟、语言绑定多很多老项目仍然跑得很稳。但如果你正在启动一个新项目或者准备把自动化测试工程化Playwright 的默认体验明显更顺。这篇文章后面的实战全部基于 Playwright版本以当前最新稳定版为准不针对特定版本做过深绑定。2. Playwright 核心概念自动等待、定位器与测试运行器零基础读者第一次接触 Playwright最需要理解三个概念浏览器三件套、定位器、Web 优先断言。2.1 浏览器三件套Browser、BrowserContext、PagePlaywright 的对象模型分三层Browser是浏览器进程BrowserContext是独立的浏览器上下文相当于一个“隐身窗口”Page是其中的一个标签页。// 概念示例同一浏览器下创建两个完全隔离的上下文 const browser await chromium.launch(); const contextA await browser.newContext(); const contextB await browser.newContext(); const pageA await contextA.newPage(); const pageB await contextB.newPage();每个 Context 的 Cookie、LocalStorage、缓存是完全隔离的。这给测试带来的好处非常直接并行跑用例时不同用例之间不会互相污染登录状态。测试运行器默认就为每个测试创建一个新的 Context这是 Playwright 用例稳定的底层原因之一。2.2 定位器从操作元素到描述用户意图Selenium 时代大家习惯用findElement(By.xpath(...))写出来的是“页面里的某个 DOM 节点”。Playwright 的 Locator 更接近用户角度它描述的是“页面上那个叫‘登录’的按钮”而不是一段脆弱的 CSS 路径。// 推荐从用户可见语义定位 await page.getByRole(button, { name: 登录 }).click(); await page.getByPlaceholder(请输入用户名).fill(tester); await page.getByText(商品列表).click();推荐优先级是getByRole、getByLabel、getByPlaceholder、getByText这类语义定位器优先普通 CSS 次之XPath 最后。语义定位器表达的是“页面上有什么”CSS 和 XPath 表达的是“DOM 长什么样”。页面样式一改CSS 可能就碎了用户看到的文字不变语义定位依然有效。2.3 Web 优先断言Playwright 的断言库专门针对 Web 应用设计。await expect(locator).toBeVisible()不是做一次判断就结束而是会在超时时间内不断重试直到状态符合预期。这背后的机制和自动等待一脉相承断言、操作、等待是同一套时间轴不存在“断言太快导致误报”的问题。await expect(page.locator(.product-card)).toHaveCount(3); await expect(page.locator(#cartCount)).toHaveText(1); await expect(page).toHaveURL(/\/order\/success/);理解这套组合之后你会发现绝大多数稳定性问题都被框架挡掉了。剩下要处理的主要是业务逻辑、测试数据、环境差异这类问题。3. 环境准备与安装3.1 前置条件开始之前请确认电脑上安装了 Node.js。Playwright 官方要求 Node.js 18 或更高版本建议使用 20 LTS。打开终端执行node -v npm -v如果两个命令都能输出版本号环境就可用。如果你平时用 Python 更熟Playwright 也有 Python 版本安装方式是pip install playwright但本文示例统一使用 JavaScript/TypeScript 生态零基础读者建议先跟同一套语言跑通。3.2 初始化项目并安装依赖新建一个目录然后初始化 npm 项目mkdir playwright-demo cd playwright-demo npm init -y安装 Playwright 测试库npm install -D playwright/test这里有一点容易踩坑安装playwright/test只会安装运行库不会自动下载浏览器内核。你需要再执行一次浏览器安装命令npx playwright install chromium如果只需要在桌面浏览器调试也可以安装全部内核npx playwright install --with-deps--with-deps在 Linux 环境下特别有用它会一并安装系统级依赖库。Windows 和 macOS 一般不需要这个参数。如果下载浏览器时长时间卡住通常是网络原因。国内开发者可以配置镜像源后重试这种方式只是替换软件下载地址并不改变任何使用方式# 使用 npmmirror 的浏览器二进制镜像 set PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromiumWindows 用setmacOS/Linux 用export PLAYWRIGHT_DOWNLOAD_HOST...。3.3 验证安装是否成功执行以下命令能输出版本号说明安装成功npx playwright --version到这里环境准备就完成了。如果第 3 步失败大概率是浏览器内核没装好而不是测试库的问题。4. 第一个测试项目从零跑通一个用例为了不依赖外部网站也避免目标网站改版导致用例失效这一节我们用一个本地 HTML 页面做测试目标。你可以在项目里新建demo/shop.html这是一个内置了登录、搜索、加购逻辑的极简商城页面所有逻辑都写在 HTML 内部不依赖任何外部服务。!-- demo/shop.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 / titleDemo Shop/title style body { font-family: Arial, sans-serif; max-width: 900px; margin: 40px auto; } .product { border: 1px solid #eee; padding: 12px; margin: 8px 0; } .hidden { display: none; } .error { color: red; } .cart { position: fixed; top: 20px; right: 20px; background: #f5a623; padding: 8px 16px; border-radius: 4px; } /style /head body div idloginBox h1登录/h1 input idusername placeholder用户名 / input idpassword typepassword placeholder密码 / button idloginBtn登录/button p idloginError classerror hidden用户名或密码错误/p /div div idshopBox classhidden div classcart购物车数量span idcartCount0/span/div h1商品列表/h1 input idsearchInput placeholder搜索商品 / button idsearchBtn搜索/button div idproducts/div /div script const products [ { name: 机械键盘, category: 外设 }, { name: 无线鼠标, category: 外设 }, { name: 高清显示器, category: 显示 } ]; const productBox document.getElementById(products); function render(list) { productBox.innerHTML ; list.forEach(p { const div document.createElement(div); div.className product; div.dataset.name p.name; div.innerHTML span${p.name}/span button classadd-btn加入购物车/button; div.querySelector(.add-btn).addEventListener(click, () { const count document.getElementById(cartCount); count.textContent Number(count.textContent) 1; }); productBox.appendChild(div); }); } document.getElementById(loginBtn).addEventListener(click, () { const u document.getElementById(username).value; const p document.getElementById(password).value; if (u tester p 123456) { document.getElementById(loginBox).classList.add(hidden); document.getElementById(shopBox).classList.remove(hidden); render(products); } else { document.getElementById(loginError).classList.remove(hidden); } }); document.getElementById(searchBtn).addEventListener(click, () { const kw document.getElementById(searchInput).value.trim(); render(products.filter(p p.name.includes(kw))); }); /script /body /html接下来在项目根目录创建playwright.config.js统一管理测试目录、超时时间、浏览器类型和失败产物// playwright.config.js const { defineConfig } require(playwright/test); module.exports defineConfig({ testDir: ./tests, timeout: 30_000, retries: 0, reporter: [[list], [html]], use: { headless: true, viewport: { width: 1280, height: 720 }, screenshot: only-on-failure, video: retain-on-failure, trace: on-first-retry, }, projects: [ { name: chromium, use: { browserName: chromium } }, ], });配置项解释testDir测试文件所在目录。timeout每个测试的超时时间默认 30 秒超过即失败。reporter测试结果同时输出到命令行和 HTML 报告。screenshot: only-on-failure失败时自动截图便于排查。video: retain-on-failure失败时保留录像。trace: on-first-retry重试时记录 Trace之后可以在 Trace Viewer 里逐步回放。最后创建第一个测试文件tests/first.spec.js// tests/first.spec.js const { test, expect } require(playwright/test); const path require(path); const SHOP_URL file:// path.resolve(__dirname, ../demo/shop.html); test(页面标题和登录表单正常渲染, async ({ page }) { await page.goto(SHOP_URL); await expect(page).toHaveTitle(Demo Shop); await expect(page.getByPlaceholder(用户名)).toBeVisible(); await expect(page.getByPlaceholder(密码)).toBeVisible(); await expect(page.getByRole(button, { name: 登录 })).toBeEnabled(); });运行测试npx playwright test命令行会输出通过或失败的结果。这是你跑通的第一个 Playwright 用例。如果想看浏览器真实操作过程可以加--headed参数npx playwright test --headed如果想逐步调试可以进入调试模式npx playwright test --debug调试模式会打开浏览器和 Playwright Inspector支持单步执行、查看定位器匹配了哪些元素、手动重试操作。新手排查定位问题时这个工具比反复改代码有效率得多。5. 项目实战登录、搜索、加购、断言第一个用例验证的是页面渲染这一节我们写真正的业务链路登录、搜索、加购、断言结果。这个流程覆盖了 Web 自动化测试里最常见的几类操作表单填写、按钮点击、列表渲染、元素数量断言、文本内容断言。创建tests/shop.spec.js// tests/shop.spec.js const { test, expect } require(playwright/test); const path require(path); const SHOP_URL file:// path.resolve(__dirname, ../demo/shop.html); test.describe(商城核心流程, () { test(用户能完成登录、搜索、加购完整流程, async ({ page }) { await test.step(打开商城页面, async () { await page.goto(SHOP_URL); }); await test.step(使用正确账号登录, async () { await page.getByPlaceholder(用户名).fill(tester); await page.getByPlaceholder(密码).fill(123456); await page.getByRole(button, { name: 登录 }).click(); await expect(page.getByText(商品列表)).toBeVisible(); await expect(page.locator(.product)).toHaveCount(3); }); await test.step(搜索商品并验证结果, async () { await page.getByPlaceholder(搜索商品).fill(机械键盘); await page.getByRole(button, { name: 搜索 }).click(); await expect(page.locator(.product)).toHaveCount(1); }); await test.step(加入购物车并验证数量, async () { await page.locator(.product).filter({ hasText: 机械键盘 }) .getByRole(button, { name: 加入购物车 }) .click(); await expect(page.locator(#cartCount)).toHaveText(1); }); }); test(错误密码时提示登录失败, async ({ page }) { await page.goto(SHOP_URL); await page.getByPlaceholder(用户名).fill(tester); await page.getByPlaceholder(密码).fill(wrong-password); await page.getByRole(button, { name: 登录 }).click(); await expect(page.locator(#loginError)).toBeVisible(); await expect(page.locator(#loginError)).toHaveText(用户名或密码错误); }); });关键点解释test.describe把相关的用例组织到同一组报告里会按组展示。test.step给用例步骤命名失败时报告能直接显示挂在哪一步。page.getByPlaceholder(用户名)直接根据输入框占位符定位不需要关心id或class。filter({ hasText: 机械键盘 })先在商品列表里筛出包含“机械键盘”的商品卡片再在这个范围内点击“加入购物车”。这个写法避免了页面上多个“加入购物车”按钮造成歧义。登录失败用例特意断言了错误提示可见并且断言了提示文案防止页面出现多个“错误”字样时误判。运行方式不变npx playwright test tests/shop.spec.js这条命令只跑商城相关用例比全量跑更快适合开发阶段迭代。如果你想确认定位器写得对不对推荐使用 Playwright 的代码生成器直接在浏览器里操作页面它会自动生成对应的测试代码npx playwright codegen https://example.com这个命令会打开一个浏览器窗口和代码生成面板。你在页面上点击、填表、选择元素面板会同步生成 Playwright 代码。新手可以先用它生成骨架再手动修正断言和业务逻辑。注意codegen生成的代码是“做了什么”的记录不一定包含合理的断言最终用例质量仍然需要人工把关。6. 用 AI Skills 让自动化测试效率翻倍2025 年再聊自动化测试绕不开 AI 编程助手。现在主流 AI 编程工具如 Codex CLI、Claude Code、Cursor 等都能直接生成 Playwright 测试代码但生成质量参差不齐。问题通常不在语法而在测试规范AI 可能写出page.screenshot满天飞、滥用waitForTimeout、用脆弱的 CSS 选择器、断言缺少业务含义的代码。行业里正在用Agent Skills解决这个问题。Skills 的形态是一个目录里面放一个SKILL.md说明文件再加上若干参考示例。AI 编程工具加载这个 Skill 之后生成代码时会自动遵守其中的规则。你可以把团队沉淀的 Playwright 测试规范写成 Skill让 AI 从一开始就按规范生成而不是生成之后再人工纠正。下面是一个可直接参考的 Playwright 测试 Skill 示例。在项目根目录创建skills/playwright-testing/SKILL.md# Playwright 测试技能 ## 目标 编写稳定、易维护的 Web 自动化测试用例。 ## 使用规范 ### 定位器选择 - 优先使用 getByRole、getByLabel、getByPlaceholder、getByText 等语义定位器。 - 避免使用 XPath 和深层 CSS 选择器如 html body div div button。 - 同一操作可能命中多个元素时使用 filter、nth、first 缩小范围。 ### 等待策略 - 禁止使用 page.waitForTimeout 作为常规等待手段。 - 等待页面状态时使用 expect(locator).toBeVisible() 等 Web 优先断言。 - 网络请求完成需要等待时优先使用 page.waitForResponse。 ### 断言要求 - 每个用例至少包含一条业务断言不能只断言“页面打开成功”。 - 断言文案要有业务含义例如 toHaveText(订单支付成功)。 ### 用例独立性 - 用例之间不允许互相依赖不共享登录态。 - 需要登录的用例在 beforeEach 或用例内部完成登录。 ### 失败现场 - 不要在用例里手动截图。 - 依赖全局配置的 screenshot、video、trace 方案收集失败现场。然后你可以让 AI 编程工具根据这个 Skill 为demo/shop.html生成测试。以 Codex CLI 为例大致交互思路是请先阅读 skills/playwright-testing/SKILL.md 中的测试规范 然后参考 demo/shop.html 的页面结构在 tests 目录下生成一组覆盖 登录、搜索、加购、登录失败场景的 Playwright 测试用例。AI 生成后你仍然要做三件事人工审阅断言是否表达业务意图、跑一遍全量测试、把不稳定的用例用 Trace 排查后修正。AI 擅长的是快速生成骨架和覆盖正常路径稳定性和业务正确性判断仍然要由人来把控。除了 Skills另一个值得关注的是Playwright MCP Server。MCPModel Context Protocol是 AI 应用与大模型之间的标准协议。Playwright 官方提供了 MCP Server运行后 AI 助手可以直接控制浏览器完成打开页面、点击、填写、读取控制台日志、截图等操作。启动方式npx playwright/mcplatest启动后支持 MCP 的客户端可以连接这个服务让 AI Agent“亲自”操作浏览器做验证。典型场景包括AI 修改前端代码后自动打开页面验证视觉效果AI 阅读页面 DOM 结构后生成更准确的 SelectorAI 根据用户描述复现 Bug并把复现步骤整理成测试用例。不过要提醒一点MCP 让 AI 能操作真实浏览器也意味着 AI 操作范围变大了。接入前建议确认工作目录、运行环境、运行命令都是可信的并且只能在你有权访问的测试环境里操作不要在未授权页面或生产环境随意执行。7. 运行结果与效果验证跑通用例之后最关键的是会看结果。输入npx playwright test预期输出类似下面这样Running 3 tests using 1 worker ✓ 1 tests/first.spec.js:8:1 › 页面标题和登录表单正常渲染 (1.1s) ✓ 2 tests/shop.spec.js:7:1 › 商城核心流程 › 用户能完成登录、搜索、加购完整流程 (1.8s) ✓ 3 tests/shop.spec.js:34:1 › 商城核心流程 › 错误密码时提示登录失败 (0.9s) 3 passed (4.2s)这里的3 passed表示全部通过。如果某个用例失败会显示✘和失败原因并自动生成失败截图和视频。测试结束后项目目录下会生成test-results和playwright-report两个目录。查看 HTML 报告npx playwright show-report报告会列出每条用例的耗时、通过状态、失败时的堆栈、截图、视频和 Trace。定位线上问题时Trace 尤其有用它记录了页面上所有网络请求、控制台日志、页面快照和鼠标操作你可以像看视频一样逐步回放失败过程。验证通过的标准不只看3 passed还要确认几个细节报告中有没有隐式警告例如 Locator 命中多个元素的提示。失败用例的截图和视频是否真实反映了问题现场。重复跑 3 次用例是否每次都稳定通过。第一次跑用例出现失败优先去看 HTML 报告里的错误堆栈和页面快照大多数问题在快照里一眼就能看出是元素没找到、文案不对还是页面 JS 报错。8. 常见问题与排查思路这一节整理零基础读者最容易遇到的 6 个问题按“现象 → 原因 → 排查 → 解决”的方式给出处理路径。问题现象可能原因排查方式解决方案npx playwright install chromium下载失败或卡住网络原因导致浏览器二进制下载不稳定查看命令行是否长时间停在 Downloading配置 npmmirror 镜像后重新下载运行时报TimeoutError元素在超时时间内没有变成可操作状态打开 HTML 报告看页面快照确认元素是否真的出现检查选择器是否精确确认页面是否有 JS 报错必要时增大 timeout定位器报strict mode violation一个选择器命中了多个元素Playwright 拒绝自动猜测在 Inspector 里运行定位器查看命中数量用filter、first()、nth()缩小范围或改用更精确的getByRole页面弹出非预期弹窗导致后续操作失败页面触发了alert、confirm或自定义弹层阻塞了操作查看 Trace 中是否有dialog事件用page.on(dialog, d d.accept())处理或在用例中按弹窗文案分支iframe 里的元素定位不到元素在 iframe 内部普通 Locator 无法跨 frame打开元素面板确认 DOM 结构是否有 iframe使用page.frameLocator(iframe选择器)再继续接 locator脚本本地全绿CI 上偶发失败CI 机器资源不足或页面加载时序不同对比本地与 CI 的截图、Trace配置重试retries: 1限制并行workers: 2保留 Trace补充一个高频问题waitForTimeout到底能不能用。我的建议是不要在业务逻辑里依赖它偶尔用来“等一个明显很慢的动画效果”可以但一旦养成习惯用例会越来越慢而且等待时间写死之后页面快的时候浪费时间慢的时候照样崩。用自动等待断言代替固定 sleep是 Playwright 用例稳定性的第一原则。9. 最佳实践与工程建议到这里你已经能跑通用例也知道了常见的坑。最后给一套能直接用于项目的工程建议分五块。9.1 定位器规范团队里建议统一“语义定位器优先”的规范并在 Code Review 时重点关注 XPath 和深层 CSS。规则可以浓缩为有getByRole用getByRole。有表单控件用getByLabel或getByPlaceholder。文本内容用getByText但要确认它不是匹配整个页面的大段文字。CSS 选择器保留用于测试属性例如>// 环境变量读取示例 const username process.env.TEST_USER || tester; const password process.env.TEST_PASSWORD || 123456;9.3 失败现场收集全局配置screenshot: only-on-failure、video: retain-on-failure、trace: on-first-retry。这三件套能覆盖绝大多数排查场景不需要在用例里手动截图。CI 上传测试报告产物时把playwright-report和test-results目录一并保留方便失败后下载分析。9.4 接入 CI在新项目里建议把测试接入 GitHub Actions 或 GitLab CI。最小化的 GitHub Actions 配置可以参考# .github/workflows/playwright.yml name: Playwright Tests on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps chromium - run: npx playwright test - uses: actions/upload-artifactv4 if: failure() with: name: playwright-report path: playwright-report/ retention-days: 7注意 CI 里要运行npx playwright install --with-deps chromium因为 CI 机器默认没有浏览器内核而且可能缺系统依赖。9.5 AI 辅助测试的边界AI 生成测试代码时能力和边界要分清楚。适合交给 AI 的根据页面描述生成用例骨架、补全重复性测试步骤、根据现有页面结构生成定位器。需要人把关的断言是否表达真实业务规则、用例是否依赖了时序、测试数据是否合理、是否涉及不可逆操作。凡是涉及发送真实请求、修改生产数据、删除资源的行为测试脚本里都不应该出现测试环境操作也要先确认权限边界。生产环境自动化测试要格外谨慎。任何自动化脚本都可能因为选择器变化或误操作造成真实业务影响跑生产脚本前必须有审批、最小权限账号、执行窗口和回滚方案。个人项目可以随意跑团队项目务必先约定好环境边界。10. 总结与后续学习方向现在回头看这篇文章的核心其实是一条链路安装 Playwright → 理解浏览器三件套和 Locator → 跑通第一个用例 → 写业务链路用例 → 用 AI Skills 提高生成质量 → 用报告和 Trace 排查问题 → 把规范沉淀进工程。如果你能独立跑通第 5 节的商城用例并且能把常见的 6 个问题按表格里的思路排查一遍就已经具备把 Playwright 用在日常项目里的基础能力。下一步建议从三个方向深入项目改造挑一条你日常维护的业务链路用本地页面或测试环境写一组覆盖“正常流程 异常场景”的用例先跑稳定再扩大范围。工程化能力研究 fixtures、多项目配置、WebServer 启动、API 请求复用、数据清理这些是大型项目自动化测试规模化绕不开的能力。AI Agent 工作流把第 6 节的 Skills 和 MCP 方案接入你常用的 AI 编程工具形成“AI 生成 → 人审阅 → 自动回归”的闭环。最后一条实用提醒不要一开始就追求用例数量。先让 10 条核心用例连续 7 天稳定通过比一次性写出 100 条天天失败的用例有价值得多。自动化测试的价值不在于代码量只在于你是否愿意持续维护它。 
长河君 · 2026/8/31 11:28:26 · 阅读 1.2k Playwright Web自动化测试实战：从环境搭建到AI集成、MCP协议与稳定工程实践
如果你所在团队的 Web 自动化测试还停留在 Selenium 时代下面这些场景应该不陌生脚本昨天还全绿今天一跑就挂定位元素要写各种等待时间最后干脆sleep(3)横行CI 里跑 50 条用例经常因为一条不稳定用例拖垮整个流水线。这些问题的根源往往不是用例写得不够多而是测试框架把最关键的稳定性责任交给了开发者。Playwright 出现之后这个局面被重新定义了一次。它不只是一个替代 Selenium 的自动化测试库而是把“等元素出现、可点击、可操作”这件事从开发者手动处理变成了框架内置能力。更关键的是这几年 AI 编程工具集中爆发Playwright 通过 MCP 协议和 Agent Skills 可以直接让 AI 智能体接管浏览器做自动化验证。换句话说它既是当前 Web 自动化测试的“默认选项”也是 AI Agent 落地到测试领域的最短路径之一。这篇文章不讲玄学。我会从零开始带你用大约 1 小时跑通一个完整的 Playwright 自动化测试项目包括环境安装、配置文件、用例编写、报告生成再讲清楚怎么结合 AI skills 提高测试编写效率。读完你可以直接照着搭一个能用在日常项目里的 Web 自动化测试工程。1. 为什么 Web 自动化测试绕不开 Playwright先给一个明确判断Playwright 真正降低的不是“写用例”的成本而是“维护用例”的成本。很多团队自动化测试做不下去不是因为没人写脚本而是脚本太容易挂一个月后没人愿意管。传统 Selenium 方案通过 WebDriver 协议和浏览器通信每一条定位、点击、取值命令都要走一遍 HTTP 往返。为了等元素出现你需要在代码里反复写WebDriverWait写少了脚本不稳定写多了用例越来越慢。Playwright 改变了这个模式它通过浏览器原生调试协议通信Chromium 走 CDPFirefox 和 WebKit 走各自的远程调试协议并且把自动等待内置到每一个操作里。你调用click()时框架会自动等待元素可见、稳定、可被点击直到超时。这一条改进直接消灭了开发中最多的一类不确定性。再对比一下测试运行器的体验。Selenium 本身不带测试框架你需要自己拼 JUnit、TestNG 或者 pytest断言失败时想看现场要么自己写截图逻辑要么装第三方库。Playwright 开箱自带测试运行器、断言库、HTML 报告、Trace 录制、失败截图、视频回放还有测试隔离的 BrowserContext。新手不需要理解这一整套生态是怎么拼起来的装完就能跑。下面是三款常用框架的快速对比方便你判断选型对比维度SeleniumCypressPlaywright通信方式WebDriver HTTP 协议与浏览器同进程注入浏览器原生调试协议等待机制需要手动显式等待自动重试查询自动等待可操作状态多标签页支持较弱需要切换句柄不支持原生支持 Page 对象iframe 处理需要切 frame较好frameLocator()原生支持网络请求拦截较弱支持支持 Mock、拦截、路由自带测试运行器无有有失败现场保留需自行开发自动截图视频Trace、截图、视频齐全AI/MCP 生态弱一般官方 MCP Server这张表不是要否定 Selenium。Selenium 胜在生态成熟、语言绑定多很多老项目仍然跑得很稳。但如果你正在启动一个新项目或者准备把自动化测试工程化Playwright 的默认体验明显更顺。这篇文章后面的实战全部基于 Playwright版本以当前最新稳定版为准不针对特定版本做过深绑定。2. Playwright 核心概念自动等待、定位器与测试运行器零基础读者第一次接触 Playwright最需要理解三个概念浏览器三件套、定位器、Web 优先断言。2.1 浏览器三件套Browser、BrowserContext、PagePlaywright 的对象模型分三层Browser是浏览器进程BrowserContext是独立的浏览器上下文相当于一个“隐身窗口”Page是其中的一个标签页。// 概念示例同一浏览器下创建两个完全隔离的上下文 const browser await chromium.launch(); const contextA await browser.newContext(); const contextB await browser.newContext(); const pageA await contextA.newPage(); const pageB await contextB.newPage();每个 Context 的 Cookie、LocalStorage、缓存是完全隔离的。这给测试带来的好处非常直接并行跑用例时不同用例之间不会互相污染登录状态。测试运行器默认就为每个测试创建一个新的 Context这是 Playwright 用例稳定的底层原因之一。2.2 定位器从操作元素到描述用户意图Selenium 时代大家习惯用findElement(By.xpath(...))写出来的是“页面里的某个 DOM 节点”。Playwright 的 Locator 更接近用户角度它描述的是“页面上那个叫‘登录’的按钮”而不是一段脆弱的 CSS 路径。// 推荐从用户可见语义定位 await page.getByRole(button, { name: 登录 }).click(); await page.getByPlaceholder(请输入用户名).fill(tester); await page.getByText(商品列表).click();推荐优先级是getByRole、getByLabel、getByPlaceholder、getByText这类语义定位器优先普通 CSS 次之XPath 最后。语义定位器表达的是“页面上有什么”CSS 和 XPath 表达的是“DOM 长什么样”。页面样式一改CSS 可能就碎了用户看到的文字不变语义定位依然有效。2.3 Web 优先断言Playwright 的断言库专门针对 Web 应用设计。await expect(locator).toBeVisible()不是做一次判断就结束而是会在超时时间内不断重试直到状态符合预期。这背后的机制和自动等待一脉相承断言、操作、等待是同一套时间轴不存在“断言太快导致误报”的问题。await expect(page.locator(.product-card)).toHaveCount(3); await expect(page.locator(#cartCount)).toHaveText(1); await expect(page).toHaveURL(/\/order\/success/);理解这套组合之后你会发现绝大多数稳定性问题都被框架挡掉了。剩下要处理的主要是业务逻辑、测试数据、环境差异这类问题。3. 环境准备与安装3.1 前置条件开始之前请确认电脑上安装了 Node.js。Playwright 官方要求 Node.js 18 或更高版本建议使用 20 LTS。打开终端执行node -v npm -v如果两个命令都能输出版本号环境就可用。如果你平时用 Python 更熟Playwright 也有 Python 版本安装方式是pip install playwright但本文示例统一使用 JavaScript/TypeScript 生态零基础读者建议先跟同一套语言跑通。3.2 初始化项目并安装依赖新建一个目录然后初始化 npm 项目mkdir playwright-demo cd playwright-demo npm init -y安装 Playwright 测试库npm install -D playwright/test这里有一点容易踩坑安装playwright/test只会安装运行库不会自动下载浏览器内核。你需要再执行一次浏览器安装命令npx playwright install chromium如果只需要在桌面浏览器调试也可以安装全部内核npx playwright install --with-deps--with-deps在 Linux 环境下特别有用它会一并安装系统级依赖库。Windows 和 macOS 一般不需要这个参数。如果下载浏览器时长时间卡住通常是网络原因。国内开发者可以配置镜像源后重试这种方式只是替换软件下载地址并不改变任何使用方式# 使用 npmmirror 的浏览器二进制镜像 set PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromiumWindows 用setmacOS/Linux 用export PLAYWRIGHT_DOWNLOAD_HOST...。3.3 验证安装是否成功执行以下命令能输出版本号说明安装成功npx playwright --version到这里环境准备就完成了。如果第 3 步失败大概率是浏览器内核没装好而不是测试库的问题。4. 第一个测试项目从零跑通一个用例为了不依赖外部网站也避免目标网站改版导致用例失效这一节我们用一个本地 HTML 页面做测试目标。你可以在项目里新建demo/shop.html这是一个内置了登录、搜索、加购逻辑的极简商城页面所有逻辑都写在 HTML 内部不依赖任何外部服务。!-- demo/shop.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 / titleDemo Shop/title style body { font-family: Arial, sans-serif; max-width: 900px; margin: 40px auto; } .product { border: 1px solid #eee; padding: 12px; margin: 8px 0; } .hidden { display: none; } .error { color: red; } .cart { position: fixed; top: 20px; right: 20px; background: #f5a623; padding: 8px 16px; border-radius: 4px; } /style /head body div idloginBox h1登录/h1 input idusername placeholder用户名 / input idpassword typepassword placeholder密码 / button idloginBtn登录/button p idloginError classerror hidden用户名或密码错误/p /div div idshopBox classhidden div classcart购物车数量span idcartCount0/span/div h1商品列表/h1 input idsearchInput placeholder搜索商品 / button idsearchBtn搜索/button div idproducts/div /div script const products [ { name: 机械键盘, category: 外设 }, { name: 无线鼠标, category: 外设 }, { name: 高清显示器, category: 显示 } ]; const productBox document.getElementById(products); function render(list) { productBox.innerHTML ; list.forEach(p { const div document.createElement(div); div.className product; div.dataset.name p.name; div.innerHTML span${p.name}/span button classadd-btn加入购物车/button; div.querySelector(.add-btn).addEventListener(click, () { const count document.getElementById(cartCount); count.textContent Number(count.textContent) 1; }); productBox.appendChild(div); }); } document.getElementById(loginBtn).addEventListener(click, () { const u document.getElementById(username).value; const p document.getElementById(password).value; if (u tester p 123456) { document.getElementById(loginBox).classList.add(hidden); document.getElementById(shopBox).classList.remove(hidden); render(products); } else { document.getElementById(loginError).classList.remove(hidden); } }); document.getElementById(searchBtn).addEventListener(click, () { const kw document.getElementById(searchInput).value.trim(); render(products.filter(p p.name.includes(kw))); }); /script /body /html接下来在项目根目录创建playwright.config.js统一管理测试目录、超时时间、浏览器类型和失败产物// playwright.config.js const { defineConfig } require(playwright/test); module.exports defineConfig({ testDir: ./tests, timeout: 30_000, retries: 0, reporter: [[list], [html]], use: { headless: true, viewport: { width: 1280, height: 720 }, screenshot: only-on-failure, video: retain-on-failure, trace: on-first-retry, }, projects: [ { name: chromium, use: { browserName: chromium } }, ], });配置项解释testDir测试文件所在目录。timeout每个测试的超时时间默认 30 秒超过即失败。reporter测试结果同时输出到命令行和 HTML 报告。screenshot: only-on-failure失败时自动截图便于排查。video: retain-on-failure失败时保留录像。trace: on-first-retry重试时记录 Trace之后可以在 Trace Viewer 里逐步回放。最后创建第一个测试文件tests/first.spec.js// tests/first.spec.js const { test, expect } require(playwright/test); const path require(path); const SHOP_URL file:// path.resolve(__dirname, ../demo/shop.html); test(页面标题和登录表单正常渲染, async ({ page }) { await page.goto(SHOP_URL); await expect(page).toHaveTitle(Demo Shop); await expect(page.getByPlaceholder(用户名)).toBeVisible(); await expect(page.getByPlaceholder(密码)).toBeVisible(); await expect(page.getByRole(button, { name: 登录 })).toBeEnabled(); });运行测试npx playwright test命令行会输出通过或失败的结果。这是你跑通的第一个 Playwright 用例。如果想看浏览器真实操作过程可以加--headed参数npx playwright test --headed如果想逐步调试可以进入调试模式npx playwright test --debug调试模式会打开浏览器和 Playwright Inspector支持单步执行、查看定位器匹配了哪些元素、手动重试操作。新手排查定位问题时这个工具比反复改代码有效率得多。5. 项目实战登录、搜索、加购、断言第一个用例验证的是页面渲染这一节我们写真正的业务链路登录、搜索、加购、断言结果。这个流程覆盖了 Web 自动化测试里最常见的几类操作表单填写、按钮点击、列表渲染、元素数量断言、文本内容断言。创建tests/shop.spec.js// tests/shop.spec.js const { test, expect } require(playwright/test); const path require(path); const SHOP_URL file:// path.resolve(__dirname, ../demo/shop.html); test.describe(商城核心流程, () { test(用户能完成登录、搜索、加购完整流程, async ({ page }) { await test.step(打开商城页面, async () { await page.goto(SHOP_URL); }); await test.step(使用正确账号登录, async () { await page.getByPlaceholder(用户名).fill(tester); await page.getByPlaceholder(密码).fill(123456); await page.getByRole(button, { name: 登录 }).click(); await expect(page.getByText(商品列表)).toBeVisible(); await expect(page.locator(.product)).toHaveCount(3); }); await test.step(搜索商品并验证结果, async () { await page.getByPlaceholder(搜索商品).fill(机械键盘); await page.getByRole(button, { name: 搜索 }).click(); await expect(page.locator(.product)).toHaveCount(1); }); await test.step(加入购物车并验证数量, async () { await page.locator(.product).filter({ hasText: 机械键盘 }) .getByRole(button, { name: 加入购物车 }) .click(); await expect(page.locator(#cartCount)).toHaveText(1); }); }); test(错误密码时提示登录失败, async ({ page }) { await page.goto(SHOP_URL); await page.getByPlaceholder(用户名).fill(tester); await page.getByPlaceholder(密码).fill(wrong-password); await page.getByRole(button, { name: 登录 }).click(); await expect(page.locator(#loginError)).toBeVisible(); await expect(page.locator(#loginError)).toHaveText(用户名或密码错误); }); });关键点解释test.describe把相关的用例组织到同一组报告里会按组展示。test.step给用例步骤命名失败时报告能直接显示挂在哪一步。page.getByPlaceholder(用户名)直接根据输入框占位符定位不需要关心id或class。filter({ hasText: 机械键盘 })先在商品列表里筛出包含“机械键盘”的商品卡片再在这个范围内点击“加入购物车”。这个写法避免了页面上多个“加入购物车”按钮造成歧义。登录失败用例特意断言了错误提示可见并且断言了提示文案防止页面出现多个“错误”字样时误判。运行方式不变npx playwright test tests/shop.spec.js这条命令只跑商城相关用例比全量跑更快适合开发阶段迭代。如果你想确认定位器写得对不对推荐使用 Playwright 的代码生成器直接在浏览器里操作页面它会自动生成对应的测试代码npx playwright codegen https://example.com这个命令会打开一个浏览器窗口和代码生成面板。你在页面上点击、填表、选择元素面板会同步生成 Playwright 代码。新手可以先用它生成骨架再手动修正断言和业务逻辑。注意codegen生成的代码是“做了什么”的记录不一定包含合理的断言最终用例质量仍然需要人工把关。6. 用 AI Skills 让自动化测试效率翻倍2025 年再聊自动化测试绕不开 AI 编程助手。现在主流 AI 编程工具如 Codex CLI、Claude Code、Cursor 等都能直接生成 Playwright 测试代码但生成质量参差不齐。问题通常不在语法而在测试规范AI 可能写出page.screenshot满天飞、滥用waitForTimeout、用脆弱的 CSS 选择器、断言缺少业务含义的代码。行业里正在用Agent Skills解决这个问题。Skills 的形态是一个目录里面放一个SKILL.md说明文件再加上若干参考示例。AI 编程工具加载这个 Skill 之后生成代码时会自动遵守其中的规则。你可以把团队沉淀的 Playwright 测试规范写成 Skill让 AI 从一开始就按规范生成而不是生成之后再人工纠正。下面是一个可直接参考的 Playwright 测试 Skill 示例。在项目根目录创建skills/playwright-testing/SKILL.md# Playwright 测试技能 ## 目标 编写稳定、易维护的 Web 自动化测试用例。 ## 使用规范 ### 定位器选择 - 优先使用 getByRole、getByLabel、getByPlaceholder、getByText 等语义定位器。 - 避免使用 XPath 和深层 CSS 选择器如 html body div div button。 - 同一操作可能命中多个元素时使用 filter、nth、first 缩小范围。 ### 等待策略 - 禁止使用 page.waitForTimeout 作为常规等待手段。 - 等待页面状态时使用 expect(locator).toBeVisible() 等 Web 优先断言。 - 网络请求完成需要等待时优先使用 page.waitForResponse。 ### 断言要求 - 每个用例至少包含一条业务断言不能只断言“页面打开成功”。 - 断言文案要有业务含义例如 toHaveText(订单支付成功)。 ### 用例独立性 - 用例之间不允许互相依赖不共享登录态。 - 需要登录的用例在 beforeEach 或用例内部完成登录。 ### 失败现场 - 不要在用例里手动截图。 - 依赖全局配置的 screenshot、video、trace 方案收集失败现场。然后你可以让 AI 编程工具根据这个 Skill 为demo/shop.html生成测试。以 Codex CLI 为例大致交互思路是请先阅读 skills/playwright-testing/SKILL.md 中的测试规范 然后参考 demo/shop.html 的页面结构在 tests 目录下生成一组覆盖 登录、搜索、加购、登录失败场景的 Playwright 测试用例。AI 生成后你仍然要做三件事人工审阅断言是否表达业务意图、跑一遍全量测试、把不稳定的用例用 Trace 排查后修正。AI 擅长的是快速生成骨架和覆盖正常路径稳定性和业务正确性判断仍然要由人来把控。除了 Skills另一个值得关注的是Playwright MCP Server。MCPModel Context Protocol是 AI 应用与大模型之间的标准协议。Playwright 官方提供了 MCP Server运行后 AI 助手可以直接控制浏览器完成打开页面、点击、填写、读取控制台日志、截图等操作。启动方式npx playwright/mcplatest启动后支持 MCP 的客户端可以连接这个服务让 AI Agent“亲自”操作浏览器做验证。典型场景包括AI 修改前端代码后自动打开页面验证视觉效果AI 阅读页面 DOM 结构后生成更准确的 SelectorAI 根据用户描述复现 Bug并把复现步骤整理成测试用例。不过要提醒一点MCP 让 AI 能操作真实浏览器也意味着 AI 操作范围变大了。接入前建议确认工作目录、运行环境、运行命令都是可信的并且只能在你有权访问的测试环境里操作不要在未授权页面或生产环境随意执行。7. 运行结果与效果验证跑通用例之后最关键的是会看结果。输入npx playwright test预期输出类似下面这样Running 3 tests using 1 worker ✓ 1 tests/first.spec.js:8:1 › 页面标题和登录表单正常渲染 (1.1s) ✓ 2 tests/shop.spec.js:7:1 › 商城核心流程 › 用户能完成登录、搜索、加购完整流程 (1.8s) ✓ 3 tests/shop.spec.js:34:1 › 商城核心流程 › 错误密码时提示登录失败 (0.9s) 3 passed (4.2s)这里的3 passed表示全部通过。如果某个用例失败会显示✘和失败原因并自动生成失败截图和视频。测试结束后项目目录下会生成test-results和playwright-report两个目录。查看 HTML 报告npx playwright show-report报告会列出每条用例的耗时、通过状态、失败时的堆栈、截图、视频和 Trace。定位线上问题时Trace 尤其有用它记录了页面上所有网络请求、控制台日志、页面快照和鼠标操作你可以像看视频一样逐步回放失败过程。验证通过的标准不只看3 passed还要确认几个细节报告中有没有隐式警告例如 Locator 命中多个元素的提示。失败用例的截图和视频是否真实反映了问题现场。重复跑 3 次用例是否每次都稳定通过。第一次跑用例出现失败优先去看 HTML 报告里的错误堆栈和页面快照大多数问题在快照里一眼就能看出是元素没找到、文案不对还是页面 JS 报错。8. 常见问题与排查思路这一节整理零基础读者最容易遇到的 6 个问题按“现象 → 原因 → 排查 → 解决”的方式给出处理路径。问题现象可能原因排查方式解决方案npx playwright install chromium下载失败或卡住网络原因导致浏览器二进制下载不稳定查看命令行是否长时间停在 Downloading配置 npmmirror 镜像后重新下载运行时报TimeoutError元素在超时时间内没有变成可操作状态打开 HTML 报告看页面快照确认元素是否真的出现检查选择器是否精确确认页面是否有 JS 报错必要时增大 timeout定位器报strict mode violation一个选择器命中了多个元素Playwright 拒绝自动猜测在 Inspector 里运行定位器查看命中数量用filter、first()、nth()缩小范围或改用更精确的getByRole页面弹出非预期弹窗导致后续操作失败页面触发了alert、confirm或自定义弹层阻塞了操作查看 Trace 中是否有dialog事件用page.on(dialog, d d.accept())处理或在用例中按弹窗文案分支iframe 里的元素定位不到元素在 iframe 内部普通 Locator 无法跨 frame打开元素面板确认 DOM 结构是否有 iframe使用page.frameLocator(iframe选择器)再继续接 locator脚本本地全绿CI 上偶发失败CI 机器资源不足或页面加载时序不同对比本地与 CI 的截图、Trace配置重试retries: 1限制并行workers: 2保留 Trace补充一个高频问题waitForTimeout到底能不能用。我的建议是不要在业务逻辑里依赖它偶尔用来“等一个明显很慢的动画效果”可以但一旦养成习惯用例会越来越慢而且等待时间写死之后页面快的时候浪费时间慢的时候照样崩。用自动等待断言代替固定 sleep是 Playwright 用例稳定性的第一原则。9. 最佳实践与工程建议到这里你已经能跑通用例也知道了常见的坑。最后给一套能直接用于项目的工程建议分五块。9.1 定位器规范团队里建议统一“语义定位器优先”的规范并在 Code Review 时重点关注 XPath 和深层 CSS。规则可以浓缩为有getByRole用getByRole。有表单控件用getByLabel或getByPlaceholder。文本内容用getByText但要确认它不是匹配整个页面的大段文字。CSS 选择器保留用于测试属性例如>// 环境变量读取示例 const username process.env.TEST_USER || tester; const password process.env.TEST_PASSWORD || 123456;9.3 失败现场收集全局配置screenshot: only-on-failure、video: retain-on-failure、trace: on-first-retry。这三件套能覆盖绝大多数排查场景不需要在用例里手动截图。CI 上传测试报告产物时把playwright-report和test-results目录一并保留方便失败后下载分析。9.4 接入 CI在新项目里建议把测试接入 GitHub Actions 或 GitLab CI。最小化的 GitHub Actions 配置可以参考# .github/workflows/playwright.yml name: Playwright Tests on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps chromium - run: npx playwright test - uses: actions/upload-artifactv4 if: failure() with: name: playwright-report path: playwright-report/ retention-days: 7注意 CI 里要运行npx playwright install --with-deps chromium因为 CI 机器默认没有浏览器内核而且可能缺系统依赖。9.5 AI 辅助测试的边界AI 生成测试代码时能力和边界要分清楚。适合交给 AI 的根据页面描述生成用例骨架、补全重复性测试步骤、根据现有页面结构生成定位器。需要人把关的断言是否表达真实业务规则、用例是否依赖了时序、测试数据是否合理、是否涉及不可逆操作。凡是涉及发送真实请求、修改生产数据、删除资源的行为测试脚本里都不应该出现测试环境操作也要先确认权限边界。生产环境自动化测试要格外谨慎。任何自动化脚本都可能因为选择器变化或误操作造成真实业务影响跑生产脚本前必须有审批、最小权限账号、执行窗口和回滚方案。个人项目可以随意跑团队项目务必先约定好环境边界。10. 总结与后续学习方向现在回头看这篇文章的核心其实是一条链路安装 Playwright → 理解浏览器三件套和 Locator → 跑通第一个用例 → 写业务链路用例 → 用 AI Skills 提高生成质量 → 用报告和 Trace 排查问题 → 把规范沉淀进工程。如果你能独立跑通第 5 节的商城用例并且能把常见的 6 个问题按表格里的思路排查一遍就已经具备把 Playwright 用在日常项目里的基础能力。下一步建议从三个方向深入项目改造挑一条你日常维护的业务链路用本地页面或测试环境写一组覆盖“正常流程 异常场景”的用例先跑稳定再扩大范围。工程化能力研究 fixtures、多项目配置、WebServer 启动、API 请求复用、数据清理这些是大型项目自动化测试规模化绕不开的能力。AI Agent 工作流把第 6 节的 Skills 和 MCP 方案接入你常用的 AI 编程工具形成“AI 生成 → 人审阅 → 自动回归”的闭环。最后一条实用提醒不要一开始就追求用例数量。先让 10 条核心用例连续 7 天稳定通过比一次性写出 100 条天天失败的用例有价值得多。自动化测试的价值不在于代码量只在于你是否愿意持续维护它。