qa-skills 3.0.0

package/skills/qa-visual-regression-writer/references/config.md

@@ -0,0 +1,220 @@
+# Visual Regression Configuration
+
+Configuration for Playwright screenshots, Percy, and BackstopJS.
+
+## Playwright Screenshot Configuration
+
+### playwright.config.ts
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './visual',
+  snapshotDir: './visual/snapshots',
+  snapshotPathTemplate: '{testDir}/{testFileDir}/__snapshots__/{arg}-{projectName}{ext}',
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100,
+      maxDiffPixelRatio: 0.01,
+    },
+  },
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'retain-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'mobile', use: { ...devices['iPhone 13'] } },
+  ],
+});
+```
+
+### Snapshot Path Template
+
+| Variable | Description |
+|----------|-------------|
+| `{testDir}` | Test directory |
+| `{testFileDir}` | Directory of test file |
+| `{arg}` | Screenshot name |
+| `{projectName}` | Project (browser/viewport) |
+| `{ext}` | `.png` |
+
+### Update Snapshots
+
+```bash
+npx playwright test --update-snapshots
+npx playwright test visual/ --update-snapshots
+```
+
+### Per-Test Override
+
+```typescript
+test('strict comparison', async ({ page }) => {
+  await expect(page).toHaveScreenshot('strict.png', {
+    maxDiffPixels: 0,
+    maxDiffPixelRatio: 0,
+  });
+});
+```
+
+## Percy Configuration
+
+### Installation
+
+```bash
+npm install @percy/cli @percy/playwright --save-dev
+```
+
+### percy.config.js
+
+```javascript
+module.exports = {
+  version: 2,
+  static: {
+    path: 'dist',
+  },
+  discovery: {
+    allowed-hostnames: ['localhost', '127.0.0.1'],
+    disallowed-hostnames: [],
+    network-idle-timeout: 750,
+  },
+  snapshot: {
+    widths: [1280, 375],
+    minHeight: 1024,
+    percyCSS: '',
+    enableJavaScript: true,
+  },
+};
+```
+
+### Playwright Integration
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  reporter: [['list'], ['html']],
+});
+```
+
+```bash
+percy exec -- npx playwright test
+```
+
+### Snapshot in Test
+
+```typescript
+import { test, expect } from '@playwright/test';
+import percySnapshot from '@percy/playwright';
+
+test('homepage', async ({ page }) => {
+  await page.goto('/');
+  await percySnapshot(page, 'Homepage');
+});
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PERCY_TOKEN` | Project token (required for upload) |
+| `PERCY_BRANCH` | Branch name |
+| `PERCY_PARTIAL_BUILD` | For parallelized runs |
+
+## BackstopJS Configuration
+
+### Installation
+
+```bash
+npm install backstopjs --save-dev
+npx backstop init
+```
+
+### backstop.json
+
+```json
+{
+  "id": "visual_regression",
+  "viewports": [
+    { "label": "desktop", "width": 1920, "height": 1080 },
+    { "label": "tablet", "width": 768, "height": 1024 },
+    { "label": "mobile", "width": 375, "height": 667 }
+  ],
+  "scenarios": [
+    {
+      "label": "Homepage",
+      "url": "http://localhost:3000/",
+      "referenceUrl": "",
+      "readyEvent": "",
+      "readySelector": "",
+      "delay": 500,
+      "hideSelectors": [".timestamp", ".ad-banner"],
+      "removeSelectors": [],
+      "selectorExpansion": true,
+      "expect": 0,
+      "misMatchThreshold": 0.1
+    },
+    {
+      "label": "Login",
+      "url": "http://localhost:3000/login",
+      "delay": 500,
+      "misMatchThreshold": 0.1
+    }
+  ],
+  "paths": {
+    "bitmaps_reference": "backstop_data/bitmaps_reference",
+    "bitmaps_test": "backstop_data/bitmaps_test",
+    "engine_scripts": "backstop_data/engine_scripts",
+    "html_report": "backstop_data/html_report",
+    "ci_report": "backstop_data/ci_report"
+  },
+  "report": ["browser", "CI"],
+  "engine": "playwright",
+  "engineOptions": {
+    "args": ["--no-sandbox"]
+  }
+}
+```
+
+### Scenario Options
+
+| Option | Description |
+|-------|-------------|
+| `label` | Scenario name |
+| `url` | Page URL |
+| `delay` | Wait (ms) before capture |
+| `hideSelectors` | Hide but keep layout |
+| `removeSelectors` | Remove from DOM |
+| `misMatchThreshold` | Tolerance (0–1) |
+| `selector` | Capture specific element only |
+
+### Commands
+
+```bash
+backstop test      # Run comparison
+backstop approve   # Update reference images
+backstop reference # Alias for approve
+backstop openReport # Open HTML report
+```
+
+### Docker
+
+```bash
+docker run --rm -v $(pwd):/src backstopjs/backstopjs test
+docker run --rm -v $(pwd):/src backstopjs/backstopjs approve
+```
+
+## Tool Comparison
+
+| Feature | Playwright | Percy | BackstopJS |
+|---------|------------|-------|------------|
+| Setup | Built-in | npm + token | npm or Docker |
+| Baselines | Local | Cloud | Local |
+| Review UI | Diff artifacts | Web dashboard | HTML report |
+| Viewports | Projects | Config | backstop.json |
+| Masking | mask option | percyCSS | hideSelectors |
+| CI | Native | percy exec | backstop test |
+| Cost | Free | Paid (free tier) | Free |

package/skills/qa-visual-regression-writer/references/patterns.md

@@ -0,0 +1,213 @@
+# Visual Regression Patterns
+
+Screenshot strategies, masking, viewports, and threshold configuration for visual regression testing.
+
+## Screenshot Strategies
+
+### Full Page vs Element
+
+| Strategy | Use Case | Example |
+|----------|----------|---------|
+| **Full page** | Layout, scroll behavior, long pages | `expect(page).toHaveScreenshot({ fullPage: true })` |
+| **Viewport** | Above-the-fold, fixed viewport | `expect(page).toHaveScreenshot()` (default) |
+| **Element** | Component, modal, header | `expect(locator).toHaveScreenshot()` |
+| **Multiple elements** | Key sections | Capture each with unique names |
+
+```typescript
+// Full page
+await expect(page).toHaveScreenshot('homepage-full.png', { fullPage: true });
+
+// Viewport only
+await expect(page).toHaveScreenshot('homepage-viewport.png');
+
+// Element
+await expect(page.getByRole('banner')).toHaveScreenshot('header.png');
+await expect(page.getByTestId('product-card')).toHaveScreenshot('product-card.png');
+```
+
+### When to Use Each
+
+- **Full page:** Marketing pages, documentation, long forms
+- **Viewport:** Hero sections, dashboards, fixed layouts
+- **Element:** Reusable components, modals, cards, headers
+
+## Dynamic Content Masking
+
+### Playwright Mask
+
+```typescript
+await expect(page).toHaveScreenshot('dashboard.png', {
+  mask: [
+    page.getByTestId('user-avatar'),
+    page.getByTestId('timestamp'),
+    page.locator('.ad-banner'),
+  ],
+  maskColor: '#000000', // Optional: color for masked regions
+});
+```
+
+### Common Elements to Mask
+
+| Element | Reason |
+|---------|--------|
+| Timestamps | Always changing |
+| User avatars | User-specific |
+| Ads | Third-party, variable |
+| Charts/graphs | May use random data |
+| "X minutes ago" | Relative time |
+| Session IDs, tokens | Security, uniqueness |
+
+### Percy Masking
+
+```typescript
+await percySnapshot(page, 'Dashboard', {
+  percyCSS: `
+    [data-testid="timestamp"] { visibility: hidden; }
+    .ad-banner { display: none; }
+  `,
+});
+```
+
+### BackstopJS Selectors to Hide
+
+```json
+{
+  "scenarios": [{
+    "url": "https://example.com/dashboard",
+    "hideSelectors": [".timestamp", ".ad-banner", "[data-testid='avatar']"]
+  }]
+}
+```
+
+## Viewport Variations
+
+### Playwright Projects
+
+```typescript
+// playwright.config.ts
+projects: [
+  { name: 'desktop', use: { ...devices['Desktop Chrome'], viewport: { width: 1920, height: 1080 } } },
+  { name: 'tablet', use: { ...devices['iPad Pro'] } },
+  { name: 'mobile', use: { ...devices['iPhone 13'] } },
+],
+```
+
+### Snapshot Naming with Viewport
+
+```typescript
+test('homepage visual', async ({ page }, testInfo) => {
+  await page.goto('/');
+  const project = testInfo.project.name;
+  await expect(page).toHaveScreenshot(`homepage-${project}.png`);
+});
+```
+
+### BackstopJS Viewports
+
+```json
+{
+  "viewports": [
+    { "label": "desktop", "width": 1920, "height": 1080 },
+    { "label": "tablet", "width": 768, "height": 1024 },
+    { "label": "mobile", "width": 375, "height": 667 }
+  ]
+}
+```
+
+### Recommended Breakpoints
+
+| Label | Width | Height | Use |
+|-------|-------|--------|-----|
+| Desktop | 1920 | 1080 | Primary desktop |
+| Tablet | 768 | 1024 | iPad portrait |
+| Mobile | 375 | 667 | iPhone SE / small phone |
+| Mobile large | 414 | 896 | iPhone 11+ |
+
+## Threshold Configuration
+
+### Playwright
+
+```typescript
+await expect(page).toHaveScreenshot('page.png', {
+  maxDiffPixels: 100,        // Absolute pixel count
+  maxDiffPixelRatio: 0.01,   // 1% of pixels
+});
+```
+
+| Option | Description | When to Use |
+|--------|-------------|-------------|
+| `maxDiffPixels` | Max differing pixels | Font/subpixel differences |
+| `maxDiffPixelRatio` | Max ratio (0–1) | Proportional tolerance |
+
+### BackstopJS
+
+```json
+{
+  "scenarios": [{
+    "misMatchThreshold": 0.1
+  }]
+}
+```
+
+- `0` = strict (no tolerance)
+- `0.1` = 0.1% tolerance
+- `1` = 100% (accept all)
+
+### Percy
+
+Percy uses built-in diff engine; configure via dashboard or `percy.config.js` for ignore regions.
+
+## Animation Disabling
+
+### CSS Override (Playwright)
+
+```typescript
+await page.addStyleTag({
+  content: `
+    *, *::before, *::after {
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
+      transition-duration: 0s !important;
+    }
+  `,
+});
+await expect(page).toHaveScreenshot('static.png');
+```
+
+### prefers-reduced-motion
+
+```typescript
+await page.emulateMedia({ reducedMotion: 'reduce' });
+await expect(page).toHaveScreenshot('reduced-motion.png');
+```
+
+### Wait for Stability
+
+```typescript
+await page.waitForLoadState('networkidle');
+await page.waitForTimeout(500); // Allow animations to settle
+await expect(page).toHaveScreenshot('stable.png');
+```
+
+## Element Screenshot Patterns
+
+### Scroll Into View
+
+```typescript
+await page.getByTestId('footer').scrollIntoViewIfNeeded();
+await expect(page.getByTestId('footer')).toHaveScreenshot('footer.png');
+```
+
+### Modal / Overlay
+
+```typescript
+await page.getByRole('button', { name: 'Open modal' }).click();
+await expect(page.getByRole('dialog')).toHaveScreenshot('modal.png');
+```
+
+### Hover State
+
+```typescript
+await page.getByTestId('card').hover();
+await expect(page.getByTestId('card')).toHaveScreenshot('card-hover.png');
+```

package/skills/qa-vitest-writer/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: qa-vitest-writer
+description: Generate Vitest unit and integration tests for TypeScript projects with ESM-native support, Vite integration, and Jest-compatible API.
+output_dir: tests/unit
+---
+
+# QA Vitest Writer
+
+## Purpose
+
+Write Vitest unit and integration tests from test case specifications. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer, or specs) into executable Vitest code with proper mocking, fixtures, and assertions.
+
+## Trigger Phrases
+
+- "Write Vitest tests for [module/feature]"
+- "Generate Vitest unit tests from test cases"
+- "Create Vitest integration tests"
+- "Add Vitest tests for [spec/requirements]"
+- "Migrate Jest tests to Vitest"
+- "Vitest tests with mocks and fixtures"
+- "In-source Vitest tests for [component]"
+- "Parameterized Vitest tests (test.each)"
+
+## Key Advantages
+
+| Advantage | Description |
+| --------- | ----------- |
+| **ESM-native** | No CommonJS transformation; native `import`/`export` |
+| **Vite integration** | Uses Vite for fast transforms, HMR, and config |
+| **Watch mode** | Instant re-runs on file changes |
+| **Jest-compatible API** | `describe`/`it`/`test`, `expect`, `vi` (like `jest`) |
+| **In-source testing** | Co-locate tests with source (`__tests__` or `*.test.ts`) |
+| **Workspace support** | Monorepo config with project-level overrides |
+
+## Workflow
+
+1. **Read test cases** — From specs, requirements, or manual test designs
+2. **Analyze code** — Inspect module under test: exports, dependencies, types
+3. **Generate tests** — Produce `describe`/`it` blocks with assertions
+4. **Add mocks/fixtures** — Use `vi.mock`, `vi.fn`, `vi.spyOn`, fixtures as needed
+5. **Verify** — Ensure tests run and pass; fix any config or import issues
+
+## Context7 MCP
+
+Use **Context7 MCP** for current Vitest documentation when:
+- API signatures or options are uncertain
+- New Vitest features (e.g., `vi.hoisted`, workspace config) need verification
+- Migration from Jest requires up-to-date compatibility notes
+
+## Key Patterns
+
+| Pattern | Usage |
+| ------- | ----- |
+| `describe` / `it` / `test` | Test structure (Jest-compatible) |
+| `vi.mock()` | Module substitution; hoisted before imports |
+| `vi.fn()` | Mock function with call tracking |
+| `vi.spyOn()` | Spy on existing method; optionally replace |
+| `vi.hoisted()` | Run code before imports (ESM mocking) |
+| In-source testing | `__tests__/` or `{module}.test.ts` / `{module}.spec.ts` |
+| Snapshot testing | `expect(obj).toMatchSnapshot()` |
+| Parameterized | `test.each([...])` / `it.each([...])` |
+| Concurrent | `it.concurrent` / `test.concurrent` |
+
+See `references/patterns.md` for detailed patterns.
+
+## Configuration
+
+- **Config file:** `vitest.config.ts` or `vite.config.ts` with `test` block
+- **Workspace:** `vitest.workspace.ts` for monorepos
+- **Coverage:** `v8` or `istanbul` via `@vitest/coverage-v8` / `@vitest/coverage-istanbul`
+
+See `references/config.md` for configuration patterns.
+
+## Migration from Jest
+
+| Jest | Vitest | Notes |
+| ---- | ------ | ----- |
+| `jest.mock()` | `vi.mock()` | Same semantics; hoisted |
+| `jest.fn()` | `vi.fn()` | Same API |
+| `jest.spyOn()` | `vi.spyOn()` | Same API |
+| `jest.useFakeTimers()` | `vi.useFakeTimers()` | Same API |
+| `beforeAll` / `afterAll` | Same | Unchanged |
+| `beforeEach` / `afterEach` | Same | Unchanged |
+
+ESM: Use `vi.hoisted()` when variables must be available in `vi.mock` factory. See `references/best-practices.md`.
+
+## File Naming
+
+- `{module}.test.ts` — Preferred for unit tests
+- `{module}.spec.ts` — Alternative; common for integration tests
+- `__tests__/{module}.test.ts` — Co-located in source directory
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Vitest unit and integration tests from test cases
+- Add mocks (`vi.mock`, `vi.fn`, `vi.spyOn`), fixtures, and setup/teardown
+- Use `test.each` for parameterized tests; `it.concurrent` for parallel runs
+- Configure `vitest.config.ts` and coverage
+- Migrate Jest tests to Vitest (syntax and API mapping)
+- Call qa-diagram-generator for test flow diagrams if needed
+
+**Cannot do (requires confirmation):**
+- Change production code to satisfy tests
+- Add tests for requirements not in source documents
+- Override project-level Vitest/Vite config without approval
+
+**Will not do (out of scope):**
+- Execute tests (user runs `vitest` or `npm test`)
+- Write Playwright/Cypress E2E tests (use qa-playwright-ts-writer)
+- Modify CI/CD pipelines
+
+## References
+
+- `references/patterns.md` — ESM mocking, in-source testing, concurrent tests, workspace
+- `references/assertions.md` — Vitest/Chai assertion reference
+- `references/config.md` — vitest.config.ts, coverage, workspace, plugins
+- `references/best-practices.md` — Best practices, Jest migration patterns
+
+## Quality Checklist
+
+- [ ] Tests match test case steps and expected results
+- [ ] Mocks are properly scoped (per test or per describe)
+- [ ] No hardcoded secrets or sensitive data
+- [ ] Assertions are specific (avoid only `toBeTruthy` where value matters)
+- [ ] `beforeEach`/`afterEach` restore state; mocks reset where needed
+- [ ] File naming follows project convention (`*.test.ts` or `*.spec.ts`)
+- [ ] Imports use ESM (`import`); no `require` unless required by dependency
+- [ ] Coverage targets considered if specified in requirements
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| `vi.mock` not working | ESM hoisting; variable not in scope | Use `vi.hoisted()` to define variables before imports |
+| Mock returns undefined | Factory not returning correct shape | Ensure factory returns object matching module exports |
+| Tests pass individually, fail together | Shared mutable state | Reset mocks in `beforeEach`; use `vi.clearAllMocks()` |
+| `import.meta.env` wrong in tests | Env not set for test | Use `vi.stubEnv()` with `unstubEnvs: true` in config |
+| Coverage not collected | Reporter not configured | Add `@vitest/coverage-v8`, set `coverage.reporter` |
+| Slow test runs | No workspace or wrong config | Use `vitest.workspace.ts`; exclude node_modules |
+| Type errors in mocks | Mock shape doesn't match types | Use `vi.mocked()` or type assertions; match export shape |

package/skills/qa-vitest-writer/references/assertions.md

@@ -0,0 +1,105 @@
+# Vitest / Chai Assertion Reference
+
+Vitest uses the same assertion API as Jest (which is built on Chai). All assertions are available via `expect()`.
+
+## Equality
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(x).toBe(y)` | Strict equality (`Object.is`) |
+| `expect(x).toEqual(y)` | Deep equality for objects/arrays |
+| `expect(x).toStrictEqual(y)` | Deep equality + type checks (undefined, etc.) |
+| `expect(x).not.toBe(y)` | Negation |
+
+## Truthiness
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(x).toBeTruthy()` | Truthy value |
+| `expect(x).toBeFalsy()` | Falsy value |
+| `expect(x).toBeDefined()` | Not `undefined` |
+| `expect(x).toBeUndefined()` | `undefined` |
+| `expect(x).toBeNull()` | `null` |
+
+## Numbers
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(n).toBeGreaterThan(m)` | `n > m` |
+| `expect(n).toBeGreaterThanOrEqual(m)` | `n >= m` |
+| `expect(n).toBeLessThan(m)` | `n < m` |
+| `expect(n).toBeLessThanOrEqual(m)` | `n <= m` |
+| `expect(n).toBeCloseTo(m, numDigits)` | Float comparison with precision |
+| `expect(n).toBeNaN()` | `NaN` |
+
+## Strings
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(s).toMatch(/regex/)` | Matches regex |
+| `expect(s).toContain(substr)` | Includes substring |
+| `expect(s).toHaveLength(n)` | Length equals n |
+
+## Arrays and Iterables
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(arr).toContain(item)` | Array contains item |
+| `expect(arr).toContainEqual(item)` | Array contains object matching shape |
+| `expect(arr).toHaveLength(n)` | Array length |
+| `expect(arr).toEqual(expect.arrayContaining([...]))` | Array contains subset |
+
+## Objects
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(obj).toHaveProperty(key)` | Has property |
+| `expect(obj).toHaveProperty(key, value)` | Property equals value |
+| `expect(obj).toMatchObject(partial)` | Contains subset of properties |
+| `expect(obj).toHaveLength(n)` | For array-like (length property) |
+
+## Functions and Mocks
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(fn).toHaveBeenCalled()` | Called at least once |
+| `expect(fn).toHaveBeenCalledTimes(n)` | Called exactly n times |
+| `expect(fn).toHaveBeenCalledWith(arg1, arg2)` | Called with specific args |
+| `expect(fn).toHaveBeenLastCalledWith(arg1, arg2)` | Last call args |
+| `expect(fn).toHaveBeenNthCalledWith(n, arg1, arg2)` | Nth call args |
+| `expect(fn).toHaveReturned()` | Returned (did not throw) |
+| `expect(fn).toHaveReturnedWith(value)` | Returned specific value |
+| `expect(fn).toThrow()` | Threw an error |
+| `expect(fn).toThrow(error)` | Threw specific error type/message |
+
+## Async
+
+| Assertion | Description |
+| --------- | ----------- |
+| `await expect(promise).resolves.toBe(value)` | Resolved value |
+| `await expect(promise).rejects.toThrow()` | Rejected with error |
+
+## Snapshots
+
+| Assertion | Description |
+| --------- | ----------- |
+| `expect(obj).toMatchSnapshot()` | File snapshot |
+| `expect(obj).toMatchInlineSnapshot(\`...\`)` | Inline snapshot |
+
+## Type Assertions (TypeScript)
+
+Use `expect.any(constructor)` for flexible matching:
+
+```ts
+expect(fn).toHaveBeenCalledWith(expect.any(String), expect.any(Number))
+expect(obj).toEqual({ id: expect.any(Number), name: expect.any(String) })
+```
+
+## Negation
+
+Prefix any assertion with `.not`:
+
+```ts
+expect(x).not.toBeNull()
+expect(arr).not.toContain(undefined)
+```