企业官网建设流程全解析

说实话，我搞前端自动化测试这些年，工具换了一茬又一茬。最早是Selenium，后来折腾过Cypress，等微软开源了Playwright，我的第一反应是“又来一个框架？”结果用了一个月之后，我直接把公司项目里两百多条Selenium用例全部重写掉了。Playwright这个关键词在测试圈讨论度有多高不需要多解释，但真正把它用好、用明白，大部分人还停留在“录个脚本跑通”的阶段。这篇内容，我打算把从原理到实战踩坑的东西一次说清楚。

先说清楚它到底解决什么问题：跨浏览器端到端测试、动态页面断言、接口Mock、多页面和iframe处理，这些过去需要拼装各种工具链才能搞定的活儿，现在一个框架全包了。适合谁看？前端工程师、测试开发、以及所有想用浏览器自动化做数据采集和分析的同学。

1. Playwright到底改变了什么：自动化测试工具的演进逻辑

1.1 老工具的三个痛点：等待、驱动、多浏览器

在聊Playwright之前，得先明白过去的自动化测试工具为什么让人头皮发麻。拿Selenium举例，它称得上端到端测试的鼻祖，但用久了痛点非常明显。

第一个痛点是“等待”。页面加载是异步的，前端组件渲染有快有慢，你很难用一个固定sleep搞定所有场景。sleep短了元素还没出现，sleep长了整个测试慢得像蜗牛。早期Selenium的官方方案是ExpectedConditions，但这东西写起来啰嗦，而且很多新手直接无视它，测试不稳定了就在代码里乱加Thread.sleep，最后跑一次全量回归要几十分钟，一半时间在空等。

第二个痛点是“驱动”。Selenium的架构是WebDriver服务转发命令。你换一个浏览器版本，就得去下载对应的driver版本，版本对不上直接报session异常。我曾经在一个企业项目里同时维护Chrome、Firefox、IE三套driver，光是给测试机更新驱动就占了不少工时。

第三个痛点是“多浏览器支持”。老项目的UI自动化往往只覆盖Chrome，因为Chromium生态最好搞。一提到Safari和Firefox，要么是版本兼容问题，要么是WebDriver实现不完整，很多团队直接放弃。实际业务里用户用Firefox出了问题，测试覆盖率却是零。

1.2 Playwright的设计答案：同源驱动、自动等待、网络全接管

Playwright最惊艳的地方在于，它把上面这些问题当成设计目标来处理，而不是靠插件补丁。

首先是“同源驱动”。Playwright自己维护了Chromium、Firefox、WebKit三个内核的二进制下载，每个版本的Playwright对应固定的浏览器版本，不需要额外安装driver。它底层通过CDP（Chrome DevTools Protocol，Chrome开发者工具协议）和WebDriver BiDi与浏览器通信，本质上就是浏览器原生协议，响应速度远快于Selenium那种转发模式。

然后是“自动等待”。这是我在实际项目里体验最深的一点。Playwright的每个操作方法都有自己的actionability检查，它会自动等待元素可见、稳定、可接收事件，直到超时才会报错。也就是说你不需要写等待逻辑，框架自己会帮你判断。真正实践下来，你会发现测试代码大幅缩短，而且稳定性直线上升。

第三是“网络全接管”。Playwright内置page.route()接口，能拦截、修改、模拟网络请求。做测试的时候你可以彻底屏蔽掉外部接口，用本地mock数据驱动页面场景，这在Selenium时代需要一个单独的代理工具（比如BrowserMob Proxy）才能实现，配置过程繁琐且不稳定。

1.3 与Cypress、Selenium的核心差异

我经常被问到一个问题：“团队已经在用Cypress了，还有必要切Playwright吗？”这确实取决于项目场景。但单从能力表格来看，Playwright覆盖的范围明显更大：

Cypress的上手体验确实比Selenium好太多，调试也非常直观。但它的设计局限在于“一切都跑在同一个页面上下文里”，一旦遇到真正的多标签页、跨域测试或者原生iframe嵌套，就非常痛苦。Playwright的Context（浏览器上下文）设计从根本上解决了这种隔离和扩展问题。

还有一个容易被忽略的好处：Playwright的浏览器上下文天然隔离。每条测试用例开一个全新的上下文，Cookie、localStorage、缓存全都互不影响。这意味着并行执行时的串扰问题被框架层面直接掐死了，这也是我后来敢把全量用例并行的底气。

2. 零基础上手：安装、录制与第一个用例

2.1 环境搭建：npm安装与浏览器内核下载

先说环境准备。Playwright对Node版本有要求，建议装Node.js 18以上的LTS版本，实测在16上也勉强能跑，但我建议大家别折腾旧版本，能上新就上新，有些新特性和性能优化在低版本上是缺失的。

创建项目很简单，在任意目录下执行：

mkdir playwright-demo && cd playwright-demo npm init -y npm install -D @playwright/test

这里强调一下，@playwright/test是测试运行器，它包含了编写、运行、断言、报告的全部能力，日常使用时我们只需要依赖这一个包就够了。

然后下载浏览器内核。这一步很多人会卡住，因为默认是从CDN下载，国内网络环境经常失败。我的做法是先设置镜像环境变量再执行安装：

PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install

上面的命令会把Chromium、Firefox、WebKit三个浏览器都下载下来。如果你只想跑某个内核，也可以单独装，比如npx playwright install chromium。另外，在Linux服务器上运行测试时，浏览器依赖的系统库不一定完整，我建议先跑一次带依赖检测的安装：

npx playwright install --with-deps

这个命令会主动安装系统层面的共享库，是解决CI环境“浏览器打开就崩溃”最方便的一招。

2.2 用codegen录制一段测试脚本

说实话，Playwright的codegen工具是新手友好的核武器。它相当于一个带录制回放功能的浏览器，你在页面上点哪儿、输入什么，它都会自动生成对应代码。

启动方式：

npx playwright codegen https://example.com

运行之后会弹出一个浏览器窗口和一个代码生成面板。你在页面上的操作会被实时翻译成代码，连选择器都给你生成好了。右侧面板还能切换生成语言，想用TypeScript写测试就选TS，底层想用Python选Python也行。

录制时可以做的几件事：

• 点击按钮和链接，会生成click操作
• 输入文字，会生成fill操作
• 右键勾选“Assert that element is visible”，会生成一个断言语句，把元素可见性检查写进用例
• 每次操作后，面板顶部会显示自动等待建议，你可以直接复制进代码

我在团队里带新人时，基本要求就是先用codegen跑通一个完整流程，再手工优化选择器和断言逻辑。这种“先录再改”的方式，比一开始要求手写全部代码的学习曲线要平缓得多。

2.3 手工编写第一个断言用例

录制生成的代码往往有很多冗余，理解结构以后还是建议手写。下面是一个最基础的用例，它做的事很简单：打开首页，验证标题包含关键字，并检查搜索框是否可用。

import { test, expect } from '@playwright/test'; test('首页加载并包含核心元素', async ({ page }) => { await page.goto('https://example.com'); await expect(page).toHaveTitle(/Example/); const searchBox = page.getByRole('textbox', { name: '搜索' }); await expect(searchBox).toBeVisible(); await searchBox.fill('自动化测试'); });

跑测试的命令是：

npx playwright test

默认情况下，Playwright会启用项目配置里的所有浏览器项目，并对每条用例做断言失败自动截图。你在命令行里可以看到每个用例的通过状态，失败时会提供错误详情和定位步骤。

这里有必要解释下执行流程：测试运行时，Playwright会启动一个本地浏览器实例，但不会弹出窗口，因为它默认headless运行。想要看动画过程可以加--headed参数，调试某个用例加--debug，它会打开一个类似开发者工具的面板，能逐步查看每个操作和页面状态。

我在实际项目中，测试用例一般不会直接抛给浏览器跑，而是先在本地带着调试模式跑一遍，确认选择器和等待逻辑都对，再交到CI。这能省下大量来回提交的时间。

3. 核心机制拆解：选择器、自动等待与网络拦截

3.1 选择器：别再用脆弱的CSS类名

早年的自动化测试里，定位元素最常用的方式就是CSS selector，比如#login-btn、.nav-item。但随着前端工程化和组件化的发展，类名变得非常不可控。你可能今天写了一个.nav-item，明天组件库升级就变成了.nav-item--new，测试直接挂掉。

Playwright提供了一套更面向语义的选择器引擎，优先级按我的个人习惯是：

• >const article = page.locator('article'); await article.getByRole('button', { name: '点赞' }).click();

  这种写法比一次性写一个超长CSS路径可读性好很多，而且当页面结构调整时，只需修改链条前面的容器选择器，后面逻辑不用动。

  3.2 自动等待：不是sleep替代品，而是状态感知

  很多人刚接触Playwright时，容易把自动等待理解和“内置了sleep”混为一谈。实际上它的实现思路完全不同。每个动作执行前，Playwright都会对目标元素进行actionability检查，要求元素同时满足：依附到DOM、可见、稳定（尺寸位置不再变化）、可接收事件、无障碍元素不被遮挡。只有当这些条件都成立，它才真正执行点击或输入。

  这套机制的巧妙在于，它考虑了一个元素“能不能交互”，而不是单纯“存不存在”。比如一个有loading动画的按钮，虽然DOM存在，但它可能正在旋转、位置在变化，Playwright会一直等到动画停止才点击。这在月销过亿的业务系统里尤其关键，弹窗、loading、表格刷新都是动态交互的重灾区。

  但有几种情况自动等待机制也帮不上忙，需要手动处理：

  • 页面跳转后，新页面正在加载，需要await page.waitForLoadState('networkidle')
  • 某些WebSocket推送数据，只有数据到达后才渲染列表，可以用page.waitForResponse()等待特定接口返回
  • 滚动加载的分页内容，必须手动触发滚动

  给新手一个忠告：不要动辄就写page.waitForTimeout(3000)。这种固定的等待时长既不稳定，也无脑浪费时间。最稳的做法是拥抱可轮询的waitFor*方法，让测试根据真实页面状态推进。

  3.3 网络拦截与Mock：把接口依赖从用例中剥离

  端到端测试最头疼的问题之一是外部依赖：第三方接口挂了、订单服务联调环境不稳定、返回数据偶发异常。这时候测试用例再准也没用，因为跑在真实接口上就是会飘忽不定。

  Playwright的page.route()接口可以截获浏览器发出的一切请求。我们可以用本地数据替掉远程响应，或者直接断开某些无关请求来加速测试。

  await page.route('**/api/user/profile', async (route) => { await route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ id: 1, name: '测试用户' }), }); });

  有时候接口响应不是固定的，需要按请求内容动态决定。Route对象里能拿到请求的URL、请求头和body，body就是热点里常说的“body语法”，获取方式很简单：

  await page.route('**/api/submit', async (route) => { const request = route.request(); const postData = request.postDataJSON(); // 根据postData里的字段决定返回什么数据 await route.continue(); });

  除了数据Mock，网络拦截还能用来屏蔽测试中完全不关心的资源，比如图片、字体、统计脚本，这能明显缩短测试时间。我在一个大型后台项目中，光是拦截所有图片请求，整套测试耗时大约减少了四分之一。

  需要注意，route回调里必须调用route.continue()或route.fulfill()，否则请求会一直挂起。回调是异步的，写的时候很容易漏掉这点，创建了一个悬空的请求。

  4. 进阶实战：动态页面、数据采集与AI工具集成

  4.1 用Playwright采集动态渲染的页面内容

  除了做测试，我还经常把Playwright用在实际的数据采集工作中。传统的requests + BeautifulSoup只能拿到静态HTML，遇到前后端分离的项目，页面主体全靠JS渲染，源码里什么都没剩。这时候Playwright作为“带浏览器的爬虫工具”就非常顺手。

  举一个踩过的例子：采集某个社交平台的评论区。评论区是无限滚动加动态加载，用requests根本没法拿全，而Playwright可以模拟用户滚动并等待新内容出现。思路是这样的：

  1. 用page.goto()打开目标页面，等待首屏加载
  2. 循环执行页面滚动函数，把滚动条拉到最底部
  3. 每次滚动后，使用page.locator()重新获取评论区节点
  4. 记录当前可见的评论数量或ID集合
  5. 当连续多次滚动后评论数不再增长，判断已加载到底，结束循环

  需要注意一个细节：无限滚动的页面，DOM节点只保留可视区域附近的部分，前面的评论可能被框架回收了。解决办法是在滚动过程中把每次拿到的文本字段追加存到数组里，最后统一去重。单纯依赖最后一次性抓取DOM会漏数据。

  采集逻辑跑通后，我还会配合page.on('request')监听到的接口，直接把数据从接口层面拿，比从DOM提取快得多。Playwright的好处就在于：浏览器环境能正常应对那些必须带特定header和加密参数的接口，而requests模拟起来成本高、极易失效。

  4.2 在Scrapy中集成Playwright处理动态iframe

  做过爬虫的朋友都知道Scrapy是目前最成熟的同步爬虫框架，但它本身不执行JavaScript。遇到动态渲染的页面，过去只能依赖Splash（一个渲染服务）或者中间件拼一个浏览器，配置复杂。后来社区出了scrapy-playwright插件，它允许Scrapy的Request在渲染时自动走浏览器，同时保留Scrapy的调度和去重能力。

  配置第一步是安装插件并写入settings：

  DOWNLOAD_HANDLERS = { "http": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler", "https": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler", } PLAYWRIGHT_BROWSER_TYPE = "chromium"

  然后在Request里meta带meta={"playwright": True}，这个请求就会走浏览器渲染。

  处理iframe时比Scrapy原生方案优雅很多。Scrapy本身对iframe无能为力，而Playwright的frameLocator可以直接定位到iframe内部元素：

  frame = page.frame_locator("iframe[data-testid='content']") texts = frame.locator("div.post-content").all_text_contents()

  动态iframe一直是采集和自动化里的硬骨头。很多数据看板、地图组件、第三方登录页都嵌套在iframe里，从HTML源码里根本找不到那些元素。用scrapy-playwright做集成后，你可以先处理iframe内的元素，再把最终提取结果存成Item，交给Scrapy管道做清洗和入库。

  4.3 Midscene.js：AI驱动的测试用例新写法

  最近有一个叫Midscene.js的开源项目，热度上升很快。它做了一件很有意思的事：把AI识别能力注入到Playwright的测试流程里。热点里那句“midscene被playwright调用的原理”，简单说就是利用Playwright的扩展机制，把AI推理作为选择器的替代方案。

  传统选择器需要你精确定位元素，AI驱动的方式则是给一句自然语言描述，比如“点击页面中标题为《季度报表》的按钮”。Midscene.js的实现思路大致是：通过Playwright的页面上下文注入一段JS SDK，对页面截图并采集结构数据，然后将这些数据发给AI模型，模型返回目标元素的坐标或语义标记，SDK再把坐标映射成实际操作。

  集成到Playwright用例里通常是这样：

  import { test } from '@midscene/web'; test('AI驱动的测试用例', async () => { const ai = await extPage.getAIPlaywright(); await ai.navigate('https://example.com'); await ai.input('搜索框', '前端自动化'); await ai.click('第一个搜索结果'); });

  这种写法把测试用例从“定位元素的细节实现”中解放出来，直接用人类语言描述业务操作，可读性和可维护性都提升了一个维度。

  但它也有局限：AI推理的结果并非100%稳定，在核心业务链路里我依然会保守地使用传统选择器。AI更多是能帮你快速冒烟一遍，或者处理没有data-testid、没有稳定语义的老项目中找不到定位锚点的场景。正式回归还是老老实实上稳定选择器。

  4.4 Playwright MCP与Browser Use MCP的区别

  MCP（Model Context Protocol，模型上下文协议）是这两年AI Agent领域非常热的话题。简单理解，MCP为AI模型提供了一套标准化的工具调用接口，让AI能够通过工具操作外部系统。Playwright MCP和Browser Use MCP都是把浏览器能力暴露给AI用的中间层，但出发点不同。

  Playwright MCP是微软官方维护的MCP服务器，本质是把Playwright的能力封装成MCP工具。AI模型可以调用这类工具来打开页面、点击、输入、读取内容。它在测试场景下非常好用，尤其是做自动化测试用例生成时，AI可以看懂页面结构后自己写断言。

  我对Playwright MCP的使用经验主要集中在“人机协作调试”阶段——比如问我正在调的页面里某个表格有多少行，或者帮我分析某个接口返回不符合预期时的页面表现。

  Browser Use MCP则更偏“Agent自由浏览”。它的目标不是测试，而是让AI像用户一样在互联网上完成多步骤任务，比如收集信息、对比价格、操作后台。它内部也集成了浏览器控制能力，但接口设计更侧重任务完成度，而不是测试断言。

  两者最关键的区别可以总结成一句话：Playwright MCP做测试、验证、断言，Browser Use MCP做任务执行、信息获取。在实际AI应用开发平台（比如Dify这类工作流工具）里集成的,大多是把浏览器操作封装成一个工具节点，底层用Playwright驱动，这类场景本质上更接近Browser Use的定位。

  4.5 动态页面采集的合规边界与建议

  顺着数据采集的话题往下说，有一个内容我必须放在明面上强调：用Playwright采集动态页面数据和绕过目标站点防护是两回事。我在公司内部推动用户行为分析和公共数据监控时，会给团队立几条明确的规矩：

  • 只采集公开可见的数据，不采集需要登录或者明显带访问权限的内容
  • 遵守目标站点的robots协议和平台用户协议，不利用自动化工具绕过登录、验证码等访问控制机制
  • 控制采集频率，不会给目标服务器造成压力，出现压力阈值立刻退避
  • 优先寻找官方API或开放数据接口，自动化浏览器只是最后的降级方案

  有一次我确实遇到一个动态防护很强的目标站点，普通浏览器自动化一进去就触发风险检测。我当时的做法是主动放弃，转而寻找与业务方合作获取数据授权的路径。自动化工具的本职是提升研发和测试效率，用它去硬闯别人的防护体系，既不可靠，也大概率违反法律法规。这是技术选型时最容易忽略、却最不能忽略的一环。

  5. 工程化落地：TypeScript、CI与团队协作

  5.1 TypeScript + Playwright：用例的可维护性

  现在很多团队前端技术栈都是TypeScript，Playwright对这个生态的支持也是最优先的。我强烈建议新项目直接用TypeScript写测试用例，而不是JavaScript。理由不只是类型安全，更在于代码提示和自动补全能力能帮你快速回忆起API用法。

  一个常见的工程化配置是tsconfig.json，假设源码放在tests目录：

  { "compilerOptions": { "target": "ES2022", "module": "CommonJS", "strict": true, "types": ["node"] }, "include": ["tests/**/*.ts", "playwright.config.ts"] }

  Playwright配置文件里可以定义多个测试项目，每个项目指定浏览器和基础URL。例如：

  import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests', retries: 1, workers: 4, use: { baseURL: 'https://staging.example.com', trace: 'on-first-retry', screenshot: 'only-on-failure', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, ], });

  配置里的retries字段也很值得聊。我建议把重试次数设为1或2，尤其对于依赖异步数据的用例，偶发一次定位超时很常见，重试一次能有效降低误报。但重试次数不能太高，否则用例的真实稳定性会被掩盖，变成“重试三次总能过”的假绿。

  团队里复用测试逻辑，一般用Page Object Model（页面对象模式）。一个登录页面可以封装成LoginPage类，所有登录相关操作都在类里定义，测试用例只关注业务场景：

  class LoginPage { constructor(private page: Page) {} async open() { await this.page.goto('/login'); } async login(username: string, password: string) { await this.page.getByLabel('用户名').fill(username); await this.page.getByLabel('密码').fill(password); await this.page.getByRole('button', { name: '登录' }).click(); } }

  页面对象模式的好处在于，当前端页面重构时，你只需要改Page类，而不是去翻遍几百条用例。我在迁移Selenium用例时顺便用这套模式重构了一遍，后续维护成本肉眼可见地下降。

  5.2 GitHub Actions跑测试：一键回归

  CI集成是自动化测试真正产生价值的关键。用完例在本地跑只能保证“我机器上没问题”，只有每次提交都自动跑一遍，才能防止回归。我用GitHub Actions做过很多次，配置非常顺畅。

  下面是一个最简配置，放到.github/workflows/playwright.yml：

  name: Playwright CI on: push: branches: [main] pull_request: branches: [main] jobs: test: timeout-minutes: 30 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 - run: npx playwright test - uses: actions/upload-artifact@v4 if: always() with: name: playwright-report path: playwright-report

  这条流水线做的事情很简单：拉代码、装依赖、装浏览器系统库、跑测试、上传报告。如果用例失败，trace和截图都会作为artifact保留下来，开发者可以直接在详情页下载回放。我在真实项目里就靠这个功能让开发同事自己排查前端问题，不再占用测试资源。

  如果测试环境在自建机房或内网，GitHub Actions需要加一个自托管runner。Runner能跑在普通Linux服务器上，只要保证它能访问到被测环境和浏览器下载源即可。

  5.3 测试报告与失败诊断：HTML Report和Trace Viewer

  Playwright默认生成HTML报告，位置在playwright-report/index.html。这个报告包含所有用例的耗时、状态、失败步骤截图、控制台输出和网络请求时间。用它向Leader汇报测试质量非常直观，也能快速定位性能恶化的用例。

  但真正厉害的是Trace Viewer（追踪查看器）。设置trace: 'on-first-retry'后，失败重试的用例会录制完整行为轨迹。在trace面板里，你可以看到：

  • 页面每一步的DOM快照，像电影一样翻看操作过程
  • 网络请求的发起时间和响应详情，能看到接口是不是返回了500
  • 控制台报错信息，前端异常一目了然
  • 元素定位的实时调试，直接选中页面节点并查看当前选择器是否匹配

  刚迁移到Playwright那阵，我最常干的事就是让开发同学去翻trace，把“测试用例不稳定”具体成“接口偶发超时”或“一个按钮文案重复导致选择器匹配多个元素”，讨论效率瞬间提升。

  5.4 团队协作中的用例维护实践

  自动化用例最忌讳“一个人写、所有人不管”。我们团队最终定了几个协作约定，这里分享出来给需要的朋友参考。

  第一，用例和源码同仓管理。每一个测试文件和被测模块放在同一个MR（合并请求）里提交，前端改完代码必须同步更新相关用例。这样从机制上避免了代码改完了、用例半年没人修的沉疴。

  第二，用标签管理用例层级。冒烟用例打上--grep @smoke标签，线上巡检打@online，分区跑不同等级的测试，全量回归放在夜间Job里。可以有效控制每个环节的耗时。

  第三，测试数据尽量自治。不要依赖线上数据库里的特定记录，而是通过接口造数或直接在用例里初始化测试数据。我在一个电商项目里就吃过亏：测试用例依赖一个特定优惠券，运营后台某天把券下架了，第二天全量用例挂了一半，最后罚自己写了一套数据初始化脚本才根治。

  第四，并行执行时注意全局状态。多个worker同时启动，如果被测系统依赖共享的本地端口或全局缓存，容易互相踩踏。给每个worker分配独立账号或独立数据域是最稳妥的办法。

  6. 常见问题排查与避坑实录

  6.1 npx playwright install失败的处理流程

  npx playwright install失败是群里问得最多的问题之一。它失败的原因五花八门，但排错思路相对固定。

  第一步看报错类型。如果提示证书错误或ENOTFOUND，基本上是网络下载源的问题。换镜像源就行：

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

  第二步看是不是缺系统依赖。在Linux环境下，报错经常会提到libX11-xcb.so.1或者libnss3 missing这类字样。别手动去装一个个包，直接运行npx playwright install --with-deps，它会根据当前系统自动安装全套依赖。

  第三步看是不是已有浏览器冲突。某些用户电脑里装了自定义的Chromium，环境变量CHROME_PATH指向了错误路径，导致Playwright加载失败。这种情况需要检查环境变量：

  unset CHROME_PATH npx playwright install chromium

  如果还是失败，最后的手段是彻底清缓存重装。删除用户目录下的ms-playwright缓存文件夹，再重新执行安装，一般能解决大部分陈旧缓存导致的版本错乱问题。

  6.2 元素定位超时与选择器不生效

  元素定位超时是我在项目中遇到频率第二高的报错，错误信息通常是“Timeout 30000ms exceeded waiting for locator(...)”。

  把常见原因归纳成一张表，排查起来会清晰很多：

  报错场景	可能原因	解决方案
  元素在DOM里但不可见	父容器折叠、动画覆盖、页面滚动位置不对	改用expect自动等待或scrollIntoViewIfNeeded
  多个元素匹配	没有用严格模式，选择器命中了多个节点	加上strict: true，或改用getByRole更精确的定位
  元素在iframe内	普通page.locator找不到iframe内部元素	使用page.frameLocator().locator()链式定位
  元素在shadow DOM内部	常规CSS穿透不进去	使用穿透CSS选择器或建立自定义穿透封装
  页面跳转导致上下文失效	点击触发了新页面导航	等待新页面加载完成，用page.waitForURL或waitForLoadState

  遇到这类问题，我最推荐的排查方式是直接用codegen打开目标页面，手动导航到报错元素所在位置。codegen会自动生成能定位到元素的代码，如果生成不出来，说明元素不是常规渲染方式（iframe、shadow DOM、自定义组件）。这时候copy一份trace文件，在Trace Viewer里看每一步页面状态，比盯着报错文案瞎猜高效得多。

  6.3 并行执行时的用例串扰

  Playwright的浏览器上下文隔离做得很好，但用例之间的串扰问题并没有完全消失。最典型的例子是接口数据共用。两条用例都往同一张账单表里插入数据，第二条用例去查列表时，看到了第一条用例插入的数据，断言就会莫名其妙地挂掉。

  我的经验是给套件里增加用例级数据清理机制。在fixture的teardown中删除本次用例创建的数据。如果被测系统没有删除接口，可以约定测试数据统一使用某个前缀（比如test_auto_，可用时间戳区分），通过过滤前缀来规避数据干扰。

  另一个容易忽略的是登录态共享问题。不同用例使用同一账号并行操作，后端通常真的会把前一操作踢下线。解决办法是给每个用例创建独立浏览器上下文，同时准备一组测试账号池，通过fixture动态分配闲置账号。这套方案实施后，我们并行跑10个worker时几乎没有再出现过登录态互相挤掉的幺蛾子。

  6.4 动态页面的稳定性优化

  动态页面最大的坑在于“你觉得页面加载完了，其实数据还在请求中”。我见过很多人在写测试时，在goto()后加一句waitForTimeout(2000)就认为页面稳定了，这是最大的伪稳定性来源。

  更可靠的做法是判断业务数据真正到达了。比如页面有一个表格组件，你可以等待那个数据行出现：

  await page.waitForResponse( (response) => response.url().includes('/api/order/list') && response.status() === 200 ); await expect(page.getByText('订单编号')).toBeVisible();

  如果页面有骨架屏或者加载动画，尽量等待动画消失，而不是固定等待时长。因为等待真实状态变化永远是动态页面稳定的核心思路。

  另一个优化点是避免使用networkidle作为万能等待。networkidle要求网络空闲500ms，这在有多条持续WebSocket连接或定时轮询的页面上，可能永远等不到空闲状态。更接地气的等待方式是根据关键请求的响应事件来完成状态同步。

  6.5 和其他技术栈共存的取舍建议

  我经常被问，项目中既有Selenium老用例，又有新写的Playwright用例，能不能共存？从工程角度看完全可以，只要在CI里分成两个Job跑互不干扰即可。但从长期维护角度看，还是建议逐步把Selenium用例迁移过来。迁移的优先级很有讲究：先迁移最不稳定的、依赖多标签和网络Mock的、维护成本最高的那部分；简单表单填写的用例暂时留着不碍事，避免一次性大动干戈。

  另外，如果团队已经在用Cypress，我的建议是不必要的话不要同时推两套框架。两者的WebKit支持差异是主要考量点：需要Safari覆盖，Playwright是更优解；如果纯Chrome链路，Cypress的调试体验也很不错，切换成本大于收益时别折腾。

  我自己在多个项目中做了统计，Playwright用例相对Selenium的好处，最直观的改变有两点：一是执行速度明显提升，因为不再需要WebDriver中转协议，CDP直连的效率确实高；二是稳定性大幅上升，自动等待机制省掉了大量无谓的sleep，全量用例的失败率从过去“周五跑一次挂一半”，降到现在的“偶发网络波动才会红一个”。

  最后再分享一个小建议：如果你正准备给团队引入Playwright，先别急着把所有功能模块都铺满用例。挑一条核心业务链路，用page object模式写透、跑稳，让同事看到报告那一秒的直观冲击力，再逐步推广，比任何制度宣导都有用。

  用Playwright越久，我越觉得自动化测试的仿真度和稳定性并不矛盾。工具把那些繁琐的等待、驱动、选择器问题都替你承担了，剩下的就是你业务逻辑的表达再精准一点、数据隔离再干净一点。技术选的顺，项目跑的稳，团队自然愿意把自动化这件事一直做下去。