Skip to main content

從 Puppeteer 遷移

遷移原則​

本指南說明如何從 Puppeteer 遷移到 Playwright Library 和 Playwright Test。這些 API 有相似之處，但 Playwright 為 Web 測試和跨瀏覽器自動化提供了更多可能性。

  • 大多數 Puppeteer API 都可以照常使用
  • 不建議使用 ElementHandle，請使用 Locator 物件和 Web 優先斷言
  • Playwright 支援跨瀏覽器
  • 您可能不需要明確等待

對照表​

PuppeteerPlaywright Library
await puppeteer.launch()await playwright.chromium.launch()
puppeteer.launch({product: 'firefox'})await playwright.firefox.launch()
WebKit 未受 Puppeteer 支援await 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 優先斷言。

定位器是 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.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 程式碼片段中的內嵌註釋）：

  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.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 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.dev/');
    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 優先斷言。請參閱撰寫測試

在 Puppeteer 中，常見的做法是使用 page.evaluate() 或 page.$eval() 來檢查 ElementHandle 並提取文字內容、屬性、類別...的值。Web 優先斷言為此目的提供了幾個比對器，它更可靠且可讀性更高。

Playwright Test 是我們第一方推薦的測試執行器，與 Playwright 搭配使用。它提供了幾個功能，如頁面物件模型、平行處理、佈置或報告器。

Playwright Test 超能力​

一旦您使用 Playwright Test，您會獲得很多！

  • 完整的零組態設定 TypeScript 支援
  • 在任何流行的作業系統（Windows、macOS、Ubuntu）上跨所有 Web 引擎（Chrome、Firefox、Safari）執行測試
  • 完整支援多個來源、(i)frames、分頁和情境
  • 在多個瀏覽器中平行隔離執行測試
  • 內建測試記錄收集

您還會獲得所有這些 ✨ 很棒的工具 ✨，這些工具與 Playwright Test 一起捆綁提供：

延伸閱讀​

了解更多關於 Playwright Test 執行器：