Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 61 additions & 23 deletions .claude/docs/FRONTEND_PATTERNS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,46 +14,84 @@ How to use this document:
`site/AGENTS.md` holds the one-line summary of each rule plus general frontend
workflow guidance. This file is the authoritative version with examples.

## FE1: UI behavior ships with Storybook interaction coverage

Every user-visible behavior change needs a Storybook story whose `play`
function actually exercises the interaction. Jest/RTL tests are for pure logic
(helpers, hooks without DOM interaction), not for UI interactions.

- The story must perform the real interaction: open the dropdown, submit the
form, pin the mobile viewport. A story that renders a closed popover tests
nothing.
- Cover the meaningful branches: error, empty, disabled, and mobile states,
not only the happy path.
- Assert both sides of an invariant: the item that changed and a neighboring
item that must not change.
## FE1: Vitest covers behavior, Storybook covers visual states

Frontend changes should have behavior coverage in Vitest and/or visual
state coverage in Storybook. This does not mean every change needs a new
test: when coverage already exists, extend it only if the change alters
what it covers. CI runs Pixel for visual regression testing using
Storybook: it loads each story, runs its `play` function, waits for the
DOM to settle, and screenshots it. The screenshot is the visual
regression check: what the DOM renders, shows, or hides. The test is
the behavior check: what the component did.

- Behavior tests should use Vitest, React Testing Library and `userEvent`.
Drive the real interaction, then assert the non-visual outcome: the
callback payload, the API request, the state change. This includes
stateful UI hooks consumed by a component: cover them through that
component's test.
- Use semantic queries (`getByRole`, `getByLabelText`) to locate the elements
you interact with, not as the assertion. Do not assert `.toBeInTheDocument()`,
`.toBeVisible()`, DOM geometry, or attribute presence. Hard stop: they
report what the DOM renders, which is exactly what the story's screenshot
already captures.
Comment on lines +33 to +37

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Permit assertions for DOM-only outcomes

When the contract is semantic DOM state, such as the absence of an incorrect tablist role or the presence of an accessible error message, there may be no callback or request to assert, and a pixel screenshot cannot detect the accessibility regression. The hard ban would reject tests such as site/src/components/Tabs/Tabs.test.tsx:31-46, removing the only check for semantics that remain visually identical. Limit the prohibition to assertions that merely duplicate visual coverage, while allowing rendered or semantic assertions when they are themselves the behavior under test.

AGENTS.md reference: AGENTS.md:L31-L31

Useful? React with 👍 / 👎.

- A story's `play` function exists only for state setup the screenshot needs:
open the menu, toggle the switch, type the text, focus the trigger. Do not
put assertions in a play function; if an assertion there seems valuable,
it belongs in a Vitest test instead. Pixel fails the capture only if the
setup throws.
Comment on lines +38 to +42

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and call out more clearly that the alternative here is to do it in Vitest instead if it's actually valuable.

- Cover the meaningful visual branches: error, empty, disabled, and mobile
states, not only the happy path.
- Stories excluded from Pixel (`parameters.pixel.exclude`) are never
screenshot, so they provide no coverage at all; state why the story is
excluded and cover its behavior with a Vitest test instead.
- When a component depends on the current time or date, accept it as a prop or
via context instead of reading `new Date()` or `Date.now()` internally, so
stories render deterministically without mocking globals.
- `renderHook` suites for stateful UI hooks are interaction tests, not pure
logic. Cover that behavior through the story of the component that uses the
hook.

**Incorrect (interaction test in Jest/RTL):**
**Incorrect (assertions in a play function):**

```tsx
// ModelSelector.stories.tsx
export const SelectModel: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await userEvent.click(canvas.getByRole("button", { name: /model/i }));
await expect(canvas.getByRole("listbox")).toBeVisible();
},
};
```

**Incorrect (visibility as the test's outcome; that is the screenshot's job):**

```tsx
// ModelSelector.test.tsx
it("selects a model", async () => {
render(<ModelSelector {...props} />);
await userEvent.click(screen.getByRole("button"));
// ...
await userEvent.click(screen.getByRole("button", { name: /model/i }));
expect(screen.getByRole("listbox")).toBeVisible();
});
```

**Correct (Storybook story with a play function):**
**Correct (the test asserts the callback, the story captures the visual):**

```tsx
// ModelSelector.test.tsx
it("selects a model", async () => {
const onValueChange = vi.fn();
render(<ModelSelector {...props} onValueChange={onValueChange} />);
await userEvent.click(screen.getByRole("button", { name: /model/i }));
await userEvent.click(screen.getByRole("option", { name: "GPT-4o Mini" }));
expect(onValueChange).toHaveBeenCalledWith("gpt-4o-mini");
});
```

```tsx
// ModelSelector.stories.tsx
export const SelectModel: Story = {
// Opens the listbox so the screenshot captures the open state.
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await userEvent.click(canvas.getByRole("button", { name: /model/i }));
await expect(canvas.getByRole("listbox")).toBeVisible();
await userEvent.click(within(canvasElement).getByRole("button", { name: /model/i }));
},
};
```
Expand Down
25 changes: 17 additions & 8 deletions .claude/skills/frontend-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ before they see the PR.
`origin` remote and the local `main` may be stale. List the changed files.
2. For each changed file, audit against each FE rule using the checklist
below. Read the full file when the diff alone cannot answer a check (for
example, whether a story's `play` function exercises the new behavior).
example, whether a `.test.tsx` covers the changed behavior).
3. Report results as a per-rule verdict table (see Output format). Every FAIL
must carry `file:line` and a one-line reason.
4. Fix all FAIL findings with the smallest safe diff. Re-run the audit until
Expand All @@ -34,13 +34,22 @@ before they see the PR.

## Per-rule diff checklist

- **FE1 (Storybook coverage)**: Does any changed component or page alter
user-visible behavior? Then a changed or added `.stories.tsx` must exist,
and its `play` function must perform the new interaction (open the menu,
submit the form), not merely render. Interaction tests added to `.test.tsx`
files are a FAIL unless they cover pure logic; `renderHook` suites for
stateful UI hooks count as interaction tests and belong in the consuming
component's story.
- **FE1 (behavior and visual coverage)**: Does any changed component or page
alter frontend behavior? The behavior should be covered by an existing or
new Vitest test, and the new visual states by Storybook stories. Behavior
tests should use Vitest, React Testing Library and `userEvent`. A `play`
function may only drive state setup the screenshot needs (open the menu,
type the text); flag assertions in a `play` function and behavior covered
only by a story, and note that a valuable assertion belongs in a
Vitest test. In the test, queries locate the element to interact with; the
assertion must be the non-visual outcome (callback, request, state). An
outcome assertion on what the DOM renders (`toBeVisible`,
`toBeInTheDocument`, geometry, attribute presence) is flagged, hard stop:
the story's screenshot already covers it. Flag tests written only to
expand coverage when equivalent coverage already exists. Flag stories marked
`parameters.pixel.exclude: true` that lack a stated reason or an
equivalent test: an excluded story is never screenshotted, so it must
justify why it is excluded and how its behavior is covered.
- **FE2 (types)**: Search the diff for `any`, `as unknown as`, non-null
assertions in any form (`x!.y`, `items[0]!`, `fn()!`, `value! as T`), and
new `as` casts. Check that API data uses types from `api/typesGenerated.ts`.
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Docs use `pnpm run format-docs` and `pnpm run lint-docs`. Frontend commands live
- **Public API:** add the required Swagger annotations for new public HTTP endpoints.
- **Transactions:** keep `InTx` work on the transaction handle. Prefer explicit database-to-SDK converters.
- **Concurrent tests:** call `t.Parallel()`, use unique identifiers, and do not use `time.Sleep` to mask timing problems.
- **Frontend:** reuse shared UI primitives and test components or pages through Storybook stories. Plain Vitest files are for pure logic only.
- **Frontend:** reuse shared UI primitives. Cover visual states with Storybook stories; Pixel screenshots them in CI. Cover component behavior with Vitest, React Testing Library and `userEvent` tests that assert the non-visual outcome of the interaction (callback, request, state); extend existing coverage instead of adding a new test when equivalent coverage already exists.
- **GitHub Actions:** set top-level `permissions: {}` and grant only required permissions per job.

## Code and writing style
Expand Down
5 changes: 3 additions & 2 deletions site/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Read [Frontend Patterns](../.claude/docs/FRONTEND_PATTERNS.md) before changing `

## Frontend contract

- **FE1:** UI behavior changes ship with Storybook stories whose `play` function exercises the real interaction. Vitest or RTL is for pure logic only.
- **FE1:** UI behavior changes should have behavior coverage in Vitest and/or visual state coverage in Storybook stories; do not write a new test when equivalent coverage already exists. Pixel screenshots every story in CI, so a story's `play` function may drive the component into the state being captured (open the menu, type text) but must not assert behavior; a valuable assertion belongs in a Vitest test instead. Behavior tests should use Vitest, React Testing Library and `userEvent`, and assert the non-visual outcome (callback, request, state); do not assert `toBeInTheDocument` or `toBeVisible`; that is the screenshot's job.
Comment thread
DanielleMaywood marked this conversation as resolved.
Resolved
- **FE2:** No `any`, `as unknown as`, or avoidable casts. Use generated API types from `api/typesGenerated.ts`.
- **FE3:** Search for an existing component or helper before writing one. Keep changes single-purpose.
- **FE4:** Do not add comments that restate identifiers, assertions, or control flow.
Expand Down Expand Up @@ -70,7 +70,8 @@ Some end-to-end tests require a license. The Storybook MCP at `http://localhost:

## Testing

- Add or update Storybook stories for component and page behavior, visual states, keyboard interaction, focus, and accessibility.
- Add or update Storybook stories for component and page visual states: loading, error, empty, refetch, keyboard, focus, and accessibility states as rendered. Cover behavior with Vitest, React Testing Library and `userEvent` tests that assert the non-visual outcome of the interaction (callback, request, state); extend existing coverage instead of adding a new test when equivalent coverage already exists.
- Stories run their `play` function during Pixel captures, so a `play` function is only for state setup that the screenshot needs (open a menu, toggle a switch); do not put assertions in it. Asserting what the DOM renders (visibility, presence, layout) belongs to the screenshot, whether in a story or a test.
- Assert observable behavior with semantic queries. Do not assert Tailwind classes or implementation details.
- Use `data-testid` only when an element has no suitable role or accessible name.
- Do not depend on smooth scrolling in tests. Use instant behavior or control the scroll position directly.
Expand Down
Loading