Retries

Configuring Retries

Set retries: process.env.CI ? 2 : 0 in config. Locally you want immediate failure for fast feedback; CI benefits from 1–2 retries for network or timing blips.

Combine with trace: 'on-first-retry' to capture debugging artifacts only when a retry happens — saving storage.

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: { trace: 'on-first-retry', screenshot: 'only-on-failure' },
});

Traces from retries often show the difference between fail and pass attempts.

Retry Behavior

retries: 2           // global
test.describe.configure({ retries: 1 });  // per group

• Each retry starts fresh test with new context (default).
• Reporter marks test as flaky if it passes on retry.
• Do not rely on retries to pass consistently broken tests.
• Serial tests retry the whole serial group context.

Retries Best Practices

When and how to retry.

Detecting Flaky Tests

HTML report shows flaky tests separately. Track flaky rate over time — rising flakiness signals suite health decline.

Pair Retries with Traces

Configure trace: 'on-first-retry' so the retry that still fails captures a trace — you debug the failure mode that retries could not heal.

Common Mistakes

• Retries locally masking bugs during development.
• High retry count (5+) normalizing broken tests.
• Shared state causing pass-on-retry false confidence.
• No trace on retry — impossible to debug CI flake.

Key Takeaways

• Retries belong primarily in CI, not local dev.
• Pair retries with trace-on-first-retry.
• Flaky passes still need investigation.
• Fix root cause — retries are band-aids.