Skip to main content

程式庫

簡介​

Playwright Library 提供統一的 API 來啟動和與瀏覽器互動，而 Playwright Test 則提供所有這些功能，再加上完全託管的端對端測試執行器和體驗。

在大多數情況下，對於端對端測試，您會想要使用 @playwright/test（Playwright Test），而不是直接使用 playwright（Playwright Library）。要開始使用 Playwright Test，請遵循入門指南。

使用程式庫時的差異​

程式庫範例​

以下是直接使用 Playwright Library 來啟動 Chromium、前往頁面並檢查其標題的範例：

import { chromium, devices } from 'playwright';
import assert from 'node:assert';

(async () => {
  // 設定
  const browser = await chromium.launch();
  const context = await browser.newContext(devices['iPhone 11']);
  const page = await context.newPage();

  // 實際有趣的部分
  await context.route('**.jpg', route => route.abort());
  await page.goto('https://example.com/');

  assert(await page.title() === 'Example Domain'); // 👎 不是網頁優先斷言

  // 清理
  await context.close();
  await browser.close();
})();

使用 node my-script.js 執行它。

測試範例​

要實現類似行為的測試，看起來會像：

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

test.use(devices['iPhone 11']);

test('should be titled', async ({ page, context }) => {
  await context.route('**.jpg', route => route.abort());
  await page.goto('https://example.com/');

  await expect(page).toHaveTitle('Example');
});

Run it with npx playwright test.

主要差異​

需要注意的主要差異如下：

程式庫測試
安裝npm install playwrightnpm init playwright@latest - 注意 install 與 init 的差別
安裝瀏覽器安裝 @playwright/browser-chromium、@playwright/browser-firefox 和/或 @playwright/browser-webkitnpx playwright install 或 npx playwright install chromium 用於單一瀏覽器
import 來源playwright@playwright/test
初始化明確需要：
  1. 選擇要使用的瀏覽器，例如 chromium
  2. 使用 browserType.launch() 啟動瀏覽器
  3. 使用 browser.newContext() 建立情境，並且明確傳遞任何情境選項，例如 devices['iPhone 11']
  4. 使用 browserContext.newPage() 建立頁面
為每個測試開箱即用地提供隔離的 page 和 context，以及其他內建佈置。無需明確建立。如果測試在其參數中引用它們，測試執行器將為測試建立它們。（即懶惰初始化）
斷言沒有內建的網頁優先斷言網頁優先斷言，例如：這些會自動等待並重試，直到滿足條件。
逾時大多數操作預設為 30 秒。大多數操作不會逾時，但每個測試都有一個逾時時間，使其失敗（預設為 30 秒）。
清理明確需要：
  1. 使用 browserContext.close() 關閉情境
  2. 使用 browser.close() 關閉瀏覽器
無需明確關閉內建佈置；測試執行器會處理它。
執行使用程式庫時，您將程式碼作為 Node 腳本執行，可能首先進行一些編譯。使用測試執行器時，您使用 npx playwright test 命令。連同您的組態設定，測試執行器處理任何編譯以及選擇執行什麼和如何執行。

除了上述內容之外，Playwright Test 作為功能齊全的測試執行器，包括：

使用方式​

使用 npm 或 Yarn 在您的 Node.js 專案中安裝 Playwright 程式庫。請參閱系統需求。

npm i -D playwright

您還需要安裝瀏覽器 - 手動安裝或新增會自動為您執行此操作的套件。

# 下載 Chromium、Firefox 和 WebKit 瀏覽器
npx playwright install chromium firefox webkit

# 或者，新增會在 npm install 時下載瀏覽器的套件
npm i -D @playwright/browser-chromium @playwright/browser-firefox @playwright/browser-webkit

更多選項請參閱管理瀏覽器。

安裝後，您可以在 Node.js 腳本中匯入 Playwright，並啟動 3 種瀏覽器中的任何一種（chromium、firefox 和 webkit）。

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  // 建立頁面、與 UI 元素互動、斷言值
  await browser.close();
})();

Playwright API 是非同步的並返回 Promise 物件。我們的程式碼範例使用 async/await 模式來提高可讀性。程式碼包裝在一個未命名的非同步箭頭函式中，該函式正在調用自身。

(async () => { // 非同步箭頭函式的開始
  // 函式程式碼
  // ...
})(); // 函式的結束和 () 來調用自身

第一個腳本​

在我們的第一個腳本中，我們將導航到 https://playwright.dev/ 並在 WebKit 中截取螢幕截圖。

const { webkit } = require('playwright');

(async () => {
  const browser = await webkit.launch();
  const page = await browser.newPage();
  await page.goto('https://playwright.dev/');
  await page.screenshot({ path: `example.png` });
  await browser.close();
})();

預設情況下，Playwright 在無頭模式下執行瀏覽器。要查看瀏覽器 UI，請在啟動瀏覽器時傳遞 headless: false 標誌。您也可以使用 slowMo 來減慢執行速度。在偵錯工具章節中了解更多。

firefox.launch({ headless: false, slowMo: 50 });

錄製腳本​

命令列工具可用於錄製使用者互動並產生 JavaScript 程式碼。

npx playwright codegen wikipedia.org

瀏覽器下載​

要下載 Playwright 瀏覽器，請執行：

# 明確下載瀏覽器
npx playwright install

或者，您可以新增 @playwright/browser-chromium、@playwright/browser-firefox 和 @playwright/browser-webkit 套件，以在套件安裝期間自動下載相應的瀏覽器。

# 使用在 npm install 時下載瀏覽器的輔助套件
npm install @playwright/browser-chromium

在防火牆或代理後面下載

傳遞 HTTPS_PROXY 環境變數以透過代理下載。

# Manual
HTTPS_PROXY=https://192.0.2.1 npx playwright install

# Through @playwright/browser-chromium, @playwright/browser-firefox
# and @playwright/browser-webkit helper packages
HTTPS_PROXY=https://192.0.2.1 npm install

從構件倉庫下載

預設情況下，Playwright 從 Microsoft 的 CDN 下載瀏覽器。傳遞 PLAYWRIGHT_DOWNLOAD_HOST 環境變數以改為從內部構件倉庫下載。

# Manual
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install

# Through @playwright/browser-chromium, @playwright/browser-firefox
# and @playwright/browser-webkit helper packages
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install

跳過瀏覽器下載

在某些情況下，希望完全避免瀏覽器下載，因為瀏覽器二進位檔案是單獨管理的。這可以透過在安裝套件之前設定 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 變數來完成。

# When using @playwright/browser-chromium, @playwright/browser-firefox
# and @playwright/browser-webkit helper packages
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install

TypeScript 支援​

Playwright 包含內建的 TypeScript 支援。類型定義將自動匯入。建議使用類型檢查來改善 IDE 體驗。

在 JavaScript 中​

在您的 JavaScript 檔案頂部新增以下內容，以在 VS Code 或 WebStorm 中獲得類型檢查。

// @ts-check
// ...

或者，您可以使用 JSDoc 為變數設定類型。

/** @type {import('playwright').Page} */
let page;

在 TypeScript 中​

TypeScript 支援將開箱即用。類型也可以明確匯入。

let page: import('playwright').Page;