库
介绍
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
运行它。
主要区别
需要注意的主要区别如下
库 | 测试 | |
---|---|---|
安装 | 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 | playwright | @playwright/test |
初始化 | 需要明确地
| 为每个测试提供了开箱即用的独立的 page 和 context ,以及其他内置夹具。无需显式创建。如果在测试的参数中引用了它们,测试运行器将为测试创建它们。(即,惰性初始化) |
断言 | 没有内置的 Web-First 断言 | 例如Web-First 断言它们会自动等待并重试直到条件满足。 |
超时 | 大多数操作默认为 30 秒。 | 大多数操作不会超时,但每个测试都有一个使其失败的超时时间(默认为 30 秒)。 |
清理 | 需要明确地
| 无需显式关闭内置夹具;测试运行器会处理好。 |
运行 | 使用库时,您将代码作为 Node 脚本运行,可能需要先进行一些编译。 | 使用测试运行器时,您使用 npx playwright test 命令。结合您的配置,测试运行器会处理任何编译以及选择运行什么和如何运行它。 |
除上述内容外,Playwright Test 作为功能齐全的测试运行器,还包括
- 配置矩阵和项目:在上面的 Playwright 库示例中,如果我们想使用不同的设备或浏览器运行,必须修改脚本并传递信息。使用 Playwright Test,我们可以在一个地方指定配置矩阵,它将为每种配置运行一次该测试。
- 并行化
- Web-First 断言
- 报告
- 重试
- 轻松启用跟踪
- 等等…
用法
在您的 Node.js 项目中使用 npm 或 Yarn 安装 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
环境变量以通过代理下载。
- 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
从 Artifact 仓库下载
默认情况下,Playwright 从 Microsoft 的 CDN 下载浏览器。传递 PLAYWRIGHT_DOWNLOAD_HOST
环境变量以从内部 Artifact 仓库下载。
- 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 文件的顶部,以便在 VS Code 或 WebStorm 中获得类型检查。
// @ts-check
// ...
或者,您可以使用 JSDoc 为变量设置类型。
/** @type {import('playwright').Page} */
let page;
在 TypeScript 中
TypeScript 支持将开箱即用。类型也可以显式导入。
let page: import('playwright').Page;