库

介绍

🌐 Introduction

Playwright Library 提供用于启动浏览器并与浏览器交互的统一 API，而 Playwright Test 则提供所有这些以及完全托管的端到端测试运行程序和体验。

🌐 Playwright Library provides unified APIs for launching and interacting with browsers, while Playwright Test provides all this plus a fully managed end-to-end Test Runner and experience.

在大多数情况下，对于端到端测试，你会想使用 @playwright/test（Playwright Test），而不是直接使用 playwright（Playwright Library）。要开始使用 Playwright Test，请参阅入门指南。

🌐 Under most circumstances, for end-to-end testing, you'll want to use @playwright/test (Playwright Test), and not playwright (Playwright Library) directly. To get started with Playwright Test, follow the Getting Started Guide.

使用库时的差异

🌐 Differences when using library

库示例

🌐 Library Example

以下是直接使用 Playwright Library 启动 Chromium、转到页面并检查其标题的示例：

🌐 The following is an example of using the Playwright Library directly to launch Chromium, go to a page, and check its title:

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

🌐 Run it with node my-script.js.

测试实例

🌐 Test Example

实现类似行为的测试如下所示：

🌐 A test to achieve similar behavior, would look like:

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

🌐 Run it with npx playwright test.

主要差异

🌐 Key Differences

需要注意的主要区别如下：

🌐 The key differences to note are as follows:

	Library	Test
Installation	`npm install playwright`	`npm init playwright@latest` - note `install` vs. `init`
Install browsers	Install `@playwright/browser-chromium`, `@playwright/browser-firefox` and/or `@playwright/browser-webkit`	`npx playwright install` or `npx playwright install chromium` for a single one
`import` from	`playwright`	`@playwright/test`
Initialization	Explicitly need to: Pick a browser to use, e.g. `chromium` Launch browser with browserType.launch() Create a context with browser.newContext(), and pass any context options explicitly, e.g. `devices['iPhone 11']` Create a page with browserContext.newPage()	An isolated `page` and `context` are provided to each test out-of the box, along with other built-in fixtures. No explicit creation. If referenced by the test in its arguments, the Test Runner will create them for the test. (i.e. lazy-initialization)
Assertions	No built-in Web-First Assertions	Web-First assertions like: expect(page).toHaveTitle() expect(page).toHaveScreenshot() which auto-wait and retry for the condition to be met.
Timeouts	Defaults to 30s for most operations.	Most operations don't time out, but every test has a timeout that makes it fail (30s by default).
Cleanup	Explicitly need to: Close context with browserContext.close() Close browser with browser.close()	No explicit close of built-in fixtures; the Test Runner will take care of it.
Running	When using the Library, you run the code as a node script, possibly with some compilation first.	When using the Test Runner, you use the `npx playwright test` command. Along with your config, the Test Runner handles any compilation and choosing what to run and how to run it.

除上述内容外，Playwright Test 作为一个功能齐全的测试运行程序，还包括：

🌐 In addition to the above, Playwright Test, as a full-featured Test Runner, includes:

配置矩阵和项目：在上述示例中，在 Playwright 库版本中，如果我们想使用不同的设备或浏览器运行测试，就必须修改脚本并传递相关信息。而使用 Playwright Test，我们只需在一个地方指定配置矩阵矩阵配置，它就会在每种配置下运行相同的测试。
Parallelization
以网络为先的断言
Reporting
Retries
轻松启用追踪
和更多…

用法

🌐 Usage

在你的 Node.js 项目中使用 npm 或 Yarn 安装 Playwright 库。请参见系统要求。

🌐 Use npm or Yarn to install Playwright library in your Node.js project. See system requirements.

npm i -D playwright

你还需要安装浏览器——可以手动安装，也可以通过添加一个自动为你安装的包来完成。

🌐 You will also need to install browsers - either manually or by adding a package that will do it for you automatically.

# 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

有关更多选项，请参阅管理浏览器。

🌐 See managing browsers for more options.

安装完成后，你可以在 Node.js 脚本中导入 Playwright，并启动任意三种浏览器（chromium、firefox 和 webkit）。

🌐 Once installed, you can import Playwright in a Node.js script, and launch any of the 3 browsers (chromium, firefox and 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 模式来提高可读性。代码被封装在一个匿名的异步箭头函数中，并且该函数会自我调用。

🌐 Playwright APIs are asynchronous and return Promise objects. Our code examples use the async/await pattern to ease readability. The code is wrapped in an unnamed async arrow function which is invoking itself.

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

第一个脚本

🌐 First script

在我们的第一个脚本中，我们将导航到 https://playwright.nodejs.cn/ 并在 WebKit 中截取屏幕截图。

🌐 In our first script, we will navigate to https://playwright.nodejs.cn/ and take a screenshot in WebKit.

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

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

默认情况下，Playwright 会以无头模式运行浏览器。要查看浏览器界面，请在启动浏览器时传入 headless: false 标志。你也可以使用 slowMo 来减慢执行速度。更多信息请参阅调试工具部分。

🌐 By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the headless: false flag while launching the browser. You can also use slowMo to slow down execution. Learn more in the debugging tools section.

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

录制脚本

🌐 Record scripts

命令行工具可用于记录用户交互并生成 JavaScript 代码。

npx playwright codegen wikipedia.org

浏览器下载

🌐 Browser downloads

要下载 Playwright 浏览器，请运行：

🌐 To download Playwright browsers run:

# Explicitly download browsers
npx playwright install

或者，你可以添加 @playwright/browser-chromium、@playwright/browser-firefox 和 @playwright/browser-webkit 包，在安装这些包时自动下载相应的浏览器。

🌐 Alternatively, you can add @playwright/browser-chromium, @playwright/browser-firefox and @playwright/browser-webkit packages to automatically download the respective browser during the package installation.

# Use a helper package that downloads a browser on npm install
npm install @playwright/browser-chromium

在防火墙或代理后下载

通过 HTTPS_PROXY 环境变量通过代理进行下载。

🌐 Pass HTTPS_PROXY environment variable to download through a 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 环境变量即可改为从内部资源仓库下载。

🌐 By default, Playwright downloads browsers from Microsoft's CDN. Pass PLAYWRIGHT_DOWNLOAD_HOST environment variable to download from an internal artifacts repository instead.

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 变量来实现。

🌐 In certain cases, it is desired to avoid browser downloads altogether because browser binaries are managed separately. This can be done by setting PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD variable before installing packages.

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 支持

🌐 TypeScript support

Playwright 内置支持 TypeScript。类型定义将会自动导入。建议使用类型检查以改善 IDE 的使用体验。

🌐 Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.

在 JavaScript 中

🌐 In JavaScript

将以下内容添加到 JavaScript 文件的顶部，以在 VS Code 或 WebStorm 中进行类型检查。

🌐 Add the following to the top of your JavaScript file to get type-checking in VS Code or WebStorm.

// @ts-check
// ...

或者，你可以使用 JSDoc 设置变量的类型。

🌐 Alternatively, you can use JSDoc to set types for variables.

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

在 TypeScript 中

🌐 In TypeScript

TypeScript 支持将开箱即用。类型也可以显式导入。

🌐 TypeScript support will work out-of-the-box. Types can also be imported explicitly.

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

介绍​

使用库时的差异​

库示例​

测试实例​

主要差异​

用法​

第一个脚本​

录制脚本​

浏览器下载​

TypeScript 支持​

在 JavaScript 中​

在 TypeScript 中​

介绍