e2e-testing

End-to-End Testing (Playwright)

E2E tests sit at the top of the test pyramid — expensive, slow, and the first place flakiness shows up. Most flakiness traces back to one thing: the test racing the page instead of waiting for a specific, observable condition.

Page Object Model

export class ReservationsPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto("/reservations");
  }

  async search(query: string) {
    await this.page.locator('[data-testid="search-input"]').fill(query);
    await this.page.waitForResponse((r) => r.url().includes("/api/search"));
  }

  rows() {
    return this.page.locator('[data-testid="reservation-row"]');
  }
}

The single highest-value fix: stop waiting on time, wait on state

// Flaky: races the animation/network, passes locally, fails in CI
await page.waitForTimeout(2000);
await page.click('[data-testid="confirm"]');

// Stable: waits for the actual condition
await page.locator('[data-testid="confirm"]').waitFor({ state: "visible" });
await page.locator('[data-testid="confirm"]').click();

Playwright locators already auto-wait for actionability (attached, visible, stable, enabled) before acting — page.waitForTimeout is almost never the right tool and should be treated as a review finding, not a style preference.

Gotchas

• page.click(selector) on a raw selector string skips Playwright's auto-waiting in some older API patterns; page.locator(selector).click() is the form that gets the actionability checks. Prefer locators throughout, not selector strings passed directly to action methods.
• A test that passes locally but fails in CI is frequently a timing issue invisible on a fast local machine and a slow, resource-constrained CI runner — reproduce with --repeat-each=10 before assuming it's an environment misconfiguration.
• test.skip/test.fixme used to silence a flaky test without an attached issue reference is a one-way door — the test quietly stops providing coverage and nobody notices it never runs again. Always attach a tracking reference when quarantining a test.
• CI-only flakiness is commonly a resource contention issue, not a logic bug: setting workers: 1 for CI (serializing tests) and retries: 2 is a legitimate stabilizing measure while investigating root cause, but should not be treated as the fix itself — a retried, silently-passing flaky test is still hiding a real race condition.