Skip to content

feat(browser-qa): add before/after screenshot QA topic - #11

Merged
gsdevme merged 2 commits into
mainfrom
feat/browser-qa
Oct 29, 2026
Merged

gsdevme merged 2 commits into
mainfrom
feat/browser-qa

Conversation

@gsdevme

@gsdevme gsdevme commented Oct 12, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds a browser-qa.md topic telling agents to QA user-visible UI changes in a real browser and attach before/after screenshots to the tracking artefact.

  • Trigger: any change with a user-visible surface rendered in a browser (anything you would cover with UI or e2e tests). Backend-only and CLI changes are exempt.
  • Tooling: phrased as generic browser automation so Codex can follow it too. claude-in-chrome is named as the Claude Code example; other agents use what they have (e.g. Playwright).
  • Screenshots: capture before on the base branch prior to the change and after at the same pages/viewport; name as <area>-before.png / <area>-after.png; keep them out of the working tree; cover default, loading/empty/error, and mobile width where relevant.
  • Attachment: always in the GitHub PR description under a "Before / After" heading; also on the GitHub Issue or Jira ticket when that is the tracking record. Do both when a project tracks in Jira but reviews in GitHub.
  • Honesty: no faking, cropping, or retouching; say when a state can't be reproduced.

Second commit extends the topic after using it on a real ticket (a chart timeframe bug where a click did nothing):

  • Where to capture: try the local dev stack first for both halves of the pair (base-branch or pinned release image for before, the fixed build for after); staging/production only when local can't reproduce the state.
  • Videos for interactions: when the change or bug is a sequence, record a scripted before/after video pair: frames per step, the target highlighted with a ring and cursor before each click, two-line captions (action + live page state), a BEFORE/AFTER tag on every frame, assembled with ImageMagick and ffmpeg. Only clicks a real user could make.
  • Tooling split: prefer the cmux browser CLI for driving and capturing; use claude-in-chrome for uploading evidence to GitHub since it holds the signed-in session. Jira attachments via one REST call, referenced as [^name] from the comment.

The topic is registered in the Makefile TOPIC_FILES list (appended after code-comments.md), the README layout tree, and the three explicit enumerations in tests/apply.bats.

Test plan

  • make test — all 13 Bats tests pass
  • make apply — ~/.claude/CLAUDE.md imports browser-qa.md and .agents/AGENTS.md contains the topic text

🤖 Generated with Claude Code

gsdevme and others added 2 commits October 12, 2026 11:20
Tell agents to verify user-visible UI changes in a real browser, capture
before/after screenshots, and attach them to the GitHub PR, GitHub Issue,
or Jira ticket that tracks the work. Phrased as generic browser automation
so Codex can follow it too.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…capture

Screenshots cannot show that a click did nothing, so interaction bugs get a
scripted before/after video pair: frames captured per step, the target
highlighted before each click, two-line captions carrying the action and the
live page state, a BEFORE/AFTER tag on every frame, assembled with
ImageMagick and ffmpeg.

Prefer the cmux browser CLI for driving and capturing, and claude-in-chrome
for attaching the evidence to GitHub (it holds the user's signed-in session).
Attachment notes cover GitHub's comment-box upload and Jira's [^name]
references.

Also add a "Where to capture" section: try the local dev stack first for
both halves of the pair and fall back to staging or production only when
local cannot reproduce the state.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@gsdevme
gsdevme marked this pull request as ready for review October 29, 2026 12:34
@gsdevme
gsdevme merged commit 6f30178 into main Oct 29, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant