跳到主要内容

超时设置

Playwright Test 为不同任务提供了多个可配置的超时设置。

超时类型默认值描述
测试超时30_000 毫秒每个测试的超时时间
在配置中设置
{ timeout: 60_000 }
在测试中覆盖
test.setTimeout(120_000)
断言超时5_000 毫秒每个断言语句的超时时间
在配置中设置
{ expect: { timeout: 10_000 } }
在测试中覆盖
expect(locator).toBeVisible({ timeout: 10_000 })

测试超时​

Playwright Test 为每个测试强制执行超时限制，默认为30秒。测试函数、fixture 设置和 beforeEach 钩子所花费的时间都计入测试超时。

超时的测试会产生以下错误：

example.spec.ts:3:1 › basic test ===========================

超过30000毫秒的超时限制。

在测试函数完成后，fixture 拆卸和 afterEach 钩子之间共享一个额外的独立超时，其值与测试超时相同。

相同的超时值也适用于 beforeAll 和 afterAll 钩子，但它们不与任何测试共享时间。

在配置中设置测试超时​

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  timeout: 120_000,
});

API参考: testConfig.timeout.

为单个测试设置超时​

example.spec.ts
import { test, expect } from '@playwright/test';

test('slow test', async ({ page }) => {
  test.slow(); // 简单方式将默认超时时间延长三倍
  // ...
});

test('very slow test', async ({ page }) => {
  test.setTimeout(120_000);
  // ...
});

API 参考: test.setTimeout() 和 test.slow().

通过 beforeEach 钩子修改超时​

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }, testInfo) => {
  // 为所有运行此钩子的测试延长超时30秒
  testInfo.setTimeout(testInfo.timeout + 30_000);
});

API 参考: testInfo.setTimeout().

修改 beforeAll/afterAll 钩子的超时​

beforeAll 和 afterAll 钩子有独立的超时设置，默认与测试超时相同。你可以在钩子内部调用 testInfo.setTimeout() 来单独修改每个钩子的超时。

example.spec.ts
import { test, expect } from '@playwright/test';

test.beforeAll(async () => {
  // 为此钩子设置超时
  test.setTimeout(60000);
});

API 参考: testInfo.setTimeout().

断言超时​

自动重试的断言如 expect(locator).toHaveText() 有独立的超时设置，默认为5秒。断言超时与测试超时无关。会产生如下错误：

example.spec.ts:3:1 › basic test ===========================

错误: expect(received).toHaveText(expected)

预期字符串: "my text"
实际字符串: ""
调用日志:
  - expect.toHaveText 超时5000ms
  - 等待 "locator('button')"

在配置中设置 expect 超时时间​

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  expect: {
    timeout: 10_000,
  },
});

API 参考: testConfig.expect.

为单个断言指定 expect 超时时间​

example.spec.ts
import { test, expect } from '@playwright/test';

test('example', async ({ page }) => {
  await expect(locator).toHaveText('hello', { timeout: 10_000 });
});

全局超时设置​

Playwright Test 支持为整个测试运行设置超时时间。这可以防止在出现问题时过度消耗资源。默认没有全局超时设置，但你可以在配置中设置一个合理的值，例如一小时。全局超时会产生以下错误：

使用 10 个工作线程运行 1000 个测试

  514 个跳过
  486 个通过
  整个测试运行超时，等待时间超过 3600 秒

你可以在配置中设置全局超时。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalTimeout: 3_600_000,
});

API 参考: testConfig.globalTimeout.

高级：底层超时设置​

以下是测试运行器预配置的底层超时参数，通常无需修改。如果您是因为测试不稳定而查阅本节内容，很可能应该在其他地方寻找解决方案。

超时类型默认值描述
操作超时无超时每个操作的超时限制
在配置中设置
{ use: { actionTimeout: 10_000 } }
在测试中覆盖
locator.click({ timeout: 10_000 })
导航超时无超时每个导航操作的超时限制
在配置中设置
{ use: { navigationTimeout: 30_000 } }
在测试中覆盖
page.goto('/', { timeout: 30_000 })
全局超时无超时整个测试运行的全局超时限制
在配置中设置
{ globalTimeout: 3_600_000 }
beforeAll/afterAll 超时30_000 毫秒钩子函数的超时限制
在钩子中设置
test.setTimeout(60_000)
Fixture 超时无超时单个 fixture 的超时限制
在 fixture 中设置
{ scope: 'test', timeout: 30_000 }

在配置中设置操作和导航超时​

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    actionTimeout: 10 * 1000,
    navigationTimeout: 30 * 1000,
  },
});

API 参考: testOptions.actionTimeout 和 testOptions.navigationTimeout。

为单个操作设置超时​

example.spec.ts
import { test, expect } from '@playwright/test';

test('basic test', async ({ page }) => {
  await page.goto('https://playwright.dev', { timeout: 30000 });
  await page.getByText('Get Started').click({ timeout: 10000 });
});

测试夹具超时​

默认情况下，测试夹具与测试共享相同的超时设置。但对于慢速夹具，特别是工作域范围的夹具，设置独立的超时会更方便。这样你可以保持整体测试超时较短，同时给慢速夹具更多时间。

example.spec.ts
import { test as base, expect } from '@playwright/test';

const test = base.extend<{ slowFixture: string }>({
  slowFixture: [async ({}, use) => {
    // ... 执行耗时操作 ...
    await use('hello');
  }, { timeout: 60_000 }]
});

test('example test', async ({ slowFixture }) => {
  // ...
});

API 参考: test.extend()。