---

name: playwright-visual-verification description: Use when you need to confirm a frontend change works in the real running app, not just that tests pass or code compiles. Covers driving the page, waiting on real signals, screenshots, and route smoke checks.

Playwright Visual Verification

When to trigger

After a UI change, before claiming it works: verifying a new route renders, a component appears in the right state, or a set of pages all return 200.

Verify against the running app

Compiling and unit tests passing is not proof the page renders. Drive the real app.

1. Start the app (or point Playwright at a running dev server).

2. Navigate and wait on a real signal, not a fixed sleep:

   await page.goto("/library/skills");
   await page.waitForLoadState("networkidle");
   await expect(page.getByRole("heading", { name: /skill library/i })).toBeVisible();
   

3. Screenshot for the record and for visual review:

   await page.screenshot({ path: "verify/library-skills.png", fullPage: true });
   

4. Assert on visible, user-facing state: a heading, a row count, a button being enabled. Not on internal class names that churn.

Route smoke check

To confirm many routes at once, loop and assert the status:

for (const path of ["/library", "/library/skills", "/library/skills/clerk-auth-setup"]) {
  const res = await page.request.get(path);
  expect(res.status(), path).toBe(200);
}

Pitfalls

• waitForTimeout (a fixed sleep) is flaky: too short and the page is not ready, too long and the suite crawls. Wait on a load state or an element instead.
• Asserting on CSS class names couples the test to styling. Assert on roles and text.
• A brand-new route can 404 because the dev server has not picked it up. Restart the server before concluding the page is broken.