程式庫

簡介

Playwright 程式庫提供用於啟動和與瀏覽器互動的統一 API，而 Playwright Test 除了提供所有這些之外，還提供完整託管的端對端測試執行器和體驗。

在大多數情況下，對於端對端測試，您會想要使用 @playwright/test (Playwright Test)，而不是直接使用 playwright (Playwright 程式庫)。若要開始使用 Playwright Test，請依照開始使用指南。

使用程式庫時的差異

程式庫範例

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

TypeScript
JavaScript

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();
})();

const assert = require('node:assert');
const { chromium, devices } = require('playwright');

(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 執行。

測試範例

達成類似行為的測試會像這樣

TypeScript
JavaScript

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

const { expect, test, devices } = require('@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 playwright`	`npm init playwright@latest` - 請注意 `install` 與 `init`
安裝瀏覽器	安裝 `@playwright/browser-chromium`、`@playwright/browser-firefox` 和/或 `@playwright/browser-webkit`	`npx playwright install` 或 `npx playwright install chromium` 以安裝單一瀏覽器
從以下位置 `import`	`playwright`	`@playwright/test`
初始化	顯式地需要選擇要使用的瀏覽器，例如 `chromium` 使用 browserType.launch() 啟動瀏覽器使用 browser.newContext() 建立內容，並顯式地傳遞任何內容選項，例如 `devices['iPhone 11']` 使用 browserContext.newPage() 建立頁面	每個測試都會提供隔離的 `page` 和 `context`，以及其他內建 fixtures。無需顯式建立。如果測試在其引數中引用了它們，測試執行器將會為測試建立它們。(即延遲初始化)
斷言	沒有內建的 Web-First 斷言	Web-First 斷言，例如 expect(page).toHaveTitle() expect(page).toHaveScreenshot() 會自動等待和重試，直到條件滿足。
逾時	大多數操作預設為 30 秒。	大多數操作不會逾時，但每個測試都有一個逾時時間，使其失敗 (預設為 30 秒)。
清除	顯式地需要使用 browserContext.close() 關閉內容使用 browser.close() 關閉瀏覽器	無需顯式關閉內建 fixtures；測試執行器會處理它。
執行	當使用程式庫時，您可以將程式碼作為節點腳本執行，可能需要先進行一些編譯。	當使用測試執行器時，您可以使用 `npx playwright test` 命令。連同您的設定，測試執行器會處理任何編譯，並選擇要執行什麼以及如何執行。

除了以上之外，Playwright Test 作為功能完整的測試執行器，還包括

設定矩陣和專案：在上述範例中，在 Playwright 程式庫版本中，如果我們想要使用不同的裝置或瀏覽器執行，我們必須修改腳本並貫穿資訊。使用 Playwright Test，我們只需在一個地方指定設定矩陣，它就會在每個設定下建立並執行一個測試。
平行化
Web-First 斷言
報告
重試
輕鬆啟用的追蹤
以及更多…

用法

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

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 API 是非同步的，並傳回 Promise 物件。我們的程式碼範例使用 async/await 模式以簡化可讀性。程式碼包裝在呼叫自身的不具名 async 箭頭函式中。

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

第一個腳本

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

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

(async () => {
  const browser = await webkit.launch();
  const page = await browser.newPage();
  await page.goto('https://playwright.dev.org.tw/');
  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

透過防火牆或 Proxy 下載

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

Bash
PowerShell
Batch

# 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

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

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

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

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

從成品儲存庫下載

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

Bash
PowerShell
Batch

# 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

# Manual
$Env:PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
npx playwright install

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

# Manual
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
npx playwright install

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

略過瀏覽器下載

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

Bash
PowerShell
Batch

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

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

# When using @playwright/browser-chromium, @playwright/browser-firefox
# and @playwright/browser-webkit helper packages
set 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;

簡介​

使用程式庫時的差異​

程式庫範例​

測試範例​

主要差異​

用法​

第一個腳本​

錄製腳本​

瀏覽器下載​

TypeScript 支援​

在 JavaScript 中​

在 TypeScript 中​

簡介