编写测试

简介

Playwright 测试很简单：它们 执行操作，并使用 断言来验证状态 是否符合预期。

Playwright 在执行每个操作之前，都会自动等待可操作性检查（actionability checks）通过。您无需添加手动等待或处理竞态条件（race conditions）。Playwright 的断言旨在描述最终会被满足的预期，从而消除了不稳定的超时（flaky timeouts）和多变的检查（racy checks）。

你将学到

• 如何编写第一个测试
• 如何执行操作
• 如何使用断言
• 测试如何在隔离环境中运行
• 如何使用测试钩子

第一个测试

请看下面的示例，了解如何编写测试。

tests/example.spec.ts

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

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Click the get started link.
  await page.getByRole('link', { name: 'Get started' }).click();

  // Expects page to have a heading with the name of Installation.
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Note

在 VS Code 中使用 JavaScript 时，在每个测试文件的开头添加 // @ts-check 以获取自动类型检查。

操作（Actions）

导航（Navigation）

大多数测试都从导航到某个 URL 开始。之后，测试会与页面元素进行交互。

await page.goto('https://playwright.dev/');

Playwright 会在继续执行之前等待页面达到加载状态（load state）。了解更多关于 page.goto() 的选项。

交互（Interactions）

执行操作始于定位元素。Playwright 为此使用了定位器（Locators）API。定位器代表了在任何时刻于页面上查找元素的方法。了解更多关于各种可用定位器类型的信息。

Playwright 会在执行操作之前等待元素达到可操作（actionable）状态，因此您无需等待其变得可用。

// 创建一个定位器。
const getStarted = page.getByRole('link', { name: 'Get started' });

// 点击它。
await getStarted.click();

在大多数情况下，它会被写成单行形式：

await page.getByRole('link', { name: 'Get started' }).click();

基础操作

以下是最常用的 Playwright 操作。有关完整列表，请查看 Locator API 部分。

操作	描述
locator.check()	勾选输入的复选框
locator.click()	点击元素
locator.uncheck()	取消勾选输入的复选框
locator.hover()	将鼠标悬停在元素上
locator.fill()	填充表单字段，输入文本
locator.focus()	聚焦元素
locator.press()	按下单个按键
locator.setInputFiles()	选择要上传的文件
locator.selectOption()	在下拉菜单中选择选项

断言（Assertions）

Playwright 以 expect 函数的形式包含测试断言。要进行断言，请调用 expect(value) 并选择一个反映预期的匹配器（matcher）。

Playwright 包含异步匹配器，它们会等待直到满足预期条件。使用这些匹配器可以使测试保持稳定且具有弹性。例如，以下代码会等待直到页面的标题包含 “Playwright”：

await expect(page).toHaveTitle(/Playwright/);

以下是最常用的异步断言。有关完整列表，请参阅 断言指南：

断言	描述
expect(locator).toBeChecked()	复选框已被勾选
expect(locator).toBeEnabled()	控件已启用
expect(locator).toBeVisible()	元素可见
expect(locator).toContainText()	元素包含文本
expect(locator).toHaveAttribute()	元素拥有属性
expect(locator).toHaveCount()	元素列表具有给定长度
expect(locator).toHaveText()	元素匹配文本
expect(locator).toHaveValue()	输入框元素拥有特定值
expect(page).toHaveTitle()	页面拥有特定标题
expect(page).toHaveURL()	页面拥有特定 URL

Playwright 还包含通用匹配器，例如 toEqual、toContain、toBeTruthy，它们可用于断言任何条件。这些断言不使用 await 关键字，因为它们对已经可用的值执行即时同步检查。

expect(success).toBeTruthy();

测试隔离（Test Isolation）

Playwright Test 基于测试夹具（test fixtures）的概念，例如内置的 page 夹具，它会被传递到您的测试中。由于浏览器上下文（Browser Context）的存在，页面在测试之间是相互隔离的，这相当于一个全新的浏览器配置文件。即使在单个浏览器中运行多个测试，每个测试也会获得一个干净的环境。

tests/example.spec.ts

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

test('example test', async ({ page }) => {
  // "page" 属于一个隔离的 BrowserContext，专门为该测试创建。
});

test('another test', async ({ page }) => {
  // 第二个测试中的 "page" 与第一个测试完全隔离。
});

使用测试钩子（Using Test Hooks）

您可以使用各种 测试钩子，例如用于声明测试组的 test.describe，以及在每个测试之前/之后执行的 test.beforeEach 和 test.afterEach。其他钩子还包括 test.beforeAll 和 test.afterAll，它们在所有测试之前/之后在每个 worker 中执行一次。

tests/example.spec.ts

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

test.describe('navigation', () => {
  test.beforeEach(async ({ page }) => {
    // 在每个测试之前导航到初始 URL。
    await page.goto('https://playwright.dev/');
  });

  test('main navigation', async ({ page }) => {
    // 断言使用 expect API。
    await expect(page).toHaveURL('https://playwright.dev/');
  });
});

下一步做什么

• 运行单个测试、多个测试、有头模式
• 使用 Codegen 生成测试
• 查看测试的跟踪（trace）
• 探索 UI 模式
• 在 CI 上使用 GitHub Actions 运行测试