browser-testing

name	browser-testing
description	Run, write, and troubleshoot Japa browser tests that use Playwright; use when you add or change frontend functionality that should be covered by tests

Browser testing with Japa + Playwright

Japa is built on Playwright, so you can use the methods from Playwright. See resources for more detailed Japa documentation.

Quick run

• node ace test browser runs the suite; limit files with --files tests/browser/smoketest.spec.ts.
• Control Playwright timeout with BROWSER_TIMEOUT (ms); defaults to 40000.
• Keep timeout config out of test files; rely on env/runner defaults.
• Browser tests depend on the shared test bootstrap. Keep schema setup in tests/bootstrap.ts via testUtils.db().migrate() and reset DB state per test with testUtils.db().withGlobalTransaction().

Debug aids

PWDEBUG=console node ace test browser

Alongside the page.pause method, you can use the page.pauseIf and page.pauseUnless methods to pause the script conditionally.

test('visit home page', async ({ visit }) => {
  const page = await visit('/')
  await page.pauseIf(process.env.DEBUG_TEST)
  await page.pauseUnless(process.env.NO_DEBUG)
})

Auth helpers

• Use browserContext.loginAs(testUser) from tests/bootstrap.ts to seed sessions.

Stable assertions

• Assert on data-testid or aria-label that you control; keep display text free for copy tweaks.
• Keep each test focused and deterministic; one concern per test.
• Add screenshots at key moments for future visual confirmation
• Capture multiple screenshots per flow (typically 2–5) at settled states (after waits/detach). Use foldered names tmp/browser/<suite>/<flow>/<step>.png via captureScreenshot in tests/browser/utils.ts (step can be 01-*). Take them only when the UI is idle to avoid empty or mid-animation shots.

Patterns that keep tests resilient

• Prefer page.getByTestId/getByRole over CSS selectors; add data-testid on status badges/CTAs you need.
• Assert on URLs for navigations to fail fast; avoid waiting on elements just to hit timeouts.
• Avoid page.evaluate for state checks; assert only on rendered UI.
• Use visit('/path'), then waitForLoadState('networkidle') before assertions.
• For auth/redirect flows, drive the real route:
  • Swap external components with fakes via app.container.swap (e.g., fake MSAL that returns a callback URL).
  • Trigger the redirect endpoint, wait for the callback URL, then land back on the target page and assert UI state.
• Keep data isolation: migrate once in tests/bootstrap.ts, then reset each browser test with testUtils.db().withGlobalTransaction(). If suite wiring happens in tests/bootstrap.ts, attach the transaction hook per test via suite.onTest((test) => test.setup(() => testUtils.db().withGlobalTransaction())).
• Seed state via models/services (e.g., insert connections or enquiries) instead of mocking fetch.
• When waiting on state changes, combine the action with an awaited navigation/response, or wait for specific testids to detach/appear; avoid arbitrary long timeouts.