Open this when designing the Playwright layer, adding Storybook interaction tests, or wiring automated accessibility checks. Verified 2026-09 against https://playwright.dev/docs/test-snapshots, https://playwright.dev/docs/auth and https://storybook.js.org/docs/writing-tests/interaction-testing.
1. Playwright — journeys, not pages
End-to-end tests are expensive per test and per failure, so spend them only where a break would be an incident: sign in, the core create/edit flow, checkout or submission, and anything involving money or permissions. Everything else belongs in a component test.
// e2e/orders.spec.ts
import { expect, test } from '@playwright/test';
test('an agent can cancel an order', async ({ page }) => {
await test.step('open the order', async () => {
await page.goto('/orders/A-42');
await expect(page.getByRole('heading', { name: 'Order A-42' })).toBeVisible();
});
await test.step('cancel it', async () => {
await page.getByRole('button', { name: 'Cancel order' }).click();
await page.getByRole('dialog').getByRole('button', { name: 'Confirm' }).click();
});
await expect(page.getByRole('status')).toHaveText(/order cancelled/i);
});
Rules that keep the suite trustworthy:
getByRolewith the accessible name. CSS and XPath selectors turn every refactor into a red suite and teach the team to ignore failures.- Sign in once, save
storageState, reuse it — a login flow repeated in fifty tests is fifty chances to be flaky and minutes of runtime. - Seed through the API in
beforeEachand clean up afterwards. Tests that depend on data another test created cannot run in parallel and cannot be run alone. - Run against built output (
ng build, then serve the artefact or the SSR server).ng servehas different chunking, different timing and no production optimizations. - Retries in CI only, with
trace: 'on-first-retry'. Local retries hide flake from the person who introduced it. - Tag a smoke subset (
test('… @smoke'), run with--grep @smoke) for every pull request and run the full suite on the merge queue or nightly. - Never
waitForTimeout. Web-first assertions (await expect(locator).toBeVisible()) already retry; a sleep is a slower, less reliable version of the same thing.
2. Visual regression
await expect(page.getByTestId('invoice-summary')).toHaveScreenshot('invoice-summary.png', {
maxDiffPixelRatio: 0.01,
mask: [page.getByTestId('generated-at')],
});
- Scope the screenshot to a component or region, never the whole page — a full-page baseline changes on every unrelated edit and is re-recorded without being read.
maskeverything non-deterministic: timestamps, avatars, random ids, animations.- Generate baselines on the same platform as CI (a container image pinned in the repo), or every developer's font rendering produces a diff.
- Disable animations and set a fixed viewport and
prefers-reduced-motionin the project config.
Visual tests are worth it for a design system and for dense, layout-critical screens. They are not worth it for ordinary CRUD forms, where a role-based assertion says more and costs less.
3. Storybook
Stories are the cheapest place to pin down every state of a shared/ui component: default, loading, error, empty, long text, RTL, disabled.
// button.stories.ts
import type { Meta, StoryObj } from '@storybook/angular';
import { expect, fn, userEvent, within } from 'storybook/test';
import { Button } from './button';
const meta: Meta<Button> = { component: Button, args: { onClick: fn() } };
export default meta;
export const Clickable: StoryObj<Button> = {
play: async ({ canvasElement, args }) => {
const canvas = within(canvasElement);
await userEvent.click(canvas.getByRole('button'));
await expect(args.onClick).toHaveBeenCalled();
},
};
Storybook 9 consolidated the test utilities into the storybook/test entry point; older examples import from @storybook/test. Run the stories in CI with the Storybook test runner so the states stay honest.
4. Automated accessibility
Automated tooling catches roughly a third of WCAG issues — missing names, contrast, bad roles, orphaned form controls. It never catches focus order, meaningful alternative text or whether a flow is operable by keyboard. Run both.
- In component tests:
axeviavitest-axe(orjest-axeon Jest) on the rendered container, asserting no violations. - In Storybook:
@storybook/addon-a11y, failing the test runner on violations for design-system components. - In Playwright:
@axe-core/playwrighton each journey's key screens. - By hand, once per feature: tab through it with the mouse unplugged. Every interactive element reachable, focus visible, order matching the visual order, Escape closing what it opened.
Fail CI on new violations, not on the existing backlog: take a baseline count, and gate on "no increase". A gate that is red on day one gets disabled in week two.
5. What not to test end to end
- Field-level validation messages — component tests, in milliseconds.
- Every permutation of a table filter — one journey proves the wiring; the rest is a unit test on the filter function.
- Third-party widgets (payment iframes, map tiles) — assert that your page asked for them; do not drive someone else's UI.
- Error states you can only produce by breaking the backend — force them in a component test with a flushed 500 instead.