Skip to main content
skill CX Codex

visual-testing-advanced — Claude Code skill: what it does

visual-testing-advanced runs pixel-level visual regression suites, responsive viewport checks, and AI diff analysis to catch broken layouts early.

MIT 163 installs ★ 533 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill visual-testing-advanced -a claude-code
Open on GitHub

What visual-testing-advanced does

This skill guides coding agents through automated UI regression workflows using qe-visual-tester, qe-test-executor, and qe-quality-gate. Its default path drives Vibium (WebDriver BiDi) via the qe-browser companion skill. Baselines get stored inside .aqe/visual-baselines/, while comparisons execute through node .claude/skills/qe-browser/scripts/visual-diff.js. Because mismatches return a non-zero exit code based on the threshold flag, the process plugs directly into CI gating steps.

When a suite requires cross-browser rendering in Firefox and WebKit, the skill switches to a Playwright fallback. Since Vibium currently targets Chrome only, Playwright remains necessary for multi-engine coverage. The fallback also covers element masking for dynamic blocks like timestamps and counters, along with Percy snapshots to bypass anti-aliasing artifacts.

Responsive runs test layouts across predefined device widths, from mobile viewports to desktop resolutions. Diff runs can target entire pages or focus strictly on individual components using CSS selectors.

What it helps with

  • detect unintended layout shifts or typography regressions across viewports
  • mask volatile DOM nodes like timestamps and ad containers before taking snapshots
  • run automated pixel diff comparisons against saved baseline screenshots
  • halt continuous integration pipelines whenever visual changes exceed allowed thresholds

Example prompts for the agent

  • Run visual regression testing on the homepage across mobile and desktop breakpoints
  • Create a baseline screenshot for the hero component using selector #hero
  • Configure Playwright to mask .avatar and .timestamp selectors during snapshot capture

How to install visual-testing-advanced

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill visual-testing-advanced -a claude-code

2Manually: put the files in place

~/.claude/skills/visual-testing-advanced/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/visual-testing-advanced/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about visual-testing-advanced

How to install visual-testing-advanced in Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill visual-testing-advanced -a claude-code in your terminal.

What does visual-testing-advanced do?

It equips the agent with recipes and scripts to capture UI baselines, compare screenshots pixel-by-pixel, and validate responsive layouts.

When should Playwright be used instead of Vibium?

Choose Playwright if you must test in Firefox or WebKit, or if you need Percy semantic diffing to filter out minor font rendering changes.

Source text

SKILL.md · MIT
---
name: visual-testing-advanced
description: "Advanced visual regression testing with pixel-perfect comparison, AI-powered diff analysis, responsive design validation, and cross-browser visual consistency. Use when detecting UI regressions, validating designs, or ensuring visual consistency."
category: specialized-testing
priority: high
tokenEstimate: 900
agents: [qe-visual-tester, qe-test-executor, qe-quality-gate]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-02
dependencies: []
quick_reference_card: true
tags: [visual, regression, screenshot, pixel-diff, percy, playwright, responsive]
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/visual-testing-advanced.yaml
---

# Advanced Visual Testing

<default_to_action>
When detecting visual regressions or validating UI:
1. CAPTURE baseline screenshots (first run establishes baseline)
2. COMPARE new screenshots against baseline (pixel-by-pixel or AI)
3. MASK dynamic content (timestamps, ads, user counts)
4. TEST across devices (desktop, tablet, mobile viewports)
5. REVIEW and approve intentional changes, fail on regressions

**Quick Visual Testing Steps:**
- Set up baseline on main branch
- Compare feature branch against baseline
- Mask dynamic elements (timestamps, avatars)
- Use AI-powered comparison to reduce false positives
- Integrate in CI/CD to block visual regressions

**Critical Success Factors:**
- Functional tests don't catch visual bugs
- AI-powered tools reduce false positives
- Review diffs, don't just auto-approve
</default_to_action>

## Quick Reference Card

### When to Use
- UI component changes
- CSS/styling modifications
- Responsive design validation
- Cross-browser consistency checks

### Visual Bug Types
| Bug Type | Description |
|----------|-------------|
| Layout shift | Elements moved position |
| Color change | Unintended color modification |
| Font rendering | Typography issues |
| Alignment | Spacing/alignment problems |
| Missing images | Broken image paths |
| Overflow | Content clipping |

### Comparison Algorithms
| Algorithm | Best For |
|-----------|----------|
| **Pixel diff** | Exact match requirement |
| **Structural similarity** | Handle anti-aliasing |
| **AI semantic** | Ignore insignificant changes |

---

## PRIMARY PATH: qe-browser visual-diff

**Most visual regression work should go through the `qe-browser` fleet skill.** It wraps Vibium (WebDriver BiDi) and provides pixel-diff against stored baselines with threshold enforcement and diff-image output. See `.claude/skills/qe-browser/SKILL.md`.

```bash
# Navigate
vibium go https://example.com
vibium wait load

# First run — creates baseline in .aqe/visual-baselines/homepage.png
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage

# Subsequent runs — compare, non-zero exit on mismatch
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --threshold 0.02

# Scope to a single region
node .claude/skills/qe-browser/scripts/visual-diff.js --name hero --selector "#hero"

# Responsive — run diff at each breakpoint
for viewport in "375 667" "768 1024" "1920 1080"; do
  read w h <<< "$viewport"
  vibium viewport $w $h
  node .claude/skills/qe-browser/scripts/visual-diff.js --name "homepage-${w}x${h}"
done

# Reset baseline after an intentional design change
node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --update-baseline
```

Baselines live in `.aqe/visual-baselines/`. The script uses `pixelmatch` when installed, with a hash-based exact-match fallback otherwise. Non-zero exit when similarity < `1 - threshold`, so CI gating is `$?`-based.

### When to keep Playwright visual regression

Use the Playwright recipe below only when you need:
- **AI semantic comparison** (Percy, Applitools) to ignore insignificant pixel drift
- **Cross-browser rendering checks** in Firefox/WebKit (Vibium is Chrome-only today)
- **Tight integration with an existing Playwright test suite**

---

## LEGACY: Visual Regression with Playwright (fallback)

```javascript
import { test, expect } from '@playwright/test';

test('homepage visual regression', async ({ page }) => {
  await page.goto('https://example.com');

  // Capture and compare screenshot
  await expect(page).toHaveScreenshot('homepage.png');
  // First run: saves baseline
  // Subsequent runs: compares to baseline
});

test('responsive design', async ({ page }) => {
  // Mobile viewport
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('homepage-mobile.png');

  // Tablet viewport
  await page.setViewportSize({ width: 768, height: 1024 });
  await expect(page).toHaveScreenshot('homepage-tablet.png');
});
```

---

## Handling Dynamic Content

```javascript
test('mask dynamic elements', async ({ page }) => {
  await page.goto('https://example.com');

  await expect(page).toHaveScreenshot({
    mask: [
      page.locator('.timestamp'),     // Dynamic time
      page.locator('.user-count'),    // Live counter
      page.locator('.advertisement'), // Ads
      page.locator('.avatar')         // User avatars
    ]
  });
});
```

---

## AI-Powered Visual Testing (Percy)

```javascript
import percySnapshot from '@percy/playwright';

test('AI-powered visual test', async ({ page }) => {
  await page.goto('https://example.com');

  // Percy uses AI to ignore anti-aliasing, minor font differences
  await percySnapshot(page, 'Homepage');
});

test('component visual test', async ({ page }) => {
  await page.goto('https://example.com/components');

  // Snapshot specific component
  const button = page.locator('.primary-button');
  await percySnapshot(page, 'Primary Button', {
    scope: button
  });
});
```

---

## Playwright Configuration

```javascript
// playwright.config.js
export default {
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,      // Allow 100 pixel difference
      maxDiffPixelRatio: 0.01, // Or 1% of image
      threshold: 0.2,          // Color similarity threshold
      animations: 'disabled',  // Disable animations
      caret: 'hide'            // Hide cursor
    }
  }
};
```

---

## Agent-Driven Visual Testing

```typescript
// Comprehensive visual regression
await Task("Visual Regression Suite", {
  baseline: 'main-branch',
  current: 'feature-branch',
  pages: ['homepage', 'product', 'checkout'],
  devices: ['desktop', 'tablet', 'mobile'],
  browsers: ['chrome', 'firefox', 'safari'],
  threshold: 0.01
}, "qe-visual-tester");

// Returns:
// {
//   comparisons: 27,  // 3 pages × 3 devices × 3 browsers
//   differences: 2,
//   report: 'visual-regression-report.html'
// }
```

---

## Agent Coordination Hints

### Memory Namespace
```
aqe/visual-testing/
├── baselines/*          - Baseline screenshots
├── comparisons/*        - Diff results
├── components/*         - Component snapshots
└── reports/*            - Visual regression reports
```

### Fleet Coordination
```typescript
const visualFleet = await FleetManager.coordinate({
  strategy: 'visual-testing',
  agents: [
    'qe-visual-tester',   // Screenshot comparison
    'qe-test-executor',   // Cross-browser execution
    'qe-quality-gate'     // Block on visual regressions
  ],
  topology: 'parallel'
});
```

---

## Related Skills
- [accessibility-testing](../accessibility-testing/) - Visual a11y checks
- [compatibility-testing](../compatibility-testing/) - Cross-browser visuals
- [regression-testing](../regression-testing/) - Regression suite

---

## Remember

**Functional tests don't catch visual bugs.** Layout shifts, color changes, font rendering, alignment issues - all invisible to functional tests but visible to users.

**AI-powered tools reduce false positives.** Percy, Applitools use AI to ignore insignificant differences (anti-aliasing, minor font rendering).

**With Agents:** `qe-visual-tester` automates visual regression across browsers and devices, uses AI to filter noise, and generates visual diff reports. Catches UI regressions before users see them.

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
brutal-honesty-review The brutal-honesty-review skill guides an agent through blunt reviews of code, tests, and technical decisions. It asks what is broken, why it matters, and how to fix it. CX Codex +1 186installs mobile-testing mobile-testing — a skill for testing iOS and Android apps: gestures, sensors, permissions, device fragmentation, and performance. CX Codex +1 177installs n8n-workflow-testing-fundamentals n8n-workflow-testing-fundamentals — a skill for testing n8n workflows: validates structure, nodes, data flows, error handling, and execution performance of automation workflows. CX Codex +1 176installs n8n-security-testing n8n-security-testing scans n8n workflows for leaked credentials, checks credential encryption, and tests webhook authentication. CX Codex +1 176installs pr-review The pr-review skill reviews GitHub PRs for scope, trust-tier assignments, code quality, and security. Use it to prepare clear feedback with actionable next steps. CX Codex +1 155installs agentic-quality-engineering The agentic-quality-engineering skill organizes AI agents around testing, risk analysis, and quality checks. It uses PACTS principles to guide coordination and agent selection. CX Codex +1 153installs security-testing security-testing is a Claude Code skill that checks projects for vulnerabilities using the OWASP Top 10 approach. It activates for auth audits, injection testing, and security automation. CX Codex +1 152installs pentest-validation pentest-validation validates SAST and DAST scanner findings against non-production targets, filters out false alarms, and produces PoC exploit proof. CX Codex +1 147installs

Project sponsors

Companies that keep this analytics open