企业官网建设流程全解析

如果你所在团队的 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 走 CDP，Firefox 和 WebKit 走各自的远程调试协议），并且把自动等待内置到每一个操作里。你调用click()时，框架会自动等待元素可见、稳定、可被点击，直到超时。这一条改进，直接消灭了开发中最多的一类不确定性。

再对比一下测试运行器的体验。Selenium 本身不带测试框架，你需要自己拼 JUnit、TestNG 或者 pytest；断言失败时想看现场，要么自己写截图逻辑，要么装第三方库。Playwright 开箱自带测试运行器、断言库、HTML 报告、Trace 录制、失败截图、视频回放，还有测试隔离的 BrowserContext。新手不需要理解这一整套生态是怎么拼起来的，装完就能跑。

下面是三款常用框架的快速对比，方便你判断选型：

这张表不是要否定 Selenium。Selenium 胜在生态成熟、语言绑定多，很多老项目仍然跑得很稳。但如果你正在启动一个新项目，或者准备把自动化测试工程化，Playwright 的默认体验明显更顺。这篇文章后面的实战全部基于 Playwright，版本以当前最新稳定版为准，不针对特定版本做过深绑定。

2. Playwright 核心概念：自动等待、定位器与测试运行器

零基础读者第一次接触 Playwright，最需要理解三个概念：浏览器三件套、定位器、Web 优先断言。

2.1 浏览器三件套：Browser、BrowserContext、Page

Playwright 的对象模型分三层：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_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium

Windows 用set，macOS/Linux 用export PLAYWRIGHT_DOWNLOAD_HOST=...。

3.3 验证安装是否成功

执行以下命令，能输出版本号说明安装成功：

npx playwright --version

到这里，环境准备就完成了。如果第 3 步失败，大概率是浏览器内核没装好，而不是测试库的问题。

4. 第一个测试项目：从零跑通一个用例

为了不依赖外部网站，也避免目标网站改版导致用例失效，这一节我们用一个本地 HTML 页面做测试目标。你可以在项目里新建demo/shop.html，这是一个内置了登录、搜索、加购逻辑的极简商城页面，所有逻辑都写在 HTML 内部，不依赖任何外部服务。

<!-- demo/shop.html --> <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <title>Demo 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 id="loginBox"> <h1>登录</h1> <input id="username" placeholder="用户名" /> <input id="password" type="password" placeholder="密码" /> <button id="loginBtn">登录</button> <p id="loginError" class="error hidden">用户名或密码错误</p> </div> <div id="shopBox" class="hidden"> <div class="cart">购物车数量：<span id="cartCount">0</span></div> <h1>商品列表</h1> <input id="searchInput" placeholder="搜索商品" /> <button id="searchBtn">搜索</button> <div id="products"></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 class="add-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('用户名或密码错误'); }); });

关键点解释：

1. test.describe把相关的用例组织到同一组，报告里会按组展示。
2. test.step给用例步骤命名，失败时报告能直接显示挂在哪一步。
3. page.getByPlaceholder('用户名')直接根据输入框占位符定位，不需要关心id或class。
4. filter({ hasText: '机械键盘' })先在商品列表里筛出包含“机械键盘”的商品卡片，再在这个范围内点击“加入购物车”。这个写法避免了页面上多个“加入购物车”按钮造成歧义。
5. 登录失败用例特意断言了错误提示可见，并且断言了提示文案，防止页面出现多个“错误”字样时误判。

运行方式不变：

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。MCP（Model Context Protocol）是 AI 应用与大模型之间的标准协议。Playwright 官方提供了 MCP Server，运行后 AI 助手可以直接控制浏览器，完成打开页面、点击、填写、读取控制台日志、截图等操作。

启动方式：

npx @playwright/mcp@latest

启动后，支持 MCP 的客户端可以连接这个服务，让 AI Agent“亲自”操作浏览器做验证。典型场景包括：AI 修改前端代码后，自动打开页面验证视觉效果；AI 阅读页面 DOM 结构后，生成更准确的 Selector；AI 根据用户描述复现 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 个问题，按“现象 → 原因 → 排查 → 解决”的方式给出处理路径。

补充一个高频问题：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/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps chromium - run: npx playwright test - uses: actions/upload-artifact@v4 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 用在日常项目里的基础能力。下一步建议从三个方向深入：

  1. 项目改造：挑一条你日常维护的业务链路，用本地页面或测试环境写一组覆盖“正常流程 + 异常场景”的用例，先跑稳定再扩大范围。
  2. 工程化能力：研究 fixtures、多项目配置、WebServer 启动、API 请求复用、数据清理，这些是大型项目自动化测试规模化绕不开的能力。
  3. AI Agent 工作流：把第 6 节的 Skills 和 MCP 方案接入你常用的 AI 编程工具，形成“AI 生成 → 人审阅 → 自动回归”的闭环。

  最后一条实用提醒：不要一开始就追求用例数量。先让 10 条核心用例连续 7 天稳定通过，比一次性写出 100 条天天失败的用例有价值得多。自动化测试的价值不在于代码量，只在于你是否愿意持续维护它。