From c2cbf26497477bc3f720ef3f2bf5123fdb9bb43b Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Wed, 9 Oct 2024 05:10:10 -0700 Subject: [PATCH] docs: refresh timeouts doc (#33025) After changes a few releases ago, specify that `afterEach` hooks are included in a separate timeout. Fixes #32851. --- docs/src/test-api/class-test.md | 2 +- docs/src/test-configuration-js.md | 2 +- docs/src/test-timeouts-js.md | 83 ++++++++++++----------------- packages/playwright/types/test.d.ts | 4 +- 4 files changed, 39 insertions(+), 52 deletions(-) diff --git a/docs/src/test-api/class-test.md b/docs/src/test-api/class-test.md index 4706d462f0..31f60b7e9c 100644 --- a/docs/src/test-api/class-test.md +++ b/docs/src/test-api/class-test.md @@ -1319,7 +1319,7 @@ Timeout for the currently running test is available through [`property: TestInfo }); ``` -* Changing timeout from a slow `beforeEach` or `afterEach` hook. Note that this affects the test timeout that is shared with `beforeEach`/`afterEach` hooks. +* Changing timeout from a slow `beforeEach` hook. Note that this affects the test timeout that is shared with `beforeEach` hooks. ```js test.beforeEach(async ({ page }, testInfo) => { diff --git a/docs/src/test-configuration-js.md b/docs/src/test-configuration-js.md index 30bdbee8ca..822bd4ea0d 100644 --- a/docs/src/test-configuration-js.md +++ b/docs/src/test-configuration-js.md @@ -115,7 +115,7 @@ export default defineConfig({ | [`property: TestConfig.globalSetup`] | Path to the global setup file. This file will be required and run before all the tests. It must export a single function. | | [`property: TestConfig.globalTeardown`] |Path to the global teardown file. This file will be required and run after all the tests. It must export a single function. | | [`property: TestConfig.outputDir`] | Folder for test artifacts such as screenshots, videos, traces, etc. | -| [`property: TestConfig.timeout`] | Playwright enforces a [timeout](./test-timeouts.md) for each test, 30 seconds by default. Time spent by the test function, fixtures, beforeEach and afterEach hooks is included in the test timeout. | +| [`property: TestConfig.timeout`] | Playwright enforces a [timeout](./test-timeouts.md) for each test, 30 seconds by default. Time spent by the test function, test fixtures and beforeEach hooks is included in the test timeout. | ## Expect Options diff --git a/docs/src/test-timeouts-js.md b/docs/src/test-timeouts-js.md index 02f00f0b26..13676991eb 100644 --- a/docs/src/test-timeouts-js.md +++ b/docs/src/test-timeouts-js.md @@ -3,18 +3,16 @@ id: test-timeouts title: "Timeouts" --- -## Introduction - Playwright Test has multiple configurable timeouts for various tasks. |Timeout |Default |Description | |:----------|:----------------|:--------------------------------| -|Test timeout|30000 ms|Timeout for each test, includes test, hooks and fixtures:
Set default
{`config = { timeout: 60000 }`}
Override
`test.setTimeout(120000)` | -|Expect timeout|5000 ms|Timeout for each assertion:
Set default
{`config = { expect: { timeout: 10000 } }`}
Override
`expect(locator).toBeVisible({ timeout: 10000 })` | +|Test timeout|30_000 ms|Timeout for each test
Set in config
{`{ timeout: 60_000 }`}
Override in test
`test.setTimeout(120_000)` | +|Expect timeout|5_000 ms|Timeout for each assertion
Set in config
{`{ expect: { timeout: 10_000 } }`}
Override in test
`expect(locator).toBeVisible({ timeout: 10_000 })` | ## Test timeout -Playwright Test enforces a timeout for each test, 30 seconds by default. Time spent by the test function, fixtures, `beforeEach` and `afterEach` hooks is included in the test timeout. +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: @@ -24,6 +22,8 @@ example.spec.ts:3:1 › basic test =========================== Timeout of 30000ms exceeded. ``` +Additional separate timeout, of the same value, is shared between fixture teardowns and `afterEach` hooks, after the test function has finished. + 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 @@ -32,7 +32,7 @@ The same timeout value also applies to `beforeAll` and `afterAll` hooks, but the import { defineConfig } from '@playwright/test'; export default defineConfig({ - timeout: 5 * 60 * 1000, + timeout: 120_000, }); ``` @@ -40,7 +40,7 @@ API reference: [`property: TestConfig.timeout`]. ### Set timeout for a single test -```js +```js title="example.spec.ts" import { test, expect } from '@playwright/test'; test('slow test', async ({ page }) => { @@ -49,7 +49,7 @@ test('slow test', async ({ page }) => { }); test('very slow test', async ({ page }) => { - test.setTimeout(120000); + test.setTimeout(120_000); // ... }); ``` @@ -58,12 +58,12 @@ API reference: [`method: Test.setTimeout`] and [`method: Test.slow`]. ### Change timeout from a `beforeEach` hook -```js +```js title="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 + 30000); + testInfo.setTimeout(testInfo.timeout + 30_000); }); ``` @@ -73,7 +73,7 @@ API reference: [`method: TestInfo.setTimeout`]. `beforeAll` and `afterAll` hooks have a separate timeout, by default equal to test timeout. You can change it separately for each hook by calling [`method: TestInfo.setTimeout`] inside the hook. -```js +```js title="example.spec.ts" import { test, expect } from '@playwright/test'; test.beforeAll(async () => { @@ -86,7 +86,7 @@ API reference: [`method: TestInfo.setTimeout`]. ## Expect timeout -Web-first 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: +Auto-retrying assertions like [`method: LocatorAssertions.toHaveText`] have a separate timeout, 5 seconds by default. Assertion timeout is unrelated to the test timeout. It produces the following error: ```txt example.spec.ts:3:1 › basic test =========================== @@ -107,11 +107,23 @@ import { defineConfig } from '@playwright/test'; export default defineConfig({ expect: { - timeout: 10 * 1000, + timeout: 10_000, }, }); ``` +API reference: [`property: TestConfig.expect`]. + +### Specify expect timeout for a single assertion + +```js title="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 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: @@ -126,12 +138,11 @@ Running 1000 tests using 10 workers You can set global timeout in the config. -```js -// playwright.config.ts +```js title="playwright.config.ts" import { defineConfig } from '@playwright/test'; export default defineConfig({ - globalTimeout: 60 * 60 * 1000, + globalTimeout: 3_600_000, }); ``` @@ -144,22 +155,13 @@ If you happen to be in this section because your test are flaky, it is very like |Timeout |Default |Description | |:----------|:----------------|:--------------------------------| -|Action timeout| no timeout |Timeout for each action:
Set default
{`config = { use: { actionTimeout: 10000 } }`}
Override
`locator.click({ timeout: 10000 })` | -|Navigation timeout| no timeout |Timeout for each navigation action:
Set default
{`config = { use: { navigationTimeout: 30000 } }`}
Override
`page.goto('/', { timeout: 30000 })` | -|Global timeout|no timeout |Global timeout for the whole test run:
Set in config
`config = { globalTimeout: 60*60*1000 }`
| -|`beforeAll`/`afterAll` timeout|30000 ms|Timeout for the hook:
Set in hook
`test.setTimeout(60000)`
| -|Fixture timeout|no timeout |Timeout for an individual fixture:
Set in fixture
`{ scope: 'test', timeout: 30000 }`
| +|Action timeout| no timeout |Timeout for each action
Set in config
{`{ use: { actionTimeout: 10_000 } }`}
Override in test
`locator.click({ timeout: 10_000 })` | +|Navigation timeout| no timeout |Timeout for each navigation action
Set in config
{`{ use: { navigationTimeout: 30_000 } }`}
Override in test
`page.goto('/', { timeout: 30_000 })` | +|Global timeout|no timeout |Global timeout for the whole test run
Set in config
`{ globalTimeout: 3_600_000 }`
| +|`beforeAll`/`afterAll` timeout|30_000 ms|Timeout for the hook
Set in hook
`test.setTimeout(60_000)`
| +|Fixture timeout|no timeout |Timeout for an individual fixture
Set in fixture
`{ scope: 'test', timeout: 30_000 }`
| -### Set timeout for a single assertion - -```js -import { test, expect } from '@playwright/test'; - -test('basic test', async ({ page }) => { - await expect(page.getByRole('button')).toHaveText('Sign in', { timeout: 10000 }); -}); -``` ### Set action and navigation timeouts in the config ```js title="playwright.config.ts" @@ -177,7 +179,7 @@ API reference: [`property: TestOptions.actionTimeout`] and [`property: TestOptio ### Set timeout for a single action -```js +```js title="example.spec.ts" import { test, expect } from '@playwright/test'; test('basic test', async ({ page }) => { @@ -190,29 +192,14 @@ test('basic test', async ({ page }) => { By default, [fixture](./test-fixtures) shares timeout with the test. However, for slow fixtures, especially [worker-scoped](./test-fixtures#worker-scoped-fixtures) 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. -```js tab=js-js -const { test: base, expect } = require('@playwright/test'); - -const test = base.extend({ - slowFixture: [async ({}, use) => { - // ... perform a slow operation ... - await use('hello'); - }, { timeout: 60000 }] -}); - -test('example test', async ({ slowFixture }) => { - // ... -}); -``` - -```js tab=js-ts +```js title="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: 60000 }] + }, { timeout: 60_000 }] }); test('example test', async ({ slowFixture }) => { diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 41c88940c9..91fe2f2b5c 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -4105,8 +4105,8 @@ export interface TestType {