Repository navigation
docs: correct FE1 and agent guidance on Storybook and Vitest roles #29016
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
| - 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
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 })); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When the contract is semantic DOM state, such as the absence of an incorrect
tablistrole 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 assite/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 👍 / 👎.