跳转到主要内容

库

简介​

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 与 init 的区别
安装浏览器安装 @playwright/browser-chromium, @playwright/browser-firefox 和/或 @playwright/browser-webkitnpx playwright install 或 npx playwright install chromium （用于单个浏览器）
从 ... 导入playwright@playwright/test
初始化明确需要
  1. 选择一个要使用的浏览器，例如 chromium
  2. 使用 browserType.launch() 启动浏览器
  3. 使用 browser.newContext() 创建一个上下文，并明确传递任何上下文选项，例如 devices['iPhone 11']
  4. 使用 browserContext.newPage() 创建一个页面
每个测试开箱即用地提供一个隔离的 page 和 context，以及其他 内置的 fixture。无需显式创建。如果测试在参数中引用它们，测试运行器将为该测试创建它们。（即延迟初始化）
断言没有内置的 Web-First 断言像这样的 Web-First 断言这些会自动等待并重试直到条件满足。
超时大多数操作默认为 30 秒。大多数操作不会超时，但每个测试都有一个使其失败的超时时间（默认为 30 秒）。
清理明确需要
  1. 使用 browserContext.close() 关闭上下文
  2. 使用 browser.close() 关闭浏览器
无需显式关闭 内置 fixture；测试运行器将负责处理。
运行当使用库时，您将代码作为一个 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 () => { // 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;