库

介绍

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 运行。

关键区别

以下是 Playwright 库与 Playwright Test 的关键区别：

区别 Library(库) 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 from

playwright

@playwright/test

初始化

显式需要：

1. 选择要使用的浏览器，如 chromium 2. 使用 browserType.launch() 启动浏览器 3. 使用 browser.newContext() 创建上下文，并显式传递上下文选项，如 devices['iPhone 11'] 4. 使用 browserContext.newPage() 创建页面

每个测试都会自动提供一个隔离的 page 和 context，以及其他内置的 fixture。不需要显式创建，测试运行器会在需要时创建它们（即懒加载）。

断言

没有内置的 Web-First 断言

Web-First 断言，如：

* expect(page).toHaveTitle() * expect(page).toHaveScreenshot()

这些断言会自动等待并重试，直到条件满足。

超时

默认大多数操作超时为 30 秒

大多数操作没有超时，但每个测试有超时设置，超时后会失败（默认为 30 秒）。

清理

显式需要：

1. 使用 browserContext.close() 关闭上下文 2. 使用 browser.close() 关闭浏览器

不需要显式关闭内置的 fixture，测试运行器会负责它们的清理。

运行方式

使用 Playwright 库时，作为 Node 脚本运行，可能需要先进行编译

使用测试运行器时，使用 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，并启动任意三种浏览器（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/ 并在 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 环境变量，您可以通过代理下载浏览器。

  • 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 会从微软的 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

  • 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 中，您可以在文件顶部添加以下代码以启用类型检查：

// @ts-check
// ...

或者，您可以使用 JSDoc 来设置变量类型。

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

在 TypeScript 中

在 TypeScript 中，TypeScript 支持会自动生效。也可以显式导入类型。

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