common-web-visual-testing git:20260914.43f160bA

Immutable. This exact content is served forever at /api/v1/blob/87400640d7210916.

---
name: common-web-visual-testing
description: Standardizes visual audits, responsive design, and behavioral testing for web apps. Use to verify a web UI fix or cross-browser behavior; defer backend API refactors, Playwright installation/tooling setup, and Appium/mobile automation.
metadata:
  triggers:
    keywords:
      - web test
      - browser test
      - responsive audit
      - verify web ui
      - cross-browser check
      - web accessibility
---

# 🌐 Web Visual & Behavioral Testing

## **Priority: P1 (HIGH)**

> [!IMPORTANT]
> **Tier 2 (Methodology)**: Strategy web UI/UX audit.
> **Tier 3 (Domain)**: Responsive, A11y (WCAG), Browser Engine quirk.

## 🧪 Testing Mindset (Comparative Audit)

Visual test best as **Comparative Audit** loop:

1.  **Baseline (Before)**: Capture `snapshot --aria` + `screenshot` prod/main.
2.  **Implementation (After)**: Capture same local/feature.
3.  **Audit**: Compare state for regression, CLS, Aria drift.

Responses must label the two captures as **Before** and **After** (or Baseline and Fixed) and include the diff and neighboring-element side-effect check.

## 📋 Scenario Matrix

| Change Type       | Scenarios to Run                                   |
| :---------------- | :------------------------------------------------- |
| **CSS/Layout**    | Responsive Audit + Hover + CLS Check               |
| **Forms/Input**   | Validation Msg + Focus State + Error Boundary      |
| **Navigation**    | URL Sync + Sticky Header + Back-Button Persistence |
| **Assets/Fonts**  | Lazy Load + Icon Check + LCP Audit                 |
| **Accessibility** | Tab Order + Aria-Snapshot + Color Contrast         |

## 🚫 Anti-Patterns

- **Single-Viewport**: Never verify Desktop only. Check Mobile (375px) + Tablet (768px).
- **Ignore Layout Shift**: Check loading state (skeleton) → no page jump.
- **Unmasked Dynamic**: **MUST** mask timestamp/balance via `--mask` or JS (`opacity: 0`). Avoid "False Regression".
- **Blind Assertion**: Use `playwright-cli snapshot --aria` (CLI) or `browser_snapshot` (Playwright MCP) verify state before done.

## 📁 Evidence

Before/After pairs live in `.playwright-cli/<session>/` as `<AC|step>-before.png` / `<AC|step>-after.png` plus matching `.aria.txt`. Driver rung and dir go in the walkthrough `driver:` / `evidence_dir:` lines.
- **External Dependency**: Mock/bypass 3rd-party (Chat, Analytics) → prevent flakiness.

## 🔗 References

- **playwright-cli**: [playwright-cli](../../quality-engineering/quality-engineering-playwright-cli/SKILL.md)
- **Driver Ladder**: [driver-ladder](../../quality-engineering/quality-engineering-playwright-cli/references/driver-ladder.md) — CLI first, Playwright MCP fallback, BLOCKED rule.
- **Diagnostic Decoder**: [diagnostic-decoder](references/diagnostic-decoder.md)
- **DOM vs Screenshot**: [dom-snapshot-vs-screenshot](references/dom-snapshot-vs-screenshot.md)
- **Login & Data**: [login-and-test-data](references/login-and-test-data.md)
- **Scenario Details**: [scenarios](references/scenarios.md)