Should you use retries, and how do they work?

A retry is a second attempt at a failed test. It is useful when the failure came from infrastructure such as a slow network or a temporarily unavailable service. It is harmful when it turns a genuine product defect into a passing run.

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

Rules of thumb

• Use zero retries locally so flakes are visible during development
• Use a small count in CI, often one or two, and alert when it is exhausted
• Record a trace and screenshot on the retry, not on every passing run
• Track which tests needed a retry and fix the root cause
• Never use retries to make an order-dependent suite look stable
• testInfo.retry exposes the current attempt count when behaviour must differ

test("uploads a report", async ({ page }, testInfo) => {
  if (testInfo.retry > 0) {
    await page.context().clearCookies();
  }

  await page.goto("/reports");
  await page.getByLabel("File").setInputFiles("fixtures/report.csv");
  await page.getByRole("button", { name: "Upload" }).click();

  await expect(page.getByText("Upload complete")).toBeVisible();
});