Skip to main content

函式庫

簡介​

Playwright 函式庫提供了啟動和互動瀏覽器的統一 API，而 Playwright Test 提供了所有這些功能，外加一個完全管理的端到端測試執行器和體驗。

在大多數情況下，對於端到端測試，你會想要使用 @playwright/test (Playwright Test)，而不是直接使用 playwright (Playwright 函式庫)。要開始使用 Playwright Test，請遵循 入門指南。

使用函式庫時的差異​

函式庫範例​

以下是一個直接使用 Playwright 函式庫來啟動 Chromium、進入頁面並檢查其標題的範例:

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

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

  // The actual interesting bit
  await context.route('**.jpg', route => route.abort());
  await page.goto('https://example.com/');

  assert(await page.title() === 'Example Domain'); // 👎 not a Web First assertion

  // Teardown
  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');
});

使用 npx playwright test 執行。

主要差異​

請注意以下主要差異：

函式庫測試
安裝npm install playwrightnpm init playwright@latest - 注意 install vs. 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() 建立一個 context，並且 明確傳遞任何 context 選項，例如 devices['iPhone 11']
  4. 使用 browserContext.newPage() 建立一個 page
每個測試會自動提供一個獨立的 page 和 context，以及其他 內建 fixtures。不需要明確建立。如果在測試的參數中引用，測試執行器會為測試建立它們。(即懶初始化)
斷言沒有內建的 Web-First 斷言Web-First 斷言 如: 會自動等待並重試以滿足條件。
清理明確需要:
  1. 使用 browserContext.close() 關閉 context
  2. 使用 browser.close() 關閉瀏覽器
不需要明確關閉 內建 fixtures; 測試執行器會處理。
執行使用函式庫時，你會將程式碼作為 node 腳本執行，可能需要先進行一些編譯。使用測試執行器時，你會使用 npx playwright test 命令。配合你的 配置，測試執行器會處理任何編譯並選擇執行什麼以及如何執行。

除了上述內容外，Playwright Test 作為一個全功能的測試執行器，還包括:

使用方式​

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

npm i -D playwright

您還需要安裝瀏覽器 - 可以手動安裝，也可以添加一個套件來自動完成。

# Download the Chromium, Firefox and WebKit browser
npx playwright install chromium firefox webkit

# Alternatively, add packages that will download a browser upon 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();
  // Create pages, interact with UI elements, assert values
  await browser.close();
})();

Playwright APIs 是非同步的並返回 Promise 物件。我們的程式碼範例使用async/await 模式來提高可讀性。程式碼包裹在一個匿名的非同步箭頭函式中，並且呼叫自身。

(async () => { // Start of async arrow function
  // Function code
  // ...
})(); // End of the function and () to invoke itself

第一個腳本​

在我們的第一個程式碼中，我們將導航到 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 瀏覽器，請執行:

# Explicitly download browsers
npx playwright install

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

# Use a helper package that downloads a browser on 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

從 artifact repository 下載

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

# 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;