🎭 Playwright

文档 | API 参考

Playwright 是一个用于 Web 测试和自动化的框架。它允许使用单一 API 测试 Chromium、Firefox 和 WebKit。Playwright 旨在实现常青、强大、可靠且快速的跨浏览器 Web 自动化。

	Linux	macOS	Windows
Chromium 143.0.7499.25	:white_check_mark:	:white_check_mark:	:white_check_mark:
WebKit 26.0	:white_check_mark:	:white_check_mark:	:white_check_mark:
Firefox 144.0.2	:white_check_mark:	:white_check_mark:	:white_check_mark:

所有平台上的所有浏览器都支持无头执行。查看系统要求了解详情。

寻找 Playwright 的 Python、.NET 或 Java 版本？

安装

Playwright 拥有自己的端到端测试运行器，我们称之为 Playwright Test。

使用 init 命令

开始使用 Playwright Test 的最简单方法是运行 init 命令。

# 从项目的根目录运行
npm init playwright@latest
# 或创建一个新项目
npm init playwright@latest new-project

这将创建一个配置文件，可选择添加示例、GitHub Action 工作流和第一个测试示例 example.spec.ts。您现在可以直接跳转到编写断言部分。

手动安装

添加依赖并安装浏览器。

npm i -D @playwright/test
# 安装支持的浏览器
npx playwright install

您可以选择仅安装部分浏览器，有关更多详细信息，请参阅安装浏览器。或者您也可以完全不安装浏览器，而是使用现有的浏览器渠道。

• 入门指南
• API 参考

功能特性

弹性可靠 • 无不稳定测试

自动等待。Playwright 在执行操作之前会等待元素可操作。它还拥有丰富的内省事件。这两者的结合消除了对人为设置超时的需求——这是导致测试不稳定的主要原因。

Web 优先的断言。Playwright 断言是专为动态 Web 内容创建的。检查会自动重试，直到满足必要条件。

追踪。配置测试重试策略，捕获执行追踪、视频和屏幕截图，以消除不稳定因素。

无需妥协 • 没有限制

浏览器在不同进程中运行属于不同来源的 Web 内容。Playwright 与现代浏览器的架构保持一致，并在进程外运行测试。这使得 Playwright 摆脱了典型的进程内测试运行器的限制。

多重一切。测试跨越多个标签页、多个来源和多个用户的场景。为不同用户创建具有不同上下文的场景，并在一个测试中针对您的服务器运行它们。

可信事件。悬停元素、与动态控件交互并产生可信事件。Playwright 使用真实的浏览器输入管道，与真实用户的操作无法区分。

测试帧，穿透 Shadow DOM。Playwright 选择器可以穿透 Shadow DOM 并无缝进入帧。

完全隔离 • 快速执行

浏览器上下文。Playwright 为每个测试创建一个浏览器上下文。浏览器上下文相当于一个全新的浏览器配置文件。这以零开销实现了完整的测试隔离。创建新的浏览器上下文只需几毫秒。

一次登录。保存上下文的认证状态并在所有测试中重复使用。这避免了在每个测试中重复执行登录操作，同时实现了独立测试的完全隔离。

强大的工具

代码生成。通过记录您的操作来生成测试。将其保存为任何语言。

Playwright 检查器。检查页面、生成选择器、逐步执行测试、查看点击点并探索执行日志。

追踪查看器。捕获所有信息以调查测试失败。Playwright 追踪包含测试执行屏幕录像、实时 DOM 快照、操作浏览器、测试源代码等等。

寻找 Playwright 的 TypeScript、JavaScript、Python、.NET 或 Java 版本？

示例

要了解如何运行这些 Playwright Test 示例，请查看我们的入门文档。

页面截图

此代码片段导航到 Playwright 主页并保存截图。

import { test } from '@playwright/test';

test('Page Screenshot', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.screenshot({ path: `example.png` });
});

移动设备和地理位置

此片段模拟给定地理位置设备上的 Mobile Safari，导航到 maps.google.com，执行操作并截图。

import { test, devices } from '@playwright/test';

test.use({
  ...devices['iPhone 13 Pro'],
  locale: 'en-US',
  geolocation: { longitude: 12.492507, latitude: 41.889938 },
  permissions: ['geolocation'],
})

test('Mobile and geolocation', async ({ page }) => {
  await page.goto('https://maps.google.com');
  await page.getByText('Your location').click();
  await page.waitForRequest(/.*preview\/pwa/);
  await page.screenshot({ path: 'colosseum-iphone.png' });
});

在浏览器上下文中执行代码

此代码片段导航到 example.com，并在页面上下文中执行脚本。

import { test } from '@playwright/test';

test('Evaluate in browser context', async ({ page }) => {
  await page.goto('https://www.example.com/');
  const dimensions = await page.evaluate(() => {
    return {
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
      deviceScaleFactor: window.devicePixelRatio
    }
  });
  console.log(dimensions);
});

拦截网络请求

此代码片段为页面设置请求路由以记录所有网络请求。

import { test } from '@playwright/test';

test('Intercept network requests', async ({ page }) => {
  // 记录并继续所有网络请求
  await page.route('**', route => {
    console.log(route.request().url());
    route.continue();
  });
  await page.goto('http://todomvc.com');
});

资源

• 文档
• API 参考
• 贡献指南
• 更新日志