Playwright Timeouts and Retries

A delivery driver waits a reasonable amount of time at a customer's door before marking the delivery as failed and moving to the next address. A test needs the same kind of reasonable limit, called a timeout, so it does not wait forever for something that will never happen.

A Timeout Countdown

Action Starts
    |
    v
Waiting... (0 seconds to 30 seconds)
    |
  +-+-------------------+
  |                     |
Condition Met     Time Runs Out
  |                     |
 Test Passes         Test Fails

Setting a Timeout on a Single Action

await page.getByRole('button', { name: 'Generate Report' }).click({ timeout: 15000 });

This waits up to fifteen seconds for the button to become ready, useful for a button that stays disabled while a large report loads in the background.

Setting a Global Timeout for Every Test

module.exports = {
  timeout: 30000,
};

This setting inside playwright.config.js applies a thirty-second overall limit to every test, stopping any single test from hanging indefinitely and blocking the rest of the suite.

Setting a Timeout for Assertions

await expect(page.getByText('Processing complete')).toBeVisible({ timeout: 20000 });

This gives an assertion extra time to wait for a slow background process, separate from the timeout applied to clicks or typing actions.

Configuring Automatic Retries

module.exports = {
  retries: 2,
};

This setting reruns a failed test up to two more times before marking it as truly failed, useful for handling occasional network hiccups that have nothing to do with an actual bug.

Retries in a Team Environment

Many teams enable retries only on their continuous integration server, keeping retries turned off during local development. A developer writing new tests wants to see real failures immediately, while a CI server benefits from smoothing out rare network flakiness.

module.exports = {
  retries: process.env.CI ? 2 : 0,
};

A Real-World Scenario

A payment gateway occasionally takes an extra few seconds to respond during peak traffic hours. Setting a slightly longer timeout on the payment confirmation step prevents tests from failing due to normal, expected slowness rather than an actual bug.

The Danger of Overusing Retries

A test that genuinely fails due to a real bug might pass by chance on a retry if the underlying issue happens intermittently. Relying too heavily on retries can hide real problems instead of surfacing them clearly to the team.

Quick Practice Task

Open your playwright.config.js file and add a retries setting that only activates when running on a continuous integration server.

Key Takeaways

• Timeouts limit how long Playwright waits before failing an action.
• Retries automatically rerun a failed test a set number of times.
• Different actions can have different timeout values based on real speed.
• Overusing retries can hide genuine bugs instead of revealing them.