What is E2E testing? A small test suite you can trust

// Take a flaky test out of the release check until it is fixed
test.fixme("order history shows a placed order", async ({ page }) => {
  // ...the scenario stays in the code; only its execution stops
});

// ❌ Depends on markup details (breaks when styling or structure changes)
await page.locator(".btn-primary").click();
await page.locator("#order-list > div:nth-child(2) a").click();

// ✅ Locates by role and accessible name, as a user would
await page.getByRole("button", { name: "Place order" }).click();
await page.getByRole("link", { name: "Order history" }).click();

// ❌ Guesses the timing (fails under load, wastes time everywhere else)
await page.waitForTimeout(3000);
expect(await page.locator(".order-row").count()).toBe(3);

// ✅ Retries until the state appears, up to the timeout
await expect(page.getByRole("row", { name: /Order #/ })).toHaveCount(3);

// ❌ Depends on state another test created
// (fails when run alone, in parallel, or in a different order)
test("shows the order from the previous test", async ({ page }) => {
  await signIn(page, sharedAccount);
  await expect(page.getByRole("row", { name: "Order #1" })).toBeVisible();
});

// ✅ Prepares its own account and data, so it can run anywhere
test("order history shows a placed order", async ({ page }) => {
  const account = await prepareTestAccount();
  const order = await createTestOrder(account);
  await signIn(page, account);
  await page.getByRole("link", { name: "Order history" }).click();
  await expect(page.getByRole("row", { name: order.number })).toBeVisible();
});

// ❌ Every test signs in through the UI before its real work
test.beforeEach(async ({ page }) => {
  await page.goto("/login");
  // ...fill in credentials on every single test
});

// ✅ A setup project signs in once per role and saves the state
import { test as setup } from "@playwright/test";

setup(`authenticate as ${role}`, async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill(user.email);
  await page.getByLabel("Password").fill(user.password);
  await page.getByRole("button", { name: "Sign in" }).click();
  await page.waitForURL("/dashboard");
  await page.context().storageState({ path: authFile(role) });
});

// ✅ Tests reuse the saved state and start signed in
test.use({ storageState: authFile("admin") });

// Screens defined once as data: path, expected heading, allowed roles
const screens = [
  { path: "/reports", heading: "Reports", roles: ["admin", "manager"] },
  { path: "/settings/members", heading: "Member settings", roles: ["admin"] },
];

// One smoke test per screen per role, generated from the table
// (role is the role this suite runs as; one fixed value per spec file)
for (const { path, heading, roles } of screens) {
  test(`${heading} ${path}`, async ({ page }) => {
    await page.goto(path);
    const expected = roles.includes(role) ? heading : "Dashboard";
    await expect(
      page.getByRole("heading", { level: 1, name: expected })
    ).toBeVisible();
  });
}

// Create the data the scenario needs through a test-support API
// (runId is a unique identifier per run, such as a timestamp)
const org = await createTestOrg({ name: `e2e-signup-${runId}` });

// ❌ Guesses how long delivery takes (fails when slow, wastes time when fast)
await page.waitForTimeout(15000);
const mail = await fetchLatestMail({ to: org.email });

// ✅ Polls with a bounded timeout until the mail arrives, then reads it
await expect
  .poll(() => fetchLatestMail({ to: org.email }), { timeout: 30_000 })
  .not.toBeNull();
const mail = await fetchLatestMail({ to: org.email });

test.skip(
  process.env.E2E_ENV === "production",
  "Scenarios that create data do not run against production"
);