Why is this an issue?

End-to-end and integration tests need to synchronize with asynchronous work such as UI updates, network requests, or background jobs. Pausing for a fixed amount of time using framework APIs like Cypress' cy.wait(<number>) or page.waitForTimeout(<number>) in Playwright and legacy Puppeteer releases before v22.0.0 is a brittle way to do this:

• If the duration is too short, the test fails intermittently depending on machine load or network latency, producing flaky results.
• If the duration is too long, the test suite becomes needlessly slow and expensive to run on CI.
• The wait completes even when the awaited condition never happens, hiding real regressions instead of surfacing them.

Each modern end-to-end framework ships dedicated synchronization primitives that wait for an observable condition instead of a duration. Replace the fixed wait with one of these primitives so the test moves on as soon as the application is ready, and fails quickly when it is not.

• In Cypress, alias network calls with cy.intercept(…​).as(name) and wait on the alias, or assert on the resulting DOM state with retry-able queries such as cy.contains(…​).should('be.visible').
• In Playwright, prefer auto-retrying web-first assertions such as expect(locator).toBeVisible() or expect(locator).toHaveText(…​), or page.waitForResponse / page.waitForURL when the synchronization point is a network event.
• In Puppeteer, use page.waitForSelector, page.waitForFunction, or page.waitForResponse. page.waitForTimeout was deprecated in v16.1.1 (2022-08-16) and removed in v22.0.0 (2024-02-05).

Code examples

Noncompliant code example

// Cypress
it('saves a user', () => {
  cy.get('button.save').click();
  cy.wait(1000); // Noncompliant: fixed wait
  cy.contains('Saved').should('be.visible');
});

Compliant solution

// Cypress
it('saves a user', () => {
  cy.intercept('POST', '/users').as('saveUser');
  cy.get('button.save').click();
  cy.wait('@saveUser');
  cy.contains('Saved').should('be.visible');
});

Noncompliant code example

// Playwright
test('saves a user', async ({ page }) => {
  await page.getByRole('button', { name: 'Save' }).click();
  await page.waitForTimeout(1000); // Noncompliant: fixed wait
  await expect(page.getByText('Saved')).toBeVisible();
});

Compliant solution

// Playwright
test('saves a user', async ({ page }) => {
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.getByText('Saved')).toBeVisible();
});

Noncompliant code example

// Puppeteer (<22.0.0)
test('saves a user', async () => {
  await page.click('button.save');
  await page.waitForTimeout(1000); // Noncompliant: fixed wait
  expect(await page.$('.toast')).not.toBeNull();
});

Compliant solution

// Puppeteer
test('saves a user', async () => {
  await page.click('button.save');
  await page.waitForSelector('.toast');
  expect(await page.$eval('.toast', node => node.textContent)).toContain('Saved');
});

Resources

Documentation

• Cypress Documentation - cy.wait
• Cypress Documentation - Best practices: unnecessary waiting
• Playwright Documentation - Best practices: use web-first assertions
• Playwright Documentation - page.waitForTimeout()
• Puppeteer Documentation - changelog
• Puppeteer Documentation - page.waitForSelector()

Related rules

• {rule:javascript:S8959} covers UI test debug commands.