Retry flaky Playwright tests at the end of the run with retryStrategy

How Playwright retries by default

With retries set, a test that fails is run again, up to that many times. Playwright throws away the worker process and browser of the failed attempt and runs the retry in a fresh worker. A test that fails first and then passes is reported as flaky; one that fails every attempt is failed.

The default retryStrategy is 'immediate'. Playwright's types describe it as: a failed test is retried as soon as a worker is available, interleaved with the rest of the run. So the retry often runs in the same conditions that made the first attempt fail: every other worker still busy, the machine loaded, and your test backend under the same pressure.

retryStrategy: 'isolated'

Playwright 1.63 accepts a second value. With 'isolated', retries are run at the end, after all other tests have finished, one by one in a single worker. The types say this minimizes the interference between retried tests and the rest of the suite, at the expense of the total run time.

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

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  retryStrategy: 'isolated',
});

This is the behavior many teams asked for in a long-running Playwright feature request: retry flaky tests at the end of the run, when the machine is quiet. If your installed version does not know the option, TypeScript will flag it in playwright.config.ts; check npx playwright --version and upgrade.

When isolated retries help

• Load-sensitive failures. Timeouts that only happen when every worker is busy, or a page that renders slowly while other tests hammer the same backend.
• Shared test environments. Tests that hit a staging service with rate limits, or a database that slows down under parallel writes.
• Interference between tests. Two tests that touch the same record or account fail when they overlap; running the retry alone removes the overlap.

In each case a passing retry tells you something useful: the test works alone and fails under load or in company. That is a clue to the real fix, such as giving each test its own data or reducing workers on a small runner.

What it costs

• Run time. Retries no longer overlap with other tests, and they run one at a time. A run with many failures can get much longer. A real regression that breaks 50 tests now runs those 50 tests again, serially.
• Slower feedback on real failures. A broken test is retried at the end, so the run takes longer to finish red.
• It can hide a problem. A test that only passes when it runs alone is telling you about shared state or load. A green run hides that unless you look at the flaky count.

Two settings keep the cost in check. maxFailures stops the run after a number of failures, so a large regression does not trigger a long tail of serial retries. And failOnFlakyTests (or --fail-on-flaky-tests) makes the run exit with an error if any test is flaky, for teams that want retries for information only.

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  retryStrategy: 'isolated',
  maxFailures: process.env.CI ? 20 : undefined,
});

Serial groups are retried together

Tests in a test.describe.configure({ mode: 'serial' }) group depend on each other, so Playwright retries the whole group when one of them fails. That still applies with isolated retries: the group is retried as a unit. Large serial groups make retries expensive with either strategy, which is one more reason to keep tests independent.

Flaky but green is still flaky

Retries, immediate or isolated, decide whether a flaky test turns the run red. They do not tell you whether the same test was flaky yesterday, how often it happens, or whether it started with a particular change. A suite can stay green for months while the number of flaky tests slowly grows.

The guide to finding and fixing flaky tests covers reproducing them with --repeat-each and reading the trace of the failed attempt. When a pull request goes red, four questions tell a flaky failure from a real one.

TurnSignal keeps every attempt of every test across runs. The Flaky tests page lists the tests that were flaky in the last 7 to 90 days, how often, and the exact runs and attempts behind each label, and a failure on a pull request is marked known flaky when that test was flaky recently. Retries keep your pipeline moving; the history shows which tests to fix first. Setup is one reporter line; see the docs.