超时

Playwright Test 对于各种任务有多个可配置的超时。

🌐 Playwright Test has multiple configurable timeouts for various tasks.

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

测试超时

🌐 Test timeout

Playwright 测试会对每个测试强制设定超时时间，默认是 30 秒。测试函数、测试夹具设置以及 beforeEach 钩子所花费的时间都计入测试超时时间。

🌐 Playwright Test enforces a timeout for each test, 30 seconds by default. Time spent by the test function, fixture setups, and beforeEach hooks is included in the test timeout.

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

🌐 Timed out test produces the following error:

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

Timeout of 30000ms exceeded.

测试功能结束后，夹具拆解和“afterEach”钩之间共享相同值的额外超时。

🌐 Additional separate timeout, of the same value, is shared between fixture teardowns and afterEach hooks, after the test function has finished.

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

🌐 The same timeout value also applies to beforeAll and afterAll hooks, but they do not share time with any test.

在配置中设置测试超时

🌐 Set test timeout in the config

playwright.config.ts

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

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

API参考：testConfig.timeout。

🌐 API reference: testConfig.timeout.

设置单个测试的超时时间

🌐 Set timeout for a single test

example.spec.ts

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

test('slow test', async ({ page }) => {
  test.slow(); // Easy way to triple the default timeout
  // ...
});

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

API 参考：test.setTimeout() 和 test.slow()。

🌐 API reference: test.setTimeout() and test.slow().

将超时从 beforeEach 钩子更改

🌐 Change timeout from a beforeEach hook

example.spec.ts

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

test.beforeEach(async ({ page }, testInfo) => {
  // Extend timeout for all tests running this hook by 30 seconds.
  testInfo.setTimeout(testInfo.timeout + 30_000);
});

API 参考：testInfo.setTimeout()。

🌐 API reference: testInfo.setTimeout().

将“beforeAll”/“afterAll”钩子的超时调整

🌐 Change timeout for beforeAll/afterAll hook

beforeAll 和 afterAll 钩子有单独的超时时间，默认等于测试超时。你可以在钩子内部调用 testInfo.setTimeout() 来分别为每个钩子修改它。

example.spec.ts

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

test.beforeAll(async () => {
  // Set timeout for this hook.
  test.setTimeout(60000);
});

API 参考：testInfo.setTimeout()。

🌐 API reference: testInfo.setTimeout().

期望超时

🌐 Expect timeout

像 expect(locator).toHaveText() 这样的自动重试断言有一个单独的超时，默认是 5 秒。断言超时与测试超时无关。它会产生以下错误:

🌐 Auto-retrying assertions like expect(locator).toHaveText() have a separate timeout, 5 seconds by default. Assertion timeout is unrelated to the test timeout. It produces the following error:

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

Error: expect(received).toHaveText(expected)

Expected string: "my text"
Received string: ""
Call log:
  - expect.toHaveText with timeout 5000ms
  - waiting for "locator('button')"

在配置中设置期望超时

🌐 Set expect timeout in the config

playwright.config.ts

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

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

API参考：testConfig.expect。

🌐 API reference: testConfig.expect.

为单个断言指定预期超时

🌐 Specify expect timeout for a single assertion

example.spec.ts

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

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

全局超时

🌐 Global timeout

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

🌐 Playwright Test supports a timeout for the whole test run. This prevents excess resource usage when everything went wrong. There is no default global timeout, but you can set a reasonable one in the config, for example one hour. Global timeout produces the following error:

Running 1000 tests using 10 workers

  514 skipped
  486 passed
  Timed out waiting 3600s for the entire test run

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

🌐 You can set global timeout in the config.

playwright.config.ts

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

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

API 参考：testConfig.globalTimeout。

🌐 API reference: testConfig.globalTimeout.

高级：低级超时

🌐 Advanced: low level timeouts

这些是由测试运行器预先配置的低级超时设置，通常不需要更改它们。如果你因为测试不稳定而来到此部分，很可能你应该在其他地方寻找解决方案。

🌐 These are the low-level timeouts that are pre-configured by the test runner, you should not need to change these. If you happen to be in this section because your test are flaky, it is very likely that you should be looking for the solution elsewhere.

超时	默认值	描述
操作超时	无超时	每个操作的超时 在配置中设置 { 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)
夹具超时	无超时	单个夹具的超时 在夹具中设置 { scope: 'test', timeout: 30_000 }

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

🌐 Set action and navigation timeouts in the config

playwright.config.ts

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

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

API 参考：[testOptions.actionTimeout]（/api/class-testoptions.mdx#test-options-action-timeout）和 [testOptions.navigationTimeout]（/api/class-testoptions.mdx#test-options-navigation-timeout）。

🌐 API reference: testOptions.actionTimeout and testOptions.navigationTimeout.

设置单个操作的超时时间

🌐 Set timeout for a single action

example.spec.ts

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

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

夹具超时

🌐 Fixture timeout

默认情况下，fixture 与测试共享超时。但是，对于较慢的 fixture，尤其是 worker-scoped 的 fixture，设置单独的超时会更方便。这样，你可以保持整体测试超时较短，同时给较慢的 fixture 更多时间。

🌐 By default, fixture shares timeout with the test. However, for slow fixtures, especially worker-scoped ones, it is convenient to have a separate timeout. This way you can keep the overall test timeout small, and give the slow fixture more time.

example.spec.ts

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

const test = base.extend<{ slowFixture: string }>({
  slowFixture: [async ({}, use) => {
    // ... perform a slow operation ...
    await use('hello');
  }, { timeout: 60_000 }]
});

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

API参考：test.extend()。

🌐 API reference: test.extend().