跳到主要内容

库模式

简介​

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 () => {
  // 初始化设置
  const browser = await chromium.launch();
  const context = await browser.newContext(devices['iPhone 11']);
  const page = await context.newPage();

  // 实际业务逻辑
  await context.route('**.jpg', route => route.abort());
  await page.goto('https://example.com/');

  assert(await page.title() === 'Example Domain'); // 👎 非 Web 优先断言

  // 清理资源
  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-webkit使用 npx 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，以及其他内置夹具。无需显式创建。如果测试在参数中引用它们，测试运行器会为测试懒初始化这些资源。
断言无内置的 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

您还需要安装浏览器 - 可以手动安装或通过添加自动安装浏览器的包来实现。

# 下载 Chromium、Firefox 和 WebKit 浏览器
npx playwright install chromium firefox webkit

# 或者，添加会在 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();
  // 创建页面，与 UI 元素交互，断言值
  await browser.close();
})();

Playwright API 是异步的，返回 Promise 对象。我们的代码示例使用 async/await 模式 来提高可读性。代码被包裹在一个自调用的匿名异步箭头函数中。

(async () => { // 异步箭头函数开始
  // 函数代码
  // ...
})(); // 函数结束并通过 () 自调用

第一个脚本​

在我们的第一个脚本中，我们将导航到 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 以无头模式运行浏览器。要查看浏览器界面，可以在启动浏览器时传入 headless: false 参数。你也可以使用 slowMo 来减慢执行速度。更多信息请参阅调试工具 章节。

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

录制脚本​

可以使用 命令行工具 来录制用户交互并生成 JavaScript 代码。

npx playwright codegen wikipedia.org

浏览器下载​

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


# 显式下载浏览器
npx playwright install

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


# 使用辅助包，在 npm install 时下载浏览器
npm install @playwright/browser-chromium

在防火墙或代理后下载

通过设置 HTTPS_PROXY 环境变量来通过代理下载。


# 手动方式
HTTPS_PROXY=https://192.0.2.1 npx playwright install


# 通过 @playwright/browser-chromium, @playwright/browser-firefox

# 和 @playwright/browser-webkit 辅助包
HTTPS_PROXY=https://192.0.2.1 npm install

从制品仓库下载

默认情况下，Playwright 会从微软的 CDN 下载浏览器。可以通过设置 PLAYWRIGHT_DOWNLOAD_HOST 环境变量来从内部制品仓库下载。


# 手动安装
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install


# 通过 @playwright/browser-chromium, @playwright/browser-firefox

# 和 @playwright/browser-webkit 辅助包安装
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm install

跳过浏览器下载

在某些情况下，可能需要完全避免浏览器下载，因为浏览器二进制文件是单独管理的。这可以通过在安装包之前设置 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD 变量来实现。


# 当使用 @playwright/browser-chromium, @playwright/browser-firefox

# 和 @playwright/browser-webkit 辅助包时
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;