What are retries in Playwright, and when should I use them?

Retries tell Playwright to run a failed test again, up to the number you set with --retries or retries in the config; they are off by default. Use them on CI as a safety net with a report that flags every retry, never as a way to hide a test that fails for a reason you have not found.

This answer is one piece of Chapter 16: The Test Runner.

Test Structure & Lifecycle
playwright.config.ts Complete Reference
Test Organization at Scale
Tags, Grep, and the Suite You Actually Run
What Runs Where, and What Serial Costs
Practice and interview questions: Assertions & Test Runner

With retries on, a test that fails is run again. Playwright throws away the whole worker process and its browser first, so the retry starts clean. Each test then ends in one of three states: passed on the first run, flaky (failed first, passed on a retry), or failed (failed every attempt).

That middle state is the point. A flaky result is not a pass. It tells you the test depends on timing, data or another test, and the cause is still there. Teams usually set retries: process.env.CI ? 2 : 0 so the pipeline is not blocked by one bad run, keep retries off locally so flakiness is felt, and read the flaky list rather than ignoring it. trace: 'on-first-retry' records a trace exactly when you need one.

The example fakes flakiness on purpose: testInfo.retry is 0 on the first attempt, so that attempt expects the wrong heading and fails. Run with --retries=1, the retry expects the real heading and passes. Playwright reports the test as 1 flaky, not 1 passed.

retries.spec.js(https://practice.learnplayforge.com)

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

test('a flaky check passes on its retry', async ({ page }, testInfo) => {
  await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  // Simulates flakiness: the first attempt expects the wrong heading.
  const expected = testInfo.retry === 0 ? 'Some products' : 'All products';
  await expect(page.locator('#grid-heading')).toHaveText(expected, { timeout: 2000 });
});

Output

$ npx playwright test retries.spec.js --retries=1
Running 1 test using 1 worker
  x  1 [chromium] › retries.spec.js:3:1 › a flaky check passes on its retry (2.4s)
  ok 2 [chromium] › retries.spec.js:3:1 › a flaky check passes on its retry (retry #1) (345ms)

  1 flaky
    [chromium] › retries.spec.js:3:1 › a flaky check passes on its retry

Test yourself

With retries: 2, a test fails on its first run and passes on the second. How does Playwright report it?

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

What are retries in Playwright, and when should I use them?

Related questions