| name | capybara-storyboard |
| description | Visually verify UI changes by running system specs with capybara-storyboard and reading the captured screenshot sequence. Use whenever app/views or app/components changes need a visual check, or when a system spec is changed and run. |
| model | sonnet |
Capybara Storyboard visual review
Capybara::Storyboard captures a Capybara operation (visit, click_on, ...) together with a
screenshot at each step of a system spec, and lays the screenshots out as an ordered sequence
per test. This skill drives an agent through generating and reading that sequence to catch
things a passing test can't: layout breakage, leftover UI state (a modal that didn't close, a
flash message still showing), error screens, or anything else that looks wrong for the action
and point in the test where it occurs.
Reviewing screenshots one image at a time only works if the set stays small — narrow to the
system specs actually touched by the change, not the whole suite. Capturing every system spec
would produce hundreds of images, which defeats the purpose.
When this applies
app/views or app/components were changed and the resulting screen needs a visual check.- A system spec was changed and is being run.
Steps
1. Determine the target specs
Narrow to the system specs relevant to the change:
- If
app/views or app/components changed, identify which system specs exercise the changed
screen(s) — search for the view/component name, the controller action, or the route it
belongs to. Use this bullet whenever the call sites are countable: if you can enumerate all
the places the changed view/component is used and there are roughly 10 or fewer, target those
specific call sites directly — even if the changed file is itself called a shared "component".
If more than one spec is a plausible match and it isn't obvious which apply, ask the user.
- If enumerating every call site is impractical, or the changed file is a layout or
partial/component rendered by most/all pages rather than a handful of named places (so the
search above would return most or all system specs, not a short list), don't try to enumerate
every caller. Instead propose a small representative sample (roughly 3-6 specs) spanning
distinct usage contexts where the change is most likely to visually clash — e.g. a signed-out
page, a standard authenticated page, an admin/dense-UI page, a mobile/narrow-viewport spec if
one exists — and confirm the sample with the user before running, since you can't be sure
those spec files exist or still match without checking.
- If a system spec itself was changed, that spec is the target.
2. Run the specs and capture screenshots
Run the target specs locally with only SCREENSHOTS=1 set, passing the target spec files
directly as rspec arguments so only the relevant tests produce screenshots:
SCREENSHOTS=1 bundle exec rspec spec/system/login_spec.rb spec/system/signup_spec.rb
Running bundle exec rspec with SCREENSHOTS=1 and no spec path arguments captures every
system spec — avoid this unless the user explicitly wants a full-suite review, since it
produces an impractically large set of images to read one at a time.
3. Enumerate the output
Screenshots land at:
tmp/screenshots/{GroupName}/{example_name}/{NNN_action_detail}.png
Each {GroupName}/{example_name} directory is one system spec example — treat it as one unit
of review. Within a directory, list PNGs in ascending NNN order: that zero-padded prefix is
the order the actions happened during the test, and the rest of the filename names the action
(e.g. 001_visit_users.png, 002_before_click_on_Done.png,
003_after_click_on_Done.png). Click methods (click_on, click_link, click_button)
produce a before/after pair; everything else produces one screenshot taken after the action.
4. Read each image in sequence
For each {GroupName}/{example_name} directory, read its PNGs in NNN order, one at a time.
For each image, use the filename (the action) and its position in the sequence (what happened
right before it) to judge whether the screen looks right at that point — check for layout
breakage, unintended or leftover UI state, error pages, and anything else inconsistent with
the action just performed.
5. Report per test
For each {GroupName}/{example_name} directory report:
- Which test it is.
- For any issue found: which action/sequence number (by filename) it appeared right after,
and what was observed.
A directory with no issues just needs a short confirmation — don't pad the report.
6. Clean up
Remove the local tmp/screenshots/** output once the review is done, unless the user wants it
kept for later reference.
