qa-skills 3.0.0

package/skills/qa-testcase-from-ui/references/visual-analysis-guide.md

@@ -0,0 +1,146 @@
+# Visual Analysis Guide for UI Screenshots
+
+Guide for analyzing UI screenshots to identify elements, infer semantics, and derive test scenarios. Use when processing images for qa-testcase-from-ui.
+
+---
+
+## Element Identification Techniques
+
+### 1. Shape and Layout Heuristics
+
+| Visual Pattern | Likely Element | Confidence |
+|----------------|----------------|------------|
+| Rounded rectangle with placeholder text | Text input | High |
+| Small square with checkmark | Checkbox | High |
+| Circle with dot | Radio button | High |
+| Rectangle with dropdown arrow | Select/dropdown | High |
+| Rounded rectangle, filled, with label | Button | High |
+| Grid of rows and columns | Table | High |
+| Overlay with centered content | Modal/dialog | High |
+| Horizontal row of links with separators | Navigation bar | Medium |
+| Vertical list with indentation | Tree or nested menu | Medium |
+
+### 2. Label and Context Clues
+
+- **"Email", "Password", "Username"** → Form fields with implied validation
+- **"Submit", "Save", "Cancel"** → Button actions
+- **"Sign In", "Log in"** → Auth flow entry
+- **"Search"** → Search input or button
+- **"Add", "+", "New"** → Create action
+- **"Edit", "Delete", trash icon** → CRUD actions
+- **"Settings", gear icon** → Configuration/settings
+- **"Help", "?"** → Help or documentation
+
+### 3. Position Conventions
+
+- **Top of viewport:** Logo, primary nav, search
+- **Center:** Main content, forms, modals
+- **Bottom:** Submit buttons, footer links
+- **Right edge:** Sidebar, secondary actions
+- **Floating:** Notifications, tooltips
+
+---
+
+## Semantic Mapping Rules
+
+### From Visual to Action
+
+1. **Input-like shapes** → User can type or select
+2. **Button-like shapes** → User can click to trigger action
+3. **Links (underlined or distinct color)** → Navigation
+4. **Overlays** → Modal flow (open → interact → close)
+5. **Tables** → Data display + possible sort/filter/pagination
+6. **Tabs** → Switch between views/panels
+
+### Inferring Validation
+
+- **Required indicator** (asterisk, "Required") → Empty submit should show error
+- **Format hints** (e.g., "DD/MM/YYYY") → Invalid format should be rejected
+- **Character counter** → Max length validation
+- **Password strength meter** → Password rules apply
+
+### Inferring State
+
+- **Disabled** (grayed out, reduced opacity) → Not clickable
+- **Loading** (spinner, skeleton) → Async operation in progress
+- **Error** (red border, error icon) → Validation failed
+- **Success** (green check, success message) → Operation completed
+
+---
+
+## Common UI Patterns
+
+### Login / Auth Screens
+
+- Email + Password inputs
+- "Sign In" / "Log in" button
+- "Forgot password?" link
+- "Create account" / "Register" link
+- Social login buttons (Google, etc.)
+
+**Test focus:** Valid/invalid credentials, empty fields, forgot password flow.
+
+### Dashboard / List Views
+
+- Table or card grid
+- Search/filter bar
+- "Add" or "Create" button
+- Row/card actions (edit, delete)
+- Pagination or infinite scroll
+
+**Test focus:** CRUD, search, filter, sort, pagination.
+
+### Form Pages (Create/Edit)
+
+- Multiple form fields
+- Required indicators
+- Submit and Cancel buttons
+- Possible "Save draft" or "Reset"
+
+**Test focus:** Validation, submission, cancel, reset.
+
+### Settings / Configuration
+
+- Tabs or sidebar sections
+- Toggles, checkboxes, inputs
+- "Save" or "Apply" button
+- Possible "Reset to default"
+
+**Test focus:** Toggle states, save, reset, section navigation.
+
+---
+
+## Edge Cases to Consider
+
+| Scenario | When to Include |
+|----------|-----------------|
+| Empty input submit | Form with required fields |
+| Invalid format | Email, date, phone inputs |
+| Max length exceeded | Inputs with character limits |
+| Modal ESC/backdrop | Any modal/dialog |
+| No results | Search, filter, or list views |
+| Loading state | Any async action (submit, fetch) |
+| Disabled state | Buttons that depend on form validity |
+| Responsive collapse | Nav, sidebar, tables on small screens |
+
+---
+
+## Coordinate and Reference Conventions
+
+When describing element location for test cases:
+
+1. **Prefer semantic description** over coordinates: "Email input, top of form" vs "x:120, y:200"
+2. **Use relative terms:** "Center of modal", "First row of table", "Primary CTA button"
+3. **Include labels:** "Button labeled 'Submit'", "Input with placeholder 'Search'"
+4. **Note ambiguity:** "Possible dropdown (chevron visible)" when uncertain
+
+---
+
+## Limitations
+
+- **Static images** do not reveal dynamic behavior (e.g., API errors, real-time validation)
+- **Design vs implementation** — Figma/mockups may differ from built UI
+- **Overlapping elements** — Hard to distinguish without interaction
+- **Custom components** — May not match standard patterns; use conservative labels
+
+When in doubt, flag elements for manual verification and suggest live capture for implementation-level tests.

package/skills/qa-testcase-from-ui/templates/test-case-template.md

@@ -0,0 +1,31 @@
+# Test Case
+
+## [TC-{ID}] {Title}
+
+**Module:** {module name}
+**Priority:** {P1 | P2 | P3 | P4}
+**Type:** {Functional | Regression | Smoke | Integration | E2E | Other}
+
+## Preconditions
+{Prerequisites, data state, environment setup}
+
+## Test Steps
+
+| # | Action | Expected Result |
+|---|--------|-----------------|
+| 1 | {action} | {expected} |
+| 2 | {action} | {expected} |
+| 3 | {action} | {expected} |
+
+## Postconditions
+{Cleanup, state after test}
+
+## Test Data
+{Input values, test accounts, sample data}
+
+## Traceability
+- **Requirement ID:** [REQ-{ID}]
+- **Spec Reference:** {section or link}
+
+## Automation Status
+{Manual | Automated | Planned | N/A}

package/skills/qa-visual-regression-writer/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: qa-visual-regression-writer
+description: Generate visual regression tests using Playwright screenshots, Percy, and BackstopJS for screenshot comparison, layout drift detection, and baseline management.
+output_dir: tests/visual
+---
+
+# QA Visual Regression Writer
+
+## Purpose
+
+Write visual regression tests to detect unintended UI changes. Transform test cases and visual checkpoints into executable visual tests using Playwright built-in screenshots, Percy (cloud-based), or BackstopJS (Docker-based).
+
+## Trigger Phrases
+
+- "Write visual regression tests for [page/component]"
+- "Generate screenshot comparison tests"
+- "Create visual tests with Playwright toHaveScreenshot"
+- "Add Percy visual tests for [flow]"
+- "BackstopJS visual regression for [viewports]"
+- "Visual tests for layout drift detection"
+- "Screenshot baseline tests for [feature]"
+- "Mask dynamic content in visual tests"
+- "Visual regression with viewport variations"
+
+## Tools
+
+| Tool | Approach | Best For |
+|------|----------|----------|
+| **Playwright** | Built-in `toHaveScreenshot()` | Local baselines, CI, no extra services |
+| **Percy** | Cloud-based, BrowserStack integration | Cross-browser, team review, CI integration |
+| **BackstopJS** | Docker, configurable viewports | Multi-viewport, config-driven scenarios |
+
+## Workflow
+
+1. **Read test cases** — From qa-testcase-from-docs, qa-testcase-from-ui, or manual specs
+2. **Define visual checkpoints** — Identify pages/elements to capture
+3. **Set baselines** — Initial capture; store reference images
+4. **Generate visual tests** — Produce test scripts with assertions
+5. **Configure thresholds** — maxDiffPixels, maxDiffPixelRatio, or tool-specific settings
+
+## Key Patterns
+
+- **Full page screenshots** — `expect(page).toHaveScreenshot()`
+- **Element screenshots** — `expect(locator).toHaveScreenshot()`
+- **Viewport variations** — Desktop, tablet, mobile (1280x720, 768x1024, 375x667)
+- **Dynamic content masking** — Mask timestamps, avatars, ads, animations
+- **Animation disabling** — `page.addStyleTag` or `prefers-reduced-motion` for stable captures
+- **Threshold configuration** — Tune sensitivity to avoid false positives
+
+See `references/patterns.md` for screenshot strategies, masking, viewports, thresholds.
+
+## Baseline Management
+
+| Phase | Action |
+|-------|--------|
+| **Initial capture** | Run tests with `--update-snapshots` (Playwright) or `backstop approve` |
+| **Update workflow** | Review diffs → approve intentional changes → commit baselines |
+| **Review process** | Percy: dashboard review; BackstopJS: HTML report; Playwright: diff artifacts |
+
+See `references/best-practices.md` for baseline management and CI integration.
+
+## Playwright Integration
+
+```typescript
+// Full page
+await expect(page).toHaveScreenshot('homepage.png');
+
+// Element
+await expect(page.getByTestId('header')).toHaveScreenshot('header.png');
+
+// With options
+await expect(page).toHaveScreenshot('dashboard.png', {
+  mask: [page.locator('.timestamp'), page.locator('.avatar')],
+  maxDiffPixels: 100,
+  maxDiffPixelRatio: 0.01,
+  fullPage: true,
+});
+```
+
+- **expect(page).toHaveScreenshot(name)** — Full page or viewport
+- **expect(locator).toHaveScreenshot(name)** — Element-only
+- **maxDiffPixels / maxDiffPixelRatio** — Tolerance for minor rendering differences
+- **mask** — Hide dynamic regions from comparison
+
+See `references/config.md` for Playwright screenshot config.
+
+## Percy Integration
+
+```typescript
+import percySnapshot from '@percy/playwright';
+
+await percySnapshot(page, 'Homepage');
+await percySnapshot(page, 'Dashboard', { widths: [1280, 768, 375] });
+```
+
+- **percySnapshot(page, name)** — Capture and upload to Percy
+- **Percy CLI** — `npx percy exec -- npx playwright test`
+- **BrowserStack Percy** — Cloud review, cross-browser, parallel execution
+
+See `references/config.md` for Percy setup.
+
+## BackstopJS Integration
+
+```javascript
+// backstop.json
+{
+  "scenarios": [
+    {
+      "label": "Homepage",
+      "url": "http://localhost:3000",
+      "viewports": [{ "width": 1280, "height": 720 }]
+    }
+  ]
+}
+```
+
+- **backstop.json** — Scenarios, viewports, selectors, delay
+- **backstop test** — Run comparisons
+- **backstop approve** — Update baselines
+
+See `references/config.md` for BackstopJS configuration.
+
+## Output
+
+- **Visual test scripts** — TypeScript/JavaScript with screenshot assertions
+- **Baseline images** — Stored in `test-results/`, `backstop_data/`, or Percy cloud
+- **Comparison reports** — HTML diff reports, Percy dashboard, Playwright artifacts
+
+## Scope
+
+**Can do (autonomous):**
+- Generate visual regression tests from test case specs
+- Use Playwright toHaveScreenshot, Percy, or BackstopJS
+- Apply masking for dynamic content (timestamps, avatars, ads)
+- Configure viewport variations (desktop/tablet/mobile)
+- Set thresholds (maxDiffPixels, maxDiffPixelRatio)
+- Disable animations for stable captures
+- Create backstop.json scenarios
+
+**Cannot do (requires confirmation):**
+- Add Percy/BackstopJS dependencies without approval
+- Configure Percy project token (user must provide)
+- Override existing baseline images without approval
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npx playwright test`, `backstop test`)
+- Modify production UI code
+- Set up Percy/BrowserStack accounts
+
+## References
+
+- `references/patterns.md` — Screenshot strategies, masking, viewports, thresholds
+- `references/config.md` — Playwright, Percy, BackstopJS configuration
+- `references/best-practices.md` — Baseline management, CI integration, dynamic content
+
+## Quality Checklist
+
+- [ ] Dynamic content masked (timestamps, avatars, ads)
+- [ ] Animations disabled or reduced for stable captures
+- [ ] Viewport variations defined where needed
+- [ ] Thresholds configured to avoid false positives
+- [ ] Baselines stored in version control (Playwright/BackstopJS)
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (Percy token via env)
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Flaky visual diffs | Animations, timestamps, fonts | Mask dynamic regions; disable animations |
+| Too many false positives | Threshold too strict | Increase maxDiffPixels or maxDiffPixelRatio |
+| Baseline mismatch | Different OS/fonts/DPI | Run baselines in CI; use consistent environment |
+| Percy upload fails | Missing token, network | Set PERCY_TOKEN; check Percy dashboard |
+| BackstopJS no match | Wrong reference path | Run `backstop approve` to create baselines |
+| Element screenshot empty | Element not visible | Ensure element in viewport; add wait |

package/skills/qa-visual-regression-writer/references/best-practices.md

@@ -0,0 +1,154 @@
+# Visual Testing Best Practices
+
+Baseline management, CI integration, and dynamic content handling for visual regression testing.
+
+## Baseline Management
+
+### Initial Capture
+
+1. **Ensure stable state** — Disable animations, wait for network idle
+2. **Run with update flag** — `--update-snapshots` (Playwright), `backstop approve` (BackstopJS)
+3. **Commit baselines** — Store reference images in version control (Playwright, BackstopJS)
+4. **Percy** — First run creates baselines automatically
+
+### Update Workflow
+
+| Tool | Update Command | When to Use |
+|------|----------------|-------------|
+| Playwright | `npx playwright test --update-snapshots` | Intentional UI change |
+| BackstopJS | `backstop approve` | Intentional UI change |
+| Percy | Approve in dashboard | After reviewing diff |
+
+### Review Process
+
+1. **Run tests** — Detect visual changes
+2. **Review diffs** — Playwright: `test-results/`, BackstopJS: `backstop_data/html_report/`
+3. **Decide** — Intentional → approve; Bug → fix code
+4. **Update** — Only approve when change is correct
+
+### Baseline Hygiene
+
+- **One baseline per viewport** — Don't mix viewports
+- **Meaningful names** — `homepage-desktop.png` not `screenshot1.png`
+- **Avoid bloating** — Capture only critical pages/elements
+- **Branch strategy** — Baselines on main; feature branches compare against main
+
+## CI Integration
+
+### Playwright in CI
+
+```yaml
+# GitHub Actions
+- name: Run visual tests
+  run: npx playwright test visual/
+  env:
+    CI: true
+
+- name: Update snapshots (on main, when approved)
+  if: github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch'
+  run: npx playwright test visual/ --update-snapshots
+```
+
+### Percy in CI
+
+```yaml
+- name: Percy snapshots
+  run: percy exec -- npx playwright test
+  env:
+    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
+    PERCY_BRANCH: ${{ github.ref_name }}
+```
+
+### BackstopJS in CI
+
+```yaml
+- name: Backstop test
+  run: npx backstop test
+- name: Upload report
+  uses: actions/upload-artifact@v4
+  with:
+    name: backstop-report
+    path: backstop_data/html_report
+```
+
+### Fail on Diff
+
+- **Playwright:** Fails by default when diff exceeds threshold
+- **Percy:** Fails when unapproved diffs exist (configurable)
+- **BackstopJS:** Fails when `misMatchThreshold` exceeded
+
+## Dynamic Content Handling
+
+### Strategy Hierarchy
+
+1. **Mask** — Hide dynamic regions (timestamps, avatars)
+2. **Stub** — Replace with static data (API mocking)
+3. **Wait** — Ensure content loaded before capture
+4. **Ignore** — Increase threshold if unavoidable
+
+### API Mocking for Consistency
+
+```typescript
+test('dashboard visual', async ({ page }) => {
+  await page.route('**/api/user', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ name: 'Test User', avatar: '/static/avatar.png' }),
+    })
+  );
+  await page.goto('/dashboard');
+  await expect(page).toHaveScreenshot('dashboard.png');
+});
+```
+
+### Deterministic Data
+
+- Use fixed dates in test data
+- Seed database with known state
+- Mock external services (maps, analytics)
+
+### Font and Rendering Consistency
+
+- **Same OS in CI** — Use Linux in CI if baselines from Linux
+- **System fonts** — Or bundle fonts to avoid OS differences
+- **Threshold** — Use `maxDiffPixelRatio` for subpixel tolerance
+
+## Test Organization
+
+### Structure
+
+```
+visual/
+  homepage.spec.ts
+  login.spec.ts
+  __snapshots__/
+    homepage.spec.ts-snapshots/
+      homepage-chromium.png
+      homepage-mobile-chromium.png
+```
+
+### Naming Conventions
+
+- **Page:** `{page-name}-{viewport}.png`
+- **Element:** `{element}-{state}.png` (e.g., `modal-open.png`)
+- **Scenario:** Descriptive; avoid numbers
+
+### Scope
+
+- **Critical paths** — Login, checkout, key flows
+- **High-traffic pages** — Homepage, product pages
+- **Layout-sensitive** — Responsive breakpoints
+- **Avoid** — Low-value pages, rarely changed UI
+
+## Performance
+
+- **Parallelize** — Playwright and Percy support parallel runs
+- **Limit viewports** — Test 2–3 key breakpoints, not every device
+- **Lazy capture** — Only capture when test reaches checkpoint
+- **Cache baselines** — CI cache `__snapshots__` / `backstop_data` when appropriate
+
+## Security
+
+- **No secrets in screenshots** — Mask tokens, passwords, PII
+- **Percy token** — Store in CI secrets, never commit
+- **Test URLs** — Use staging/test envs, not production with real data