跳转到主要内容

库

简介​

Playwright Library（Playwright 库）提供了用于启动和与浏览器交互的统一 API，而 Playwright Test 不仅包含上述所有功能，还提供了一个完全托管的端到端测试运行器（Test Runner）及相关体验。

在大多数情况下，对于端到端测试，你应当使用 @playwright/test (Playwright Test)，而不是直接使用 playwright (Playwright Library)。若要开始使用 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 与 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，以及其他内置固件（fixtures）。无需显式创建。如果测试参数中引用了它们，测试运行器将自动为测试创建它们。（即惰性初始化）
断言无内置的 Web-First 断言诸如以下之类的Web-First 断言它们会自动等待并重试，直到满足条件。
超时大多数操作默认为 30 秒。大多数操作不会超时，但每个测试都有一个导致失败的超时时间（默认为 30 秒）。
清理需要显式地
  1. 使用 browserContext.close() 关闭上下文
  2. 使用 browser.close() 关闭浏览器
无需显式关闭内置固件；测试运行器会处理它。
运行使用库时，你将代码作为 node 脚本运行，可能需要先进行一些编译。使用测试运行器时，你使用 npx playwright test 命令。结合你的配置，测试运行器会处理编译、选择运行内容以及运行方式。

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

用法​

使用 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.net.cn/ 并在 WebKit 中截取屏幕。

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

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

从制品库下载

默认情况下，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;