Playwright E2E skill for Codex

A trustworthy Playwright suite finds elements the way users do (role, label, text), never sleeps, logs in once per worker or run instead of per test, records a trace for every retried failure, and gives the same result locally and in CI.

Inspect first

1. Read AGENTS.md, playwright.config.ts and package.json scripts. Note testDir, projects, webServer, use.baseURL, retries, trace, and reporters.
2. Check the installed version: npx playwright --version. Browsers must match it; npx playwright install --with-deps chromium downloads them and needs network (and sudo for system deps on Linux), so ask for approval in a sandboxed Codex session.
3. Read existing fixtures (tests/fixtures.ts or similar) and page objects before adding new ones.
4. Find how test data is created: API seeding, database scripts, or UI clicks. UI-only setup is the first thing to replace.

Baseline config

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: process.env.CI ? [["blob"], ["github"]] : [["html", { open: "never" }]],
  use: {
    baseURL: process.env.BASE_URL ?? "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    testIdAttribute: "data-testid",
  },
  projects: [
    { name: "setup", testMatch: /.*\.setup\.ts/ },
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" },
      dependencies: ["setup"],
    },
  ],
  webServer: {
    command: "npm run start:e2e",
    url: "http://localhost:3000/health",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
});

Add playwright/.auth/ to .gitignore; storage state files contain session cookies.

Locators

Priority, best first:

Locator	Example
Role + accessible name	page.getByRole("button", { name: "Place order" })
Label	page.getByLabel("Email")
Placeholder / text	page.getByText("Order confirmed")
Test id (stable contract)	page.getByTestId("cart-total")
CSS / XPath	last resort; breaks on markup changes

const row = page.getByRole("row").filter({ hasText: "INV-0042" });
await row.getByRole("button", { name: "Download" }).click();

• Locators are lazy and strict: an action on a locator matching two elements throws. Narrow with filter, getByRole(..., { exact: true }), or scope within a parent.
• Avoid .nth() and .first() unless order is the behavior under test.
• If role locators fail because the markup lacks labels, that is an accessibility bug; report it instead of falling back to CSS silently.

Assertions

Use web-first assertions; they retry until the timeout.

await expect(page.getByRole("heading", { name: "Checkout" })).toBeVisible();
await expect(page).toHaveURL(/\/orders\/\d+$/);
await expect(page.getByTestId("cart-total")).toHaveText("€42.00");
await expect(page.getByRole("listitem")).toHaveCount(3);
await expect.poll(async () => (await api.get("/jobs/7")).status).toBe("done");

Never: expect(await locator.isVisible()).toBe(true) (no retry), page.waitForTimeout(2000), or waitForLoadState("networkidle") as a sync point.

Auth once

// e2e/auth.setup.ts
import { test as setup, expect } from "@playwright/test";

setup("authenticate", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill(process.env.E2E_USER!);
  await page.getByLabel("Password").fill(process.env.E2E_PASSWORD!);
  await page.getByRole("button", { name: "Sign in" }).click();
  await expect(page.getByRole("button", { name: "Account" })).toBeVisible();
  await page.context().storageState({ path: "playwright/.auth/user.json" });
});

Credentials come from env vars or a seeded test account, never from source. Faster still: log in through the API with request.post and save its storage state. Tests that mutate per-user state need a user per worker; see the fixtures reference.

Fixtures

// e2e/fixtures.ts
import { test as base } from "@playwright/test";

type Fixtures = { seededOrder: { id: string } };

export const test = base.extend<Fixtures>({
  seededOrder: async ({ request }, use) => {
    const res = await request.post("/api/test/orders", { data: { items: 2 } });
    const order = await res.json();
    await use(order);
    await request.delete(`/api/test/orders/${order.id}`);
  },
});
export { expect } from "@playwright/test";

Create data through APIs in fixtures; drive the UI only for the behavior under test.

Network and time control

await page.route("**/api/recommendations", (route) =>
  route.fulfill({ json: [{ id: 1, title: "Mock item" }] }),
);
await page.route("**/*.{png,jpg}", (route) => route.abort());   // speed, when images are irrelevant

// Fixed "now" for date rendering; timers keep running normally
await page.clock.setFixedTime(new Date("2026-03-01T10:00:00Z"));

// Or full control of timers: install before navigation, then jump ahead
await page.clock.install({ time: new Date("2026-03-01T10:00:00Z") });
await page.goto("/account");
await page.clock.fastForward("05:00");                            // session timeout banner

Mock third-party services and slow non-critical endpoints; keep your own backend real in at least one smoke project so contracts are exercised.

Steps and readability

test("customer reorders a past purchase", async ({ page, seededOrder }) => {
  await test.step("open order history", async () => {
    await page.goto("/account/orders");
  });
  await test.step("reorder", async () => {
    await page.getByRole("row").filter({ hasText: seededOrder.id })
      .getByRole("button", { name: "Reorder" }).click();
  });
  await expect(page.getByRole("status")).toHaveText("Added 2 items to cart");
});

Page objects are optional; a few helper functions or fixtures usually suffice. If you use them, expose locators and intent-level actions, not assertions hidden inside.

Running and debugging

npx playwright test e2e/checkout.spec.ts -g "reorders"
npx playwright test --project=chromium --headed
npx playwright test --last-failed
npx playwright test --repeat-each=20 e2e/checkout.spec.ts     # flake hunting
npx playwright test --debug                                    # inspector, local only
npx playwright show-trace test-results/<test>/trace.zip
npx playwright show-report

In Codex, run headless (default) and read test-results/ and traces; --ui and --debug need a display.

Flake triage order: open the trace, find the action before the failure, check whether the locator matched something different, whether a request was still in flight, or whether data from another test collided. Fix the cause; do not raise timeouts globally.

CI

For sharding, merged reports, Docker images and per-worker accounts, read references/ci-and-scaling.md when setting up or changing a pipeline.

Gotchas

• retries hide flakiness; check the report’s “flaky” count and treat it as failures to fix.
• fullyParallel: true breaks tests that share a user or a record; isolate data first.
• baseURL plus page.goto("/path") only; hard-coded hosts break preview environments.
• test.only committed by accident is blocked by forbidOnly in CI.
• Visual comparisons belong to $visual-regression-testing; keep E2E specs behavioral.

Verification

1. Run the new or changed spec with --repeat-each=10; zero failures.
2. Run the whole suite with the CI worker count.
3. Confirm a deliberate break (wrong expected text) fails with a readable message and a trace.
4. Check that no test depends on another test’s data or order.