如何把现有 Puppeteer 项目迁移到 Playwright【免费下载链接】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如果你手上有用 Puppeteer 写的 Web 自动化脚本或测试用例项目想切换到 Playwright——一个用单一 API 测试 Chromium、Firefox 和 WebKit 的 Web 测试与自动化框架——仓库中的 Puppeteer 迁移指南 描述了完整的迁移原则、API 对照表和逐行改写示例。这篇文章按“安装 Playwright → 对照迁移脚本 → 改写测试用例 → 运行验证”的顺序给出可执行路径。适用环境来自 安装文档Node.jslatest 22.x、24.x 或 26.xWindows 11、Windows Server 2019 或 Windows Subsystem for LinuxWSLmacOS 14Sonoma或更高版本Debian 12 / 13Ubuntu 22.04 / 24.04 / 26.04x86-64 或 arm64按用途选择安装方式原项目的使用方式决定了装哪个 Playwright 包见 Library 文档自动化脚本原项目直接使用puppeteer库对应 Playwright Librarynpm i -D playwright之后还要下载浏览器可以手动执行也可以通过助手包在 npm install 时自动下载# 手动下载 Chromium、Firefox 和 WebKit 浏览器 npx playwright install chromium firefox webkit # 或者安装会在 npm install 时自动下载对应浏览器的包 npm i -D playwright/browser-chromium playwright/browser-firefox playwright/browser-webkit测试用例原项目用 Jest 等测试框架建议迁到 Playwright Test下面这条命令会初始化一个新项目或把 Playwright 加到现有项目中npm init playwrightlatestyarn 与 pnpm 的等价命令是yarn create playwright和pnpm create playwright。执行过程中需要确认TypeScript 或 JavaScript默认 TypeScript测试目录名默认tests若tests已存在则为e2e是否添加 GitHub Actions workflow推荐用于 CI是否安装 Playwright 浏览器默认是在现有项目中依赖会被加进当前的package.json稍后可以重复执行该命令它不会覆盖已有测试。脚手架包含playwright.config.ts # 测试配置 package.json package-lock.json # 或 yarn.lock / pnpm-lock.yaml tests/ example.spec.ts # 最小示例测试playwright.config 集中管理目标浏览器、超时、重试、projects、reporter 等配置。四条迁移原则官方迁移指南给出的原则是后续所有改写工作的依据大多数 Puppeteer API 可以直接使用Most Puppeteer APIs can be used as is。不推荐使用 ElementHandle改用 Locator 对象和 web-first assertions。Playwright 是跨浏览器的Puppeteer 不支持 WebKit。你大概不需要显式等待。API 对照速查表迁移指南提供了常用 API 的映射改写代码时优先查这张表PuppeteerPlaywright Libraryawait puppeteer.launch()await playwright.chromium.launch()puppeteer.launch({product: firefox})await playwright.firefox.launch()WebKit is not supported by Puppeteerawait playwright.webkit.launch()await browser.createIncognitoBrowserContext(...)await browser.newContext(...)await page.setViewport(...)await page.setViewportSize(...)await page.waitForXPath(XPathSelector)await page.waitForSelector(XPathSelector)await page.waitForNetworkIdle(...)await page.waitForLoadState(networkidle)await page.$eval(...)多数情况下可用 Assertions 直接校验 text、attribute、class 等await page.$(...)不推荐改用 Locatorsawait page.$x(xpath_selector)不推荐改用 Locators没有 checkbox 或 radio 专用方法await page.locator(selector).check()/await page.locator(selector).uncheck()await page.click(selector)await page.locator(selector).click()await page.focus(selector)await page.locator(selector).focus()await page.hover(selector)await page.locator(selector).hover()await page.select(selector, values)await page.locator(selector).selectOption(values)await page.tap(selector)await page.locator(selector).tap()await page.type(selector, ...)await page.locator(selector).fill(...)await page.waitForFileChooser(...)await elementHandle.uploadFile(...)await page.locator(selector).setInputFiles(...)await page.cookies([...urls])await browserContext.cookies([urls])await page.deleteCookie(...cookies)await browserContext.clearCookies()await page.setCookie(...cookies)await browserContext.addCookies(cookies)page.on(...)page.on(...)拦截并修改请求参见Page.routepage.waitForNavigation和page.waitForSelector在 Playwright 中仍然存在但由于 auto-waiting很多情况下不再需要它们。自动化脚本逐行改写官方示例把一个 Puppeteer 截图脚本逐行迁移到 Playwright Library。迁移后的脚本用node my-script.js直接运行。Puppeteer 原始脚本const puppeteer require(puppeteer); (async () { const browser await puppeteer.launch(); const page await browser.newPage(); await page.setViewport({ width: 1280, height: 800 }); await page.goto(https://playwright.dev/, { waitUntil: networkidle2, }); await page.screenshot({ path: example.png }); await browser.close(); })();逐行迁移到 Playwright数字注释对应下方说明const { chromium } require(playwright); // 1 (async () { const browser await chromium.launch(); const page await browser.newPage(); // 2 await page.setViewportSize({ width: 1280, height: 800 }); // 3 await page.goto(https://playwright.dev/, { waitUntil: networkidle, // 4 }); await page.screenshot({ path: example.png }); await browser.close(); })();改写要点每个 Playwright Library 文件都要显式导入chromium也可以同样导入webkit或firefox。若需要浏览器状态隔离考虑使用 browser contexts。setViewport改名为setViewportSize。networkidle2变为networkidle文档提示多数情况下由于 auto-waiting这个参数并无太大用处。如果想通过录制交互来生成 Playwright 代码可以运行npx playwright codegen wikipedia.org测试用例改写从 Jest 到 Playwright Test官方示例把 Puppeteer Jest 的测试迁移到 Playwright Test这是官方建议与 Playwright 搭配的第一方测试运行器提供 Page Object Model、并行、fixtures、reporters 等能力。Puppeteer with Jest 原始代码import puppeteer from puppeteer; describe(Playwright homepage, () { let browser; let page; beforeAll(async () { browser await puppeteer.launch(); page await browser.newPage(); }); it(contains hero title, async () { await page.goto(https://playwright.dev/); await page.waitForSelector(.hero__title); const text await page.$eval(.hero__title, e e.textContent); expect(text).toContain(Playwright enables reliable end-to-end testing); // 5 }); afterAll(() browser.close()); });迁移到 Playwright Testimport { test, expect } from playwright/test; // 1 test.describe(Playwright homepage, () { test(contains hero title, async ({ page }) { // 2, 3 await page.goto(https://playwright.dev/); const titleLocator page.locator(.hero__title); // 4 await expect(titleLocator).toContainText( // 5 Playwright enables reliable end-to-end testing ); }); });改写要点每个 Playwright Test 文件显式导入test和expect。测试函数标记为async。page是 Playwright Test 众多内置 fixtures 之一通过参数传入每个测试会得到一个隔离的Page对象。如果想让多个测试复用同一个Page可以在Test.beforeAll中自建、并在Test.afterAll中关闭。Page.locator是少数几个同步方法之一。用 web-first assertions 代替page.$eval()校验状态。Puppeteer 中常见用page.evaluate()或page.$eval()检查 ElementHandle、提取文本、属性或类名的写法在 Playwright 中可以用 web-first assertions 的对应 matcher 完成官方文档认为这种方式更可靠也更易读。运行并验证迁移后的测试安装完成后按 安装文档 运行测试npx playwright testyarn 与 pnpm 等价命令为yarn playwright test和pnpm exec playwright test。默认情况下测试以 headless 模式在 Chromium、Firefox 和 WebKit 上并行运行输出与聚合结果显示在终端。验证阶段常用参数查看浏览器窗口--headed只运行单个 project/浏览器--projectchromium只运行单个文件npx playwright test tests/example.spec.ts打开测试 UI--ui测试结束后HTML Reporter 提供按浏览器、passed、failed、skipped、flaky 等过滤的 dashboard。它只在有失败时自动打开手动打开用npx playwright show-report在报告中点击某个测试可以检查错误、attachments 和步骤这是定位迁移后具体某个用例失败原因的主要入口。限制与注意事项Locators 是严格的如果一个选择器匹配到多个元素针对目标 DOM 元素的操作会抛出异常迁移时需要保证原选择器指向唯一元素。web-first assertions 会不断重新取元素并检查直到条件满足或超时默认超时 5 秒可通过测试配置中的TestConfig.expect统一调整。迁移到 Playwright Test 后按官方文档还获得全量零配置 TypeScript 支持、在 Chrome/Firefox/Safari 等 web 引擎和 Windows/macOS/Ubuntu 上运行测试、多浏览器并行隔离执行、内置测试产物收集以及 Playwright Inspector、Codegen、Tracing 等随附工具。下一步Writing Tests用 web-first assertions、fixtures 和 locators 编写测试Running Tests过滤、headed 模式、sharding 与重试Codegen 生成测试Tracing事后调试测试运行轨迹【免费下载链接】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），仅供参考