Playwright 从 Protractor 迁移实战指南ElementFinder 到 Locator 的完整对照与 waitForAngular 替代方案【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright本文以 Playwright 官方仓库中的迁移文档 protractor-js.md 为核心系统讲解如何将一套 ProtractorSelenium WebDriver 时代的 Angular 自动化测试框架用例迁移到 Playwright Test包括 ElementFinder 与 Locator 的逐条对照表、官方 todo list 示例的逐行迁移、waitForAngular的两种 polyfill 方案以及 Playwright 相比 Protractor 额外提供的自动等待、多浏览器并行与录制/追踪能力。读完本文你可以独立完成一个 Protractor 项目的迁移并理解 Locator 实现 背后的选择器链式拼接机制。迁移总原则在动手改写任何用例之前先建立四个核心认知。这四点来自官方迁移文档的 Migration Principles 章节决定了后续所有改写方式不再需要 webdriver-manager / Selenium。Protractor 用例背后依赖的 WebDriver 服务端、浏览器驱动版本管理webdriver-manager在 Playwright 中全部消失——Playwright 自带浏览器二进制由 browsers.json 描述浏览器构建信息测试直接通过协议驱动浏览器不存在驱动兼容性问题。Protractor 的 ElementFinder ⇄ Playwright 的 Locator。Protractor 中element()/element.all()返回的 ElementFinder对应 Playwright 中的 Locator API。Locator 是惰性描述符创建时不触碰 DOM每次操作时重新解析天然规避元素被框架重新渲染后引用失效的问题。waitForAngular⇄ Playwright 的自动等待auto-waiting。Protractor 必须在每个操作前后显式等待 Angular 稳定Playwright 在每个动作执行前自动完成可见性、稳定性、可操作性检查绝大多数场景不再需要手写等待详见 actionability.md。不要忘记await。Protractor 基于 Promise 队列protractor 的 promise manager串行执行调用本身不需要 awaitPlaywright 是标准的 JavaScript 异步模型几乎所有 API 都返回 Promise必须await。这是迁移中最高频的坑。从源码层面印证第 2 点Page.locator()与Locator.locator()创建 Locator 是同步的它只是在字符串层面拼接选择器。见 locator.tslocator(selectorOrLocator: string | Locator, options?: OmitLocatorOptions, visible): Locator { if (isString(selectorOrLocator)) return new Locator(this._frame, this._selector selectorOrLocator, options); ... }也就是说page.locator(..1.. text..2..)中的链式选择器语法就是 Locator 把多个选择器用拼接成一个字符串、由浏览器端的注入脚本逐级解析实现的。这与官方对照表中by.cssContainingText(..1.., ..2..)→page.locator(..1.. text..2..)的写法完全一致。而click()、fill()等动作方法则是异步的locator.ts#L117-L119、locator.ts#L152-L154它们会等待选择器解析出唯一元素并满足可操作性条件后才真正执行——这正是 Dont forget to await 的底层原因。选择器 Cheat Sheetby.* 到 Locator 的完整对照官方文档提供了一张速查表覆盖 Protractor 绝大多数定位方式。下表完整保留该速查表并对每一行补充了迁移时需要注意的细节ProtractorPlaywright Test说明element(by.buttonText(...))page.locator(button, input[typebutton], input[typesubmit] text...)Playwright 没有等价的by.buttonText引擎用一组标签选择器 text组合替代。若希望语义化也可以写成page.getByRole(button, { name: ... })element(by.css(...))page.locator(...)一一对应CSS 选择器可直接复用element(by.cssContainingText(..1.., ..2..))page.locator(..1.. text..2..)用链式选择器表达先按 css 定位再在结果中按文本过滤element(by.id(...))page.locator(#...)直接用 CSS id 选择器element(by.model(...))page.locator([ng-model...])Angular 1 的ng-model属性选择器element(by.repeater(...))page.locator([ng-repeat...])Angular 1 的ng-repeat属性选择器element(by.xpath(...))page.locator(xpath...)注意 Playwright 中 xpath 需显式加xpath前缀element.allpage.locatorelement.all()返回所有匹配page.locator()本身就是集合式定位配合nth()/first()/last()取单项browser.get(url)await page.goto(url)注意 awaitgoto默认等待 load 事件行为比browser.get更明确browser.getCurrentUrl()page.url()page.url()是同步方法无需 await两个 Protractor 惯用模式在 Playwright 中的对应关系值得展开集合取值Protractor 的todoList.get(2)对应 Playwright 的todoList.nth(2)todoList.count()对应await todoList.count()。nth()的实现见 locator.ts#L251-L253它同样是同步的——内部只是拼接 nth${index}真正的求值发生在后续动作或断言中。断言风格Protractor 的expect(...)来自 Jasmine在 Playwright Test 中被替换为 web-first 断言。expect(todoList.count()).toEqual(3)迁移为await expect(todoList).toHaveCount(3)——后者是自动重试的在超时窗口内反复轮询直到条件成立或失败而不是像一次性断言那样只查一次。完整的断言列表见 test-assertions-js.md。官方示例逐行迁移angularjs.org todo list这是迁移文档中最核心的实战部分。先看 Protractor 原版用例针对 angularjs.org 首页的 todo 列表describe(angularjs homepage todo list, function() { it(should add a todo, function() { browser.get(https://angularjs.org); element(by.model(todoList.todoText)).sendKeys(first test); element(by.css([valueadd])).click(); const todoList element.all(by.repeater(todo in todoList.todos)); expect(todoList.count()).toEqual(3); expect(todoList.get(2).getText()).toEqual(first test); // You wrote your first test, cross it off the list todoList.get(2).element(by.css(input)).click(); const completedAmount element.all(by.css(.done-true)); expect(completedAmount.count()).toEqual(2); }); });迁移到 Playwright Test 后官方给出的逐行对照版本数字对应文末迁移要点const { test, expect } require(playwright/test); // 1 test.describe(angularjs homepage todo list, () { test(should add a todo, async ({ page }) { // 2, 3 await page.goto(https://angularjs.org); // 4 await page.locator([ng-modeltodoList.todoText]).fill(first test); await page.locator([valueadd]).click(); const todoList page.locator([ng-repeattodo in todoList.todos]); // 5 await expect(todoList).toHaveCount(3); await expect(todoList.nth(2)).toHaveText(first test, { useInnerText: true, }); // You wrote your first test, cross it off the list await todoList.nth(2).getByRole(textbox).click(); const completedAmount page.locator(.done-true); await expect(completedAmount).toHaveCount(2); }); });迁移要点与文档中的 inline 注释一一对应显式导入test与expect。每个 Playwright Test 文件顶部都要写const { test, expect } require(playwright/test)ESM 场景用import。Protractor 中browser、element、by是全局注入的这一心智模型要换掉。测试函数标记为async因为函数体内要 await 浏览器调用。page通过参数解构注入。Playwright Test 的 fixtures 机制会向测试函数传入page以及browser、context等大量内置 fixture每个测试都会拿到全新的、互相隔离的上下文。几乎所有 Playwright 调用都要加awaitgoto、fill、click、toHaveCount均是如此。Locator 创建是少数同步方法之一page.locator(...)、todoList.nth(2)、getByRole(...)都同步返回新的 Locator不产生网络/浏览器往返只有真正执行动作或断言时才异步。这与上一节源码中的实现一致。逐行迁移时还有三处细节值得注意sendKeys→fillProtractor 的sendKeys是模拟逐字符键入Playwright 的fill()直接设置值并触发 input 事件速度快且稳定。若确需模拟逐字输入例如测试实时联想应改用locator.type(first test)。getText()→toHaveText且注意useInnerTextelement.getText()返回的是渲染后的 innerText因此迁移到断言时用toHaveText(first test, { useInnerText: true })保证语义一致。toHaveText的默认行为更接近 outerHTML 文本匹配迁移带文本断言的用例时务必核对这个选项。element(by.css(input))→getByRole(textbox)文档示例把在 todo 项里找 input从 css 选择器升级成了 role 定位。role-based 定位器getByRole、getByLabel、getByText等在 Locator 实现中 都是把 role 参数翻译为internal:前缀的内部选择器再拼接到选择器链上比裸 css 选择器更能抵抗前端重构建议迁移时顺势升级。PolyfillwaitForAngular两种方案Playwright 内置的 自动等待 在一般情况下使waitForAngular变得多余每次click/fill/断言前Playwright 都会自动完成元素存在 → 可见 → 稳定bounding box 连续两帧不变→ 可接收事件的检查序列。但官方文档明确指出在少数边缘场景下例如你需要在动作发生前确认整个 Angular 应用已完成本轮变更、且此时没有任何可锚定的具体元素polyfill 一个waitForAngular仍然有用。文档给出了两种实现均完整保留如下。方案一直接复用 Protractor 的客户端脚本全版本 Angular前提你的package.json中仍安装着 protractor。直接取用 Protractor 内置的客户端注入脚本async function waitForAngular(page) { const clientSideScripts require(protractor/built/clientsidescripts.js); async function executeScriptAsync(page, script, ...scriptArgs) { await page.evaluate( new Promise((resolve, reject) { const callback (errMessage) { if (errMessage) reject(new Error(errMessage)); else resolve(); }; (function() {${script}}).apply(null, [...${JSON.stringify(scriptArgs)}, callback]); }) ); } await executeScriptAsync(page, clientSideScripts.waitForAngular, ); }实现思路Protractor 的waitForAngular本质是往页面里注入一段脚本Protractor 的browser.executeScriptPlaywright 没有executeScriptAPI所以用page.evaluate手搓了一个注入函数 回调转 Promise的执行器——把脚本字符串包进 IIFE通过callback参数把完成/报错传回 Node 侧。方案二基于 Testability API 的轻量实现仅 Angular 2如果不想为了一个 polyfill 而保留整个 protractor 依赖可以直接调用 Angular 自身的 Testability 全局 APIasync function waitForAngular(page) { await page.evaluate(async () { // ts-expect-error if (window.getAllAngularTestabilities) { // ts-expect-error await Promise.all(window.getAllAngularTestabilities().map(whenStable)); // ts-expect-error async function whenStable(testability) { return new Promise(res testability.whenStable(res)); } } }); }原理Angular 2 会在window上暴露getAllAngularTestabilities()每个Testability实例都有whenStable(callback)在应用没有未完成的变更检测/宏任务时回调。两个方案都只在页面存在该 API 时才生效非 Angular 页面会安全跳过。使用方式const page await context.newPage(); await page.goto(https://example.org); await waitForAngular(page);注意page.goto默认已等待load事件waitForAngular之后才是业务断言/操作的安全起点。迁移之后Playwright Test 提供的增量能力文档的 Playwright Test Super Powers 一节列出了留在 Playwright 生态中的收益逐条对应到仓库中的实际能力零配置 TypeScript 支持Playwright Test 内置 TypeScript 执行无需额外配置编译步骤测试入门文档 给出的npx playwright test即跑即得。跨全部主流浏览器引擎Chromium、Firefox、WebKit 三种引擎覆盖 Windows、macOS、Ubuntu 等主流操作系统browsers.json 中记录了各浏览器构建的下载与校验信息。多源站、(i)frame、多标签页与上下文支持Protractor 时代跨 frame/tab 需要繁琐的browser.switchTo与 Angular 感知切换Playwright 的 Frame API 与 Pages/Contexts 文档 提供了一等的frameLocator、page.waitForEvent(popup)等能力。跨浏览器并行执行测试可并行跑在多个浏览器上由测试 runner 的分片与隔离机制完成。内置产物artifact收集截图、视频、trace 等录制选项在 test-use-options 的 recording 一节中配置失败自动收集。配套工具链Playwright Inspector逐步调试器可视化每一步动作与页面状态Codegennpx playwright codegen录制操作并直接生成测试代码——迁移 Protractor 套件时对个别难以手写的用例可以先录制再生成再手工修正Tracing逐请求、逐操作、带截图的追踪文件用于事后post-mortem调试配合 Trace Viewer 查看。对于从 Protractor 迁移而来的大型套件推荐顺序是先整体套用 Cheat Sheet 与自动等待原则改写定位与断言 → 用--reporterhtml观察失败项 → 对仍有偶发的用例打开 trace 定位是否缺了waitForAngular级别的等待 → 必要时按上文 polyfill 补上。延伸阅读Getting StartedPlaywright Test 入门Fixtures理解page等测试夹具的注入机制LocatorsLocator 与链式选择器的完整语义Assertionsexpect(locator)全部 web-first 断言Auto-waiting自动等待的触发条件清单Locator APInth、filter、and/or、getByRole等方法的完整签名【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考