What is the visual-testing-advanced skill?
The visual-testing-advanced skill is a SKILL.md in proffesor-for-testing/agentic-qe for visual regression testing. Your AI coding agent captures a baseline, compares new screenshots by pixel diff, masks dynamic content, checks three viewports and fails the run when similarity drops below the threshold.
The visual-testing-advanced skill teaches your agent visual regression testing: capture a baseline on the main branch, compare a feature branch against it, and fail the run when the screenshots differ more than the threshold allows.
It exists because functional tests do not catch visual bugs. Layout shifts, color changes, font rendering problems and clipped content pass functional checks while users still see them.
Five steps the agent follows
- Capture baseline screenshots, where the first run establishes the baseline.
- Compare new screenshots against the baseline, pixel by pixel or with AI.
- Mask dynamic content such as timestamps, ads and user counts.
- Test across desktop, tablet and mobile viewports.
- Review and approve intentional changes, and fail on regressions.
Visual bugs it targets
- Layout shift, where elements move position.
- Color change and font rendering issues.
- Alignment and spacing problems.
- Missing images from broken paths, and overflow that clips content.
Primary path and fallback
Most work goes through the qe-browser visual-diff script, which stores baselines in .aqe/visual-baselines/ and exits non-zero on a mismatch. Percy and Applitools are kept for AI comparison, and Playwright toHaveScreenshot for Firefox and WebKit or an existing Playwright suite.
Who the visual-testing-advanced skill is for
Best for
- Teams changing CSS or components who need a CI gate against visual regressions.
- Responsive design checks at 375x667, 768x1024 and 1920x1080.
- Projects pairing screenshot diffs with the accessibility-testing skill from the same repository.
Not for
- Auditing a rendered interface with browser evidence, which the frontend-visual-qa skill does.
- Capturing consistent before and after screenshot pairs, where the ui-screenshots skill fits.
- Reviewing accessibility rules, which the accessibility-audit skill covers.
How to install Visual Testing Advanced Skill: Baseline Screenshots and Pixel Diffs
npm install -g agentic-qe
cd your-project
aqe init --auto/plugin install agentic-qe-fleet --marketplace proffesor-for-testing/agentic-qe.Check the requirements
The repository requires Node.js 22.13.0 or newer and npm 10.0.0 or newer, and works with the coding agent you already have configured.
Install and initialize
Run the three commands above.
aqe init --autoanalyzes your project and configures the default Claude Code surface, including MCP. Runaqe healthto check the setup.Pick another client if needed
Add a setup flag such as
--with-codex,--with-cursor,--with-copilot,--with-clineor--with-windsurftoaqe init --auto.Ask for a visual regression run
Request a baseline, a diff against it or a responsive check. The skill triggers on detecting UI regressions, validating designs and visual consistency.
Check that it loaded
Ask your agent to run visual regression on your homepage at three viewports. Expect a baseline saved on the first run, then a diff report with a threshold and non-zero exit on mismatch.
Key features
- Baseline workflowThe first run saves a baseline, and later runs compare against it. Baselines are set on the main branch and the feature branch is compared to them.
- qe-browser visual-diffThe visual-diff.js script takes a --name, a --threshold such as 0.02, an optional --selector for one region and --update-baseline to reset after an intentional design change.
- CI gating by exit codeThe script exits non-zero when similarity falls below 1 minus the threshold, so a pipeline can gate on the exit code.
- Pixelmatch with fallbackThe script uses pixelmatch when it is installed, and falls back to a hash-based exact match otherwise.
- Responsive viewportsA loop runs the diff at 375x667, 768x1024 and 1920x1080 with a named baseline per size, such as homepage-375x667.
- Dynamic content masksPlaywright mask locators hide timestamps, live counters, advertisements and avatars so they do not trigger false differences.
- Comparison algorithmsPixel diff suits exact matches, structural similarity handles anti-aliasing, and AI semantic comparison ignores insignificant changes.
- Playwright screenshot configtoHaveScreenshot accepts maxDiffPixels 100, maxDiffPixelRatio 0.01, threshold 0.2, disabled animations and a hidden caret.
- Percy snapshotspercySnapshot captures a full page or a scoped component, and its AI comparison ignores anti-aliasing and minor font differences.
Frequently asked questions
What is the visual-testing-advanced skill?
It is a SKILL.md in the proffesor-for-testing/agentic-qe repository for visual regression testing. Your AI coding agent captures baseline screenshots, compares new ones by pixel diff or AI, masks dynamic content, checks responsive viewports and fails the run when a change exceeds the threshold.
How do I install visual-testing-advanced?
Install the repository CLI with npm install -g agentic-qe, move into your project and run aqe init --auto. It needs Node.js 22.13.0 or newer. For clients other than Claude Code, add a flag such as --with-cursor or --with-codex to the init command.
Where are the baseline screenshots stored?
The qe-browser visual-diff script stores baselines in .aqe/visual-baselines/, for example homepage.png. The first run creates the baseline and later runs compare against it. Add --update-baseline to reset it after an intentional design change, or --selector to compare one region such as #hero.
How does the skill fail a build?
The visual-diff script exits non-zero when similarity falls below 1 minus the threshold. With --threshold 0.02, a similarity under 0.98 fails. A non-zero exit code on mismatch means a CI pipeline can gate on the exit code of the command and block the merge.
How does it handle timestamps and ads?
It masks them. In Playwright, toHaveScreenshot takes a mask list of locators, and the skill shows .timestamp, .user-count, .advertisement and .avatar as examples. The mask list names those locators so dynamic content is hidden from the comparison. Masking dynamic content is the third of the skill's five steps.
When should I use Playwright instead of qe-browser?
Use the Playwright recipe for AI semantic comparison with Percy or Applitools, for cross-browser checks in Firefox and WebKit because Vibium is Chrome-only today, or when you already have a Playwright test suite and want the screenshot tests inside it.
Which viewports does the skill check?
Its loop runs the diff at 375x667 for mobile, 768x1024 for tablet and 1920x1080 for desktop, saving a separate baseline per size, and the baseline name carries the size, such as homepage-1920x1080. The Playwright example sets the same mobile and tablet sizes before calling toHaveScreenshot.
What license does visual-testing-advanced use?
It is MIT licensed. The proffesor-for-testing/agentic-qe repository uses the MIT license, and its GitHub description calls the project the Agentic QE Fleet, an open-source platform that is free to use, fork, build and contribute. The visual-testing-advanced skill lives at assets/skills/visual-testing-advanced.