A screenshot diff is an observation, not a defect verdict. Fonts, viewport, data, animation, browser rendering, and intentional design changes all determine whether the comparison is meaningful.
Why this Skill is needed
The Visual Regression Testing Skill designs VRT-## candidates around baselines, viewports, fonts, data, diff thresholds, intentional changes, and prior diffs. It does not execute visual tests or turn a baseline file into pass evidence.
What the Skill does
A meaningful visual diff needs a controlled baseline and an intentional-change decision.
Use this Skill to define visual regression candidates and comparison conditions for pages or components. It makes selection rationale, applicability, evidence gaps, and the smallest validation action explicit.
A good VRT finding names the visual subject, baseline version, viewport and browser, font and data conditions, expected change, diff concern, owner, close condition, and validation method.
Use it when a design-system change, responsive layout change, localization update, or screenshot pipeline needs a defensible visual comparison.
What it does not do
The Visual Regression Testing Skill can organize material, evidence, and next actions for Visual candidate. It does not replace:
- Confirmation of rules, scope, and risk by the accountable domain owner.
- A real environment, account, dataset, log, or run record; static analysis does not become runtime evidence by itself.
- Authorization for release, compliance, production actions, or residual-risk acceptance.
- A Human decision when supplied sources conflict.
What it checks
The value of this Skill is not another keyword list. It connects each focus area to an observable input, a judgment, and a way to close the loop. Start with a small matrix based on the source Skill’s output contract:
| Focus | Question before analysis | Handoff output |
|---|---|---|
| Visual candidate | Page/component, state, variant, and risk | VRT ID and source |
| Comparison condition | Baseline, viewport, browser, font, locale, and data | Applicability |
| Diff judgment | Expected, unexplained, or unassessed change | Intent and evidence |
| Validation action | Smallest screenshot or review check | Owner and NOT_RUN state |
If a row has only a conventional expectation and no source or validation method, keep it open instead of turning it into a pass.
Audit inputs before you start
Before analyzing Visual candidate, classify the input into six evidence states. A gap is not automatically a failure, but it must not disappear inside the conclusion.
| State | Meaning | How this Skill should handle it |
|---|---|---|
| known | Directly supported by the supplied material | Keep the source, version, and time with the judgment |
| missing | Needed for this pass but not supplied | Name the smallest evidence action and limit the conclusion |
| conflicting | Sources disagree | Show both sources and route the conflict to an owner |
| stale | Present but outside the relevant version or time window | Mark freshness; old evidence is not current proof |
| out_of_scope | Related but excluded from this pass | Keep the boundary explicit |
| assumptions | Temporarily adopted to continue analysis | State how and when the assumption will be checked |
Keep the input version, scope, environment, evidence locations, and accountable owner together. Without a run record, deliver analysis, design, or a validation plan—not an execution pass.
From problem to structured Finding
Connect the source, scope, evidence state, analysis, owner, action, close condition, and validation before writing the conclusion. The case below keeps this Skill’s identifier and domain context.
Keep the decision layers separate
For Visual candidate, do not compress four different kinds of language into “recommended to pass”:
| Layer | How to write it | Application here |
|---|---|---|
| Fact | What the supplied material directly shows | Cite the source, version, input, or run record for the focus |
| Evidence-backed Inference | What several facts support together | Show the inference chain and retain uncertainty |
| Recommendation | The smallest next action | Name the evidence, review, execution, or regression path |
| Human Decision | What an accountable person must decide | Leave scope, risk acceptance, resources, and release meaning to the owner |
A complete case
This case follows Input, Analysis, Finding, Decision, and Validation. When material is incomplete, keep missing, conflicting, or assumptions visible instead of turning them into a pass.
Input
| Material | What to provide | What to do when it is missing |
|---|---|---|
| Page and component inventory | Critical pages, states, themes, and component variants | Keep missing states unassessed |
| Baseline conditions | Revision, viewport, browser, fonts, locale, timezone, and data | Do not compare unlike conditions |
| Expected change | Design change, approved intent, and affected scope | Separate intended from unexplained |
| Diff evidence | Screenshot, threshold, region, history, and review owner | A diff file is not a verdict |
Use a request like this:
Use the visual-regression-testing Skill.
Task: Prepare visual regression candidates for a dashboard theme change across light mode, dark mode, compact viewport, and Chinese locale.
Inputs: [page inventory, baseline screenshots, design diff, fonts, data fixtures, browser matrix, threshold policy]
Scope: [dashboard cards, tables, empty and error states]
Constraints: [do not execute screenshots or approve diffs]
Produce VRT-## findings with subject, conditions, expected change, concern, evidence state, owner, close condition, and validation method.Analysis
Use the input, matrix, and evidence state to form the judgment before writing the Finding; keep missing material as a gap.
Finding
Focused example: Review a theme change without blaming the font
A dark-mode diff shows text wrapping changes in a dashboard table, but the baseline used a different font fallback and data length. The Skill should separate font and fixture variance from the intended theme change, request controlled baseline conditions, and keep the diff unassessed until comparison inputs match.
The output designs visual comparison candidates. It cannot prove a visual defect, pixel-perfect quality, accessibility, or release readiness without controlled screenshots and Human review.
Example finding: turn one problem into a handoff
The field example below shows the recording pattern; it is not an execution result.
If the supplied material cannot prove that Visual candidate meets its contract, write the finding like this. It does not invent the missing rule or turn missing evidence into a failure.
| Field | Example wording |
|---|---|
| Source and scope | Record the requirement, version, environment, and the concrete object for Visual candidate |
| Finding | The condition or result for Visual candidate is not yet traceable to evidence |
| Evidence state | missing / assumptions; use conflicting when sources disagree |
| Impact and priority | Name the affected user, journey, or delivery decision without inflating severity |
| Owner and Human decision | Ask the product, engineering, security, or test owner to confirm the rule and trade-off |
| Action and close condition | Add the smallest missing evidence; close only when source, judgment, and owner can be reviewed |
| Validation | Name one repeatable check, query, or run and retain the raw artifact |
The point is to let the next person walk from the finding back to the source and run an action that can change the decision.
Decision
The accountable owner confirms the decision question and risk trade-off; the Skill does not make that choice.
Validation
Before closing the finding, run the stated validation and retain the raw artifact. Without an execution record, the status remains unverified.
How a Finding enters the next stage
Handoff output
| Output field | Why it exists | Example status |
|---|---|---|
| Visual candidate | Page/component, state, variant, and risk | VRT ID and source |
| Comparison condition | Baseline, viewport, browser, font, locale, and data | Applicability |
| Diff judgment | Expected, unexplained, or unassessed change | Intent and evidence |
| Validation action | Smallest screenshot or review check | Owner and NOT_RUN state |
Every conclusion should point to a source, evidence state, and next action. If evidence is missing, use pending, blocked, unassessed, or NOT_SCORED instead of filling the gap with confidence.
Next-stage route
At minimum, hand off the source, evidence state, owner, close condition, and validation action; the next-stage conclusion remains bounded by the evidence state.
How to prepare better input
Provide baseline revision, page states, viewport and browser, fonts, locale, timezone, data fixtures, threshold policy, intentional design scope, and review owner. Missing conditions stay blocked or unassessed.
A useful handoff includes input versions, scope, time window, evidence index, assumptions, Human decision boundary, and the smallest validation action.
Working with other Skills
- UI Test Strategy:selects journeys, states, platforms, and risk.
- Cross-Browser Testing:adds browser-specific rendering scope.
- UI Test Selector Review:covers behavior selectors rather than pixels.
Common traps
- Comparing screenshots with different fonts, data, viewport, or locale.
- Treating every pixel diff as a product defect.
- Updating baselines to make a pipeline green before understanding the change.
Install and invoke
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/visual-regression-testing -gUse the visual-regression-testing Skill.
Include objective, scope, versions, evidence paths, constraints, and decision boundary.
Audit inputs first, preserve evidence states, and finish with owner, close condition, and validation method.FAQ
Should the diff threshold be one global number?
Not necessarily. Thresholds depend on rendering noise, region, component, and the cost of missed visual change.
Can an approved design change be auto-accepted?
Only within a defined scope and review rule. Intentional change still needs baseline update evidence.
The Skill is most useful when attached to one real project artifact and kept with its source evidence. Start narrow, validate the uncertain part, and expand only when evidence supports it.
References
Source Skill and execution contract
The complete execution contract lives in Visual Regression Testing prompt. The source directory may also contain evaluation cases and supporting material.
Static plans, file presence, and dry runs keep their evidence state. They do not become runtime proof, an all-passed claim, or release approval.
Reference links
- Visual Regression Testing prompt:https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/visual-regression-testing/prompts/visual-regression-testing.md
- Visual Regression Testing Skill source:https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/visual-regression-testing
- Visual Regression Testing details:https://inaodeng.com/en/qaskills/visual-regression-testing/
- Awesome QA Skills on GitHub:https://github.com/naodeng/awesome-qa-skills