How to set Playwright test retries

Browser test suites sometimes fail because of timing, a busy CI worker, or a short-lived service response rather than a product regression. Playwright Test retries give a failed test a limited second chance while still labeling a retry-passed result as flaky.

The retries setting belongs in playwright.config.ts or playwright.config.js when the retry count should travel with the project. A command-line override such as --retries=1 is better for a one-time diagnostic run because it does not change the saved project policy.

Keep retry counts small and treat every flaky result as work to investigate. A retried pass still means the first attempt failed, so pair retries with traces, screenshots, or a focused debug run when the same test keeps appearing in the flaky list.

1. Open playwright.config.ts in the Playwright project root.
2. Set the retries value in the config file.

   import { defineConfig } from '@playwright/test';
   
   export default defineConfig({
     testDir: './tests',
     retries: 1,
   });

   Use retries: process.env.CI ? 2 : 0 when local runs should fail on the first attempt but CI jobs should retry transient failures.

3. Create a temporary retry probe test.

   tests/retry-probe.spec.ts

   import { test, expect } from '@playwright/test';
    
   test('retry probe passes on retry', async ({}, testInfo) => {
     expect(testInfo.retry).toBeGreaterThan(0);
   });

   The first attempt sees testInfo.retry as 0 and fails. The retry attempt sees 1 and passes, which gives a deterministic check of the saved retry setting.

4. Run the retry probe.

   $ npx playwright test tests/retry-probe.spec.ts --reporter=list
   Running 1 test using 1 worker
   
     ✘  1 tests/retry-probe.spec.ts:3:1 › retry probe passes on retry (6ms)
     ✓  2 tests/retry-probe.spec.ts:3:1 › retry probe passes on retry (retry #1) (6ms)
   
   ##### snipped #####
   
     1 flaky
       tests/retry-probe.spec.ts:3:1 › retry probe passes on retry

   The 1 flaky summary confirms that Playwright retried the first failed attempt and kept the test out of the final failed list.
   Related: How to run specific Playwright tests

5. Remove the temporary retry probe.

   $ rm tests/retry-probe.spec.ts

   Do not commit the probe test. It is designed to fail once so the retry path can be checked.