Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs(ci): recommend globalTimeout instead of a CI job timeout (#42563)

Dmitry Gozmana5e563294430
diff --git a/docs/src/ci-intro.md b/docs/src/ci-intro.md
index f39f11bef5..4f10fdd9b2 100644
--- a/docs/src/ci-intro.md
+++ b/docs/src/ci-intro.md
@@ -45,7 +45,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -75,6 +74,17 @@ The workflow performs these steps:
1. Run Playwright tests
1. Upload HTML report to the GitHub UI
+Note that the workflow does not set a job-level `timeout-minutes`. Instead, set [`globalTimeout`](./test-timeouts.md#global-timeout) in your config:
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ // Fail the run after an hour, so that the reporters still produce a report.
+ globalTimeout: 60 * 60 * 1000,
+});
+```
+
To learn more about this, see ["Understanding GitHub Actions"](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions).
## Setting up GitHub Actions
@@ -91,7 +101,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -123,7 +132,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -148,7 +156,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
diff --git a/docs/src/ci.md b/docs/src/ci.md
index 9c2c2cac03..a03db7ea90 100644
--- a/docs/src/ci.md
+++ b/docs/src/ci.md
@@ -59,6 +59,24 @@ export default defineConfig({
});
```
+## Global timeout
+* langs: js
+
+Always set a [global timeout](./test-timeouts.md#global-timeout) in CI. By default a test run has no upper bound, so a suite that hangs, or that slowly grows past the job limit of your CI provider, is killed by the runner mid-run and does not produce the test report.
+
+With [`property: TestConfig.globalTimeout`] set, Playwright stops the run itself.
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ // Fail the run after an hour, so that the reporters still produce a report.
+ globalTimeout: 60 * 60 * 1000,
+});
+```
+
+The examples below therefore do not set a job-level timeout such as `timeout-minutes` in GitHub Actions. If you do add one, keep it comfortably above `globalTimeout`, so that Playwright always stops first.
+
## CI configurations
The [Command line tools](./browsers#install-system-dependencies) can be used to install all operating system dependencies in CI.
@@ -79,7 +97,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -114,7 +131,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -146,7 +162,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -171,7 +186,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
@@ -312,7 +326,6 @@ on:
deployment_status:
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
@@ -336,7 +349,6 @@ on:
deployment_status:
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
@@ -363,7 +375,6 @@ on:
deployment_status:
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
@@ -389,7 +400,6 @@ on:
deployment_status:
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
@@ -415,7 +425,7 @@ Large test suites can take very long to execute. By executing a preliminary test
This will give you a faster feedback loop and slightly lower CI consumption while working on Pull Requests.
To detect test files affected by your changeset, `--only-changed` analyses your suites' dependency graph. This is a heuristic and might miss tests, so it's important that you always run the full test suite after the preliminary test run.
-```yml js title=".github/workflows/playwright.yml" {24-26}
+```yml js title=".github/workflows/playwright.yml" {23-25}
name: Playwright Tests
on:
push:
@@ -424,7 +434,6 @@ on:
branches: [ main, master ]
jobs:
test:
- timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
diff --git a/docs/src/test-configuration-js.md b/docs/src/test-configuration-js.md
index 52e68c658c..6af98ffcc8 100644
--- a/docs/src/test-configuration-js.md
+++ b/docs/src/test-configuration-js.md
@@ -30,6 +30,9 @@ export default defineConfig({
// Opt out of parallel tests on CI.
workers: process.env.CI ? 1 : undefined,
+ // Limit the whole test run, so that it fails with a report instead of hanging.
+ globalTimeout: 60 * 60 * 1000,
+
// Reporter to use
reporter: 'html',
@@ -60,6 +63,7 @@ export default defineConfig({
| :- | :- |
| [`property: TestConfig.forbidOnly`] | Whether to exit with an error if any tests are marked as `test.only`. Useful on CI.|
| [`property: TestConfig.fullyParallel`] | have all tests in all files to run in parallel. See [Parallelism](./test-parallel) and [Sharding](./test-sharding) for more details. |
+| [`property: TestConfig.globalTimeout`] | Maximum time the whole test run can take. When reached, Playwright stops the run and reporters still produce a report. See [Timeouts](./test-timeouts.md) to learn more. |
| [`property: TestConfig.projects`] | Run tests in multiple configurations or on multiple browsers |
| [`property: TestConfig.reporter`] | Reporter to use. See [Test Reporters](/test-reporters.md) to learn more about which reporters are available. |
| [`property: TestConfig.retries`] | The maximum number of retry attempts per test. See [Test Retries](/test-retries.md) to learn more about retries.|
diff --git a/docs/src/test-sharding-js.md b/docs/src/test-sharding-js.md
index a83df1b1ab..b1c0292c8a 100644
--- a/docs/src/test-sharding-js.md
+++ b/docs/src/test-sharding-js.md
@@ -93,7 +93,6 @@ on:
branches: [ main, master ]
jobs:
playwright-tests:
- timeout-minutes: 60
runs-on: ubuntu-latest
strategy:
fail-fast: false