企业官网建设流程全解析

这两年做Web UI自动化，最明显的一个感受是：工具选型正在发生迁移。以前开个自动化项目，第一反应是“Selenium + 语言绑定 + TestNG/JUnit”，搭环境能折腾半天。现在再聊起这个事，越来越多的人会提到Playwright，而且不是简单的试用，是真真切切把核心链路跑起来了。我自己也是从Selenium切到Playwright的，最开始只是拿它写几个冒烟用例做对比，结果跑了两个月之后，团队决定把新项目的自动化全部迁过来。当时只是一次技术预研，最后却成了我们组自动化效率提升的关键转折点。

这篇文章是Playwright系列的第一篇，我会把从“为什么选择Playwright”到“第一个用例顺利跑起来”整个过程的关键环节拆开讲，包含环境搭建、脚本编写、录制调试和踩坑记录。内容尽量贴实际场景，不堆概念，适合正在选型自动化框架的测试开发工程师，也适合那些已经装了Playwright但还没写出稳定用例的初学者。

1. 为什么说Playwright是当前UI自动化的黑马

1.1 传统方案留给我们的那些“老毛病”

我从Selenium WebDriver时代就开始写UI自动化，说句实话，老方案能坚持这么多年，靠的是生态和习惯，而不是体验。最典型的问题有三个。

第一个是等待逻辑。以前写定位一个元素，先是driver.findElement，然后可能再加WebDriverWait，写一个ExpectedConditions，一套组合拳下来代码量翻倍，还需要自己判断什么场景该等什么条件。更麻烦的是，同样的元素，在本地环境、测试环境、生产环境可能加载快慢完全不同，等待时间稍短就偶发失败，稍长就拖慢整体用例速度。

第二个是多浏览器支持。Selenium通过不同Driver驱动不同浏览器，这在设计上没问题，但实际使用时经常遇到浏览器升级了、Driver版本不匹配，导致“某一天所有用例全部冒烟失败”。版本对齐这个事是个纯消耗型工作，没有价值感，但几乎每个季度都要做一次。

第三个问题是测试上下文管理。以前做多账号场景，要么开多个Driver实例，要么封装复杂的cookie注入逻辑，代码写出来又长又容易出bug。如果你需要并行跑用例，还得额外引入Selenium Grid，配置成本不低，维护起来也费劲。

当然不是说Selenium不行，只是它在设计上留下太多“需要用户自己补完”的部分。Playwright的出现，在相当程度上把这些缺口补上了。

1.2 Playwright的核心设计和它背后的思路

Playwright是某浏览器厂商团队推出的一款端到端测试工具，它的设计目标很明确：把稳定性、速度和开发者体验同时拉满。

它最硬核的一点是重新实现了浏览器驱动协议，不再走“中间转一层HTTP命令”的路线，而是直接用CDP（Chrome DevTools Protocol）与浏览器通信。这意味着启动浏览器、页面交互、截图、网络拦截这些操作不再有冗长的中间转换，响应速度更快，控制粒度也更细。

另一方面，Playwright把所有浏览器操作统一成一套API。同一段测试代码可以原样跑在Chromium、Firefox和WebKit上，不需要为不同浏览器写不同版本的定位逻辑。这意味着你写的用例，跨浏览器一致性极高。

还有一个很重要的隐藏优势：自动等待机制。Playwright的操作会自动等待元素可被操作，等待到超时为止。这个机制和Selenium里“找不到就立刻报错”的默认行为完全不同，它大幅减少了“元素还没加载出来导致用例失败”的问题。我换了Playwright之后，第一感受就是同样的用例，跑十次的失败率从以前的两三次降到了接近零。

1.3 对比其他框架，Playwright的核心优势在哪里

我整理了一个对比表格，方便还没接触过Playwright的人直观理解它在几个核心维度上的表现：

从表格可以清晰看到，Playwright几乎在每个关键维度上都做到了“开箱即用”。它没有把麻烦留给使用的人，而是尽可能在框架内部消化掉那些消耗精力的琐碎环节。

这个设计哲学，也让它的学习曲线相对平缓。如果你有Selenium的使用经验，大概半天就能上手写第一个用例；如果你是纯新人，跟着官方文档走一遍，一周内做出一个能跑的回归用例集是完全可能的。

2. 环境准备：从零搭建一套可用的Playwright工程

2.1 你需要的底层环境

Playwright官方支持Node.js、Python、Java和.NET，我这里以最常用的Node.js为例。这几个前置条件建议先确认：

• Node.js 18及以上：版本过低会导致部分API不可用，建议直接用LTS版本。
• npm或yarn：一般装Node时自带npm，够了。
• 操作系统：Windows、macOS、Linux都可以，Linux服务器上跑无头浏览器也完全正常。

先用命令确认一下Node版本：

node -v npm -v

如果是新环境且版本太低，建议直接去官网装最新LTS版本。版本差异带来的坑非常隐蔽，比如某些API在旧版Node上运行时不会直接报错，而是异步行为异常，排查起来相当痛苦。

2.2 初始化项目和安装依赖

在准备好的目录里执行：

npm init -y npm install -D @playwright/test

这里我建议把@playwright/test作为开发依赖安装，因为项目里不需要在运行时依赖它。如果你只是写脚本，不想用测试运行器，也可以只装playwright包，但作为正式项目，直接用@playwright/test体验更好，它自带了断言、fixture、并行执行等能力，省去额外集成一堆库的工作。

装完之后，执行浏览器驱动安装命令：

npx playwright install

这条命令会下载Chromium、Firefox和WebKit三个浏览器内核。假如你只跑Chromium系，可以在命令后面显式指定省去其他浏览器的下载，比如：

npx playwright install chromium

我实际使用中，还是建议全量安装。因为Playwright的价值之一就是跨浏览器测试，你就算当前用不到Firefox和WebKit，装好后随时可以手动跑一遍对比各浏览器表现。而且这些内核都是Playwright锁定的版本，不会因为日常浏览器升级导致用例挂掉。

2.3 快速验证环境是否正常

依赖装好后，可以创建一个最简用例验证，保存为smoke.spec.js：

const { test, expect } = require('@playwright/test'); test('快速验证环境', async ({ page }) => { await page.goto('https://example.com'); await expect(page).toHaveTitle(/Example Domain/); });

然后执行：

npx playwright test smoke.spec.js

看到测试通过，说明环境已经OK。这一步建议所有人做一下，别等到写了20条用例再一次性跑，到时候报错都不知道是环境的锅还是代码的锅。

注意：第一次运行可能较慢，因为需要启动浏览器内核。如果是在服务器或容器里跑，可能还需要额外安装系统依赖库。遇到报错先不要慌，后面的排查章节有解决方案。

3. 编写第一个自动化用例：我把一个登录场景拆给你看

3.1 先准备好一个可练习的页面

很多人刚上手Playwright时都会卡在一个地方：不知道拿什么页面练手。直接用生产环境怕搞出脏数据，搭一个完整系统又太重。

我建议的做法是：在你本地起一个简单的测试页面，比如一个纯前端的模拟登录页。不用接入真实后端，所有登录请求都由前端JS直接比较用户名和密码，这样你随时可以创建各种可控的测试数据。下面是一份基础HTML，保存为login.html，放在你项目目录的任意位置。

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>演练用登录页</title> <script> function fakeLogin(event) { event.preventDefault(); const u = document.getElementById('username').value; const p = document.getElementById('password').value; const msg = document.getElementById('msg'); if (u === 'tester' && p === '123456') { msg.textContent = '登录成功'; } else { msg.textContent = '用户名或密码错误'; } } </script> </head> <body> <h1>登录演练</h1> <form onsubmit="fakeLogin(event)"> <input id="username" type="text" placeholder="用户名" /> <input id="password" type="password" placeholder="密码" /> <button type="submit">登 录</button> </form> <div id="msg"></div> </body> </html>

然后在项目里把首页指向这个本地文件。

3.2 用例设计：比写代码更重要的是想清楚场景

编写自动化用例，最重要的是先梳理业务场景的步骤链路，而不是直接上手写代码。比如最基础的登录场景，核心路径可以拆成这几步：

• 打开登录页面，确认标题和表单可见。
• 输入合法的用户名和密码。
• 点击登录按钮。
• 验证登录成功提示出现。

再补充一条异常场景：

• 输入错误的密码。
• 点击登录按钮。
• 验证错误提示出现。

这两条用例合在一起，就覆盖了一个模块最常见的正向和逆向校验。这一点看似简单，但很多新手容易犯的毛病是只写正向路径，测了一堆“能跑通”的用例，却覆盖不到最核心的异常逻辑。

3.3 完整脚本与逐步解析

创建login.spec.js，把测试脚本写完整：

const { test, expect } = require('@playwright/test'); test('正向登录流程', async ({ page }) => { await page.goto('file:///path/to/your/login.html'); await expect(page.locator('#username')).toBeVisible(); await expect(page.locator('#password')).toBeVisible(); await page.fill('#username', 'tester'); await page.fill('#password', '123456'); await page.click('button[type="submit"]'); await expect(page.locator('#msg')).toHaveText('登录成功'); }); test('异常密码流程', async ({ page }) => { await page.goto('file:///path/to/your/login.html'); await page.fill('#username', 'tester'); await page.fill('#password', 'wrong-password'); await page.click('button[type="submit"]'); await expect(page.locator('#msg')).toHaveText('用户名或密码错误'); });

执行方式很简单：

npx playwright test login.spec.js

这条命令执行完，会输出每条用例的通过或失败状态，以及每个步骤的耗时。

这个脚本里值得注意的几个细节：

• page.fill和page.click：这两个API内部都自带等待机制，不需要额外写等待语句。
• expect(page.locator(...)).toBeVisible()：这种断言方式在Playwright里是异步等待的，它会在指定时间内不断重试，直到元素变得可见或超时，所以断言失败不容易卡在“页面尚未渲染”这种时序问题上。
• toHaveText：会等待元素的文本内容符合预期，而不是只检查一次，这大大增强了用例鲁棒性。

3.4 关于元素定位的取舍

脚本里用的是最朴素的#username和button[type="submit"]，这是最简单的选择器。实际项目中，我更推荐给需要自动化操作的关键元素加上><button>await page.click('[data-testid="login-btn"]');

这比用CSS类名定位更不容易被前端改动影响。关于这个方式，我需要补充说明一下：没有真实项目的支持时，我们只能选择结构稳定的CSS属性替代，但如果你主导一个项目的自动化基建，推动前端同学在关键节点加上>npx playwright codegen

运行后会自动打开一个浏览器窗口和一个Inspector面板。你在浏览器里的每一次点击、输入，都会实时生成对应的代码，而且可以随时切换生成JavaScript或者Python等不同语言版本。

但我会把录制结果看作“骨架”而不是“成品”。它会帮你自动生成定位信息和基础操作，但业务断言、异常场景、数据准备这些部分基本都得你手动补完。合理的流程是：

1. 用录制工具快速走一遍业务路径，得到基础代码。
2. 把代码复制到测试文件里。
3. 手动补充断言、边界条件和数据清理逻辑。

这样写用例效率非常高，尤其适合刚接手一个陌生系统时，用录制来快速探索页面结构。

4.2 调试模式：跑用例时逐步观察页面状态

有时候用例明明报错，但错误信息不够直观，尤其是元素定位失败的时候，光看文本很难判断问题出在哪。Playwright提供了调试模式，非常简单方便：

npx playwright test login.spec.js --debug

加了--debug后，测试会用有头模式启动浏览器，每个操作之前自动暂停，方便你检查页面当前状态。这种模式对定位“元素到底有没有在页面上”“弹窗是不是挡住了按钮”这类问题特别有效。

除了调试模式，还有一个很实用的开关，直接在测试运行时打开Trace Viewer：

test('登录流程', async ({ page }) => { await page.goto('file:///path/to/your/login.html'); // 其他操作 await page.screenshot({ path: 'login.png', fullPage: true }); });

截图是最基础的记录方式，但它的问题是只能记录某一个瞬间。Trace Viewer则不同，它会记录整个测试过程的页面快照、网络请求、控制台日志和每个步骤的操作细节，失败的时候可以完整回放一遍，看看到底是哪一步出了问题。开启Trace也很简单，在配置文件里把trace设置为on-first-retry或on都可以。

在日常开发中，我习惯这样组合使用：

• 用例失败时，优先看错误信息。
• 如果错误信息不够清楚，用--debug跑一遍，观察实际页面状态。
• 如果失败还是偶发性的，开启Trace，把失败那一刻的完整页面快照和网络情况拉出来分析。

4.3 对“录制能否替代手写”的一点看法

有人问过：既然录制已经能自动生成脚本，为什么还要手写？我实际体会是，录制生成的是“操作流”，而好的自动化用例需要的是“意图流”。什么叫意图流？就是代码看出去，能清晰理解当前在验证什么业务规则，为什么要执行这一步操作。比如“点击登录按钮”很容易录制，但“点击登录按钮并断言错误提示出现”才是真正有价值的用例编写。

另一方面，录制的定位方式通常是基于CSS选择器，生成出来可能很长、很脆弱。而手写时会更有意识地选择稳定的定位策略，比如>const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const contextAdmin = await browser.newContext(); const pageAdmin = await contextAdmin.newPage(); // 用管理员账号做操作 const contextUser = await browser.newContext(); const pageUser = await contextUser.newPage(); // 用普通用户账号做操作 await browser.close(); })();

这个隔离机制不仅适合多账号场景，也是并行用例执行的基础。每个测试文件在Playwright的fixture设计中都默认拥有独立的Context，所以默认情况下用例之间不会因为登录态、localStorage之类互相干扰。

这里有一个常见的理解误区：很多人以为“每个测试起一个浏览器实例”才算隔离，其实在Playwright设计里，Context层面的隔离已经足够，而且效率更高。打包在一个浏览器进程里更省资源，启动和销毁也更快。

5.2 多页面与多标签页操作的新姿势

过去在Selenium里操作多标签页，段代码又长又绕，要先获取窗口句柄列表，然后循环查找目标句柄。Playwright直接使用Page对象代表每个标签页，切换逻辑清晰了很多。

const page2 = await context.newPage(); await page2.goto('https://example.com');

如果你需要处理页面里通过window.open打开的新标签页，Playwright会触发page事件，你可以直接监听：

const [newPage] = await Promise.all([ context.waitForEvent('page'), page.click('[data-testid="open-new-tab-link"]') ]); await newPage.waitForLoadState();

注意这段代码里用到了Promise.all，原因是点击按钮和新页面打开这两个事件几乎同时发生，如果先点击再监听，很可能出现事件已触发但还没来得及监听的竞态。这种写法在Playwright官方文档和社区中被反复强调，也印证了在实际场景里“先等待事件再触发动作”能有效避免偶发失败。

5.3 权限与UA模拟：移动端预览也能自动化

除了常规桌面浏览器，Playwright还可以直接模拟移动端设备，包括移动版Chrome和移动版Safari的User-Agent、视口尺寸、设备像素比等。

const pixel = await browser.newContext({ viewport: { width: 375, height: 812 }, userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)', deviceScaleFactor: 3, isMobile: true, hasTouch: true });

这类配置在做移动端H5页面回归时特别有用。不用拉起模拟器，直接本地就能验证移动端布局和交互。我在参与某H5活动页测试时，就是用这组配置把几十条核心用例跑在虚拟移动端上，才避免了临时真机测试的成本。

6. 稳定性提升：网络拦截与Mock数据实战

6.1 为什么UI自动化里需要Mock接口数据

自动化用例的稳定性，最大的敌人之一就是后端不稳定。比如你在验证一个页面的渲染逻辑，前端依赖一个订单列表接口，结果后端在测试环境返回超时或异常数据，用例连页面都没渲染出来，更别提后续断言了。

这种情况下，网络拦截能力就是保命技能。Playwright可以在浏览器发出真实网络请求之前，直接用你预设的Mock数据拦截并响应，前端拿到的和真实请求返回的一模一样。这样你测的是前端页面逻辑，而不是后端接口健康度。

6.2 拦截单个接口并定制返回数据

用以下方式，可以拦截订单列表接口并返回固定数据：

await page.route('**/api/orders', route => { route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify([ { id: 1, status: 'PAID', amount: 99.9 }, { id: 2, status: 'UNPAID', amount: 299.9 } ]) }); }); await page.goto('https://your-site.dev/orders'); await expect(page.locator('.order-item')).toHaveCount(2);

这种做法把用例从“依赖真实环境数据”变成“完全可控的输入-输出验证”。当页面交互、展示逻辑和接口数据解耦之后，用例可以做到很大程度上不需要真实后端参与，在持续集成里跑得非常安静。

6.3 拦截请求并验证前端是否发送了特定参数

除了Mock返回，网络拦截还可以反过来用——监听前端发起的请求，验证请求体里是否带了期望的参数。这个能力在很多场景下非常有用。

举个例子，你在测试一个搜索功能，期望用户输入关键词后，前端会把关键词放在POST /api/search的请求体里。可以用以下方式捕获并断言：

let requestBody = null; await page.route('**/api/search', route => { const postData = route.request().postDataJSON(); requestBody = postData; route.continue(); }); await page.fill('#search-input', 'Playwright 教程'); await page.click('#search-btn'); await expect.poll(() => requestBody).toBeTruthy(); expect(requestBody.keyword).toBe('Playwright 教程');

这比纯黑盒点击页面、再断言页面渲染结果要可靠得多。你可以确认交互行为从操作到请求参数的全部链路，而页面渲染只是其中最表层的证据。

6.4 可组合的灵活Mock策略

实际项目中，你不太可能每次从零拼Mock数据。更务实的做法是封装Mock数据工厂方法，按用例维度准备不同数据集合。

一个简易的封装示例如下：

function mockOrderList(orders) { return async (route) => { await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(orders) }); }; } test('空列表状态下的空态展示', async ({ page }) => { await page.route('**/api/orders', mockOrderList([])); await page.goto('https://your-site.dev/orders'); await expect(page.locator('.empty-status')).toBeVisible(); });

这样不同用例只需要传入不同的数据数组，页面渲染逻辑完全由测试自己掌控。它最大的优势在于，让测试不再“看后端脸色”，也让失败定位归因更简单。如果挂了，基本就是前端或测试自身的问题，不大会甩锅给“环境数据变动”。

7. 常见问题与排查手册：给你一张问题速查表

7.1 启动浏览器失败，提示缺少系统依赖

如果在Linux服务器上直接跑，经常看到类似“Host system is missing dependencies”的报错。这多数是因为系统缺少浏览器运行所需的动态链接库，而不是Playwright本身出了问题。

解决办法是执行：

npx playwright install-deps

这条命令需要用root或有sudo权限的用户执行。它会自动安装所有浏览器依赖库。装完后再跑测试，大概率能过。如果还有个别缺库，检查报错信息里提示的缺失库名，用系统包管理器单独安装即可。

7.2 同一个用例在本地能过，CI环境却偶尔失败

这类问题我见过很多次，本质原因大多是时序问题或资源差异。排查思路一般是：

• 是不是本机网络环境和CI差异太大？接口响应时间是否不稳定？
• 用例里是否依赖了固定等待时间？比如waitForTimeout(3000)这种硬编码，在CI环境可能不够用。
• 测试过程是否依赖真实后端数据，而后端数据在CI环境里不可预知？

解决方向也很明确：优先用自动等待替代固定等待，尽量用Mock数据验证前端逻辑，把用例从环境依赖里剥离出来。如果你在一个用例里看到waitForTimeout，先想想能不能删掉，绝大多数情况下是可以的。

7.3 元素定位失败，如何快速定位是选择器问题还是时序问题

先记住一个结论：元素定位失败，多数情况是时序问题，而不是选择器本身写错了。实际操作中，你可以按照下面顺序处理。

先打开调试模式，看报错那一刻页面到底处于什么状态。如果把--debug跑一遍，发现页面还停留在加载中或者元素确实尚未渲染，那基本就是时序问题，可以优化等待条件或改用更稳健的选择器。如果页面正常，但元素就是找不到，则需要检查选择器是否写错，或者页面里出现了多个相似元素。

这里插一个常见错误示例：页面上有多个按钮，登录和注册都用button标签，如果直接用page.click('button')，Playwright会报错提示“元素不唯一”，并列出所有匹配的按钮。解决方法是换用更具体的选择器，比如button[type="submit"]或[data-testid="login-btn"]。

7.4 点击某些按钮时提示“元素被遮挡”

出现这种提示，说明元素本身存在，但它无法接收点击，因为另一个元素覆盖在它上方，这可能是弹窗、浮层或loading遮罩造成的。

这种问题用传统思路比较麻烦，但Playwright处理起来相对简洁。先检查是否有遮挡，可以用：

await page.locator('#submit-btn').click({ timeout: 5000 });

如果还是不行，就需要你先关闭或等掉弹窗，比如：

await page.keyboard.press('Escape');

这一种做法对很多弹窗场景都有效。如果弹窗是特定的，也可以先点击弹窗的关闭按钮，再执行后续操作。基本原则是：尊重用户真实操作路径，不要直接使用click({ force: true })，因为强制点击绕过了真实交互，可能掩盖实际显示的问题。

7.5 问题排查速查表

8. 实操心得与后续规划

这段时间推广Playwright的过程中，我最深的体会是：工具选型从来不只是一个技术比较问题，它还关系到团队的日常开发节奏和用例维护成本。Playwright在稳定性和开发者体验上的优势，直接改变了我们写自动化的方式——从“写代码顺便处理各种环境问题”变成“冷静地专注于业务场景本身”。

如果你还在Selenium的等待逻辑、Driver管理这些琐碎问题里消耗精力，我建议你花一天时间，建一个最小工程，跑通一套冒烟用例，亲自感受一下自动等待、Trace回放和Context隔离带来的差别。纸上对比再多，也不如一次真实验证来得直观。

这个系列后续我会继续展开两个方向：一是从单一用例走向测试工程化，讲解Page Object模式在Playwright项目里怎样落地更合理，以及如何配置CI流水线；二是深入介绍视觉回归、移动端模拟和性能追踪这些进阶用法。这些都是我在实际项目中验证过的思路，有兴趣的话可以保持关注。