qa-skills 3.0.0 → 3.1.0

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

@@ -1,146 +0,0 @@
-# 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

@@ -1,31 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
----
-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

@@ -1,154 +0,0 @@
-# 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