跳到主要内容

从 Puppeteer 迁移

迁移原则​

本指南介绍如何从 Puppeteer 迁移到 Playwright Library 和 Playwright Test。这些 API 有相似之处，但 Playwright 为 web 测试和跨浏览器自动化提供了更多可能性。

  • 大多数 Puppeteer API 可以按原样使用
  • 不鼓励使用 ElementHandle，请改用 Locator 对象和 web-first 断言。
  • Playwright 是跨浏览器的
  • 你可能不需要显式等待

速查表​

PuppeteerPlaywright Library
await puppeteer.launch()await playwright.chromium.launch()
puppeteer.launch({product: 'firefox'})await playwright.firefox.launch()
Puppeteer 不支持 WebKitawait 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(...)通常可以使用 断言 来代替验证文本、属性、类等。
await page.$(...)不鼓励使用，请改用 定位器
await page.$x(xpath_selector)不鼓励使用，请改用 定位器
没有专用于复选框或单选框输入的方法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.route()

page.waitForNavigation 和 page.waitForSelector 仍然存在，但在许多情况下，由于 自动等待，它们不是必需的。

不鼓励使用 ElementHandle，请改用 Locator 对象和 web-first 断言。

定位器 是 Playwright 自动等待和可重试性的核心部分。定位器 是严格的。这意味着对定位器的所有操作，如果暗示某个目标 DOM 元素，并且有多个元素匹配给定的选择器，则会抛出异常。

示例​

自动化示例​

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.net.cn/', {
    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.net.cn/', {
    waitUntil: 'networkidle', // 4
  });
  await page.screenshot({ path: 'example.png' });
  await browser.close();
})();

迁移要点 (请参阅 Playwright 代码片段中的内联注释)

  1. 每个 Playwright Library 文件都显式导入了 chromium。可以使用其他浏览器 webkit 或 firefox。
  2. 对于浏览器状态隔离，请考虑 浏览器上下文
  3. setViewport 变为 setViewportSize
  4. networkidle2 变为 networkidle。请注意，在大多数情况下，由于自动等待，它并不有用。

测试示例​

Puppeteer 与 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.net.cn/');
    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 Test

import { test, expect } from '@playwright/test'; // 1

test.describe('Playwright homepage', () => {
  test('contains hero title', async ({ page }) => { // 2, 3
    await page.goto('https://playwright.net.cn/');
    const titleLocator = page.locator('.hero__title'); // 4
    await expect(titleLocator).toContainText( // 5
        'Playwright enables reliable end-to-end testing'
    );
  });
});
  1. 每个 Playwright Test 文件都显式导入了 test 和 expect 函数
  2. 测试函数用 async 标记
  3. Playwright Test 将 page 作为其参数之一。这是 Playwright Test 中众多 有用的夹具 之一。Playwright Test 为每个测试创建一个独立的 Page 对象。但是，如果您想在多个测试之间重用同一个 Page 对象，可以在 test.beforeAll() 中创建自己的，并在 test.afterAll() 中将其关闭。
  4. 使用 page.locator() 创建定位器 是少数同步方法之一。
  5. 使用 断言 来验证状态，而不是使用 page.$eval()。

测试​

为了改进测试，建议使用 定位器 和 web-first 断言。请参阅 编写测试

使用 Puppeteer 时，通常会使用 page.evaluate() 或 page.$eval() 来检查 ElementHandle 并提取文本内容、属性、类等的值。web-first 断言 为此目的提供了几个匹配器，它更可靠且更易读。

Playwright Test 是我们推荐的首选测试运行器，与 Playwright 一起使用。它提供了 Page Object Model、并行、夹具或报告器等多种功能。

Playwright Test 的超能力​

一旦你开始使用 Playwright Test，你将获得很多好处！

  • 全面的零配置 TypeScript 支持
  • 在所有 web 引擎 (Chrome, Firefox, Safari) 和任何流行的操作系统 (Windows, macOS, Ubuntu) 上运行测试
  • 完全支持多源、框架 ((i)frames)、标签页和上下文
  • 在多个浏览器上并行运行隔离的测试
  • 内置的测试 工件收集

你还将获得 Playwright Test 捆绑提供的所有这些 ✨ 超赞工具 ✨

进一步阅读​

了解更多关于 Playwright Test 运行器的信息