qa-skills 3.0.0 → 3.1.0

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

@@ -1,131 +0,0 @@
----
-name: qa-jest-writer
-description: Generate Jest unit and integration tests for TypeScript/JavaScript projects with jest.mock, snapshots, code coverage, and describe/it patterns.
-output_dir: tests/unit
----
-
-# QA Jest Writer
-
-## Purpose
-
-Write Jest unit and integration tests from test case specifications (Phase 2 output). Transform structured test cases into executable TypeScript/JavaScript tests using Jest's describe/it patterns, mocking, snapshots, and coverage tooling.
-
-## Trigger Phrases
-
-- "Write Jest tests for [module/function]"
-- "Generate Jest unit tests from test cases"
-- "Create Jest integration tests for [service]"
-- "Add Jest tests with mocks for [dependency]"
-- "Jest snapshot tests for [component]"
-- "Jest test coverage for [file]"
-- "Parameterized Jest tests for [function]"
-- "Jest async tests for [API handler]"
-
-## Test Types
-
-| Type | Scope | Focus |
-| ---- | ----- | ----- |
-| **Unit** | Isolated function/class testing | Single unit, mocked dependencies |
-| **Integration** | Module interaction, service layer | Real or partial integration, fewer mocks |
-
-## Workflow
-
-1. **Read test cases** — From Phase 2 (qa-testcase-from-docs, qa-testcase-from-ui, qa-manual-test-designer)
-2. **Analyze target code** — Identify module under test, dependencies, exports
-3. **Generate test files** — Create `{module}.test.ts` or `{module}.spec.ts`
-4. **Add mocks/fixtures** — jest.mock, jest.spyOn, factory functions, test data
-5. **Verify coverage** — Ensure assertions match test case steps, run coverage report
-
-## Context7 MCP
-
-Uses **Context7 MCP** to fetch current Jest documentation when needed. Query for Jest API, matchers, or configuration to ensure generated tests align with latest Jest behavior.
-
-## Key Patterns
-
-| Pattern | Use Case |
-| ------- | -------- |
-| `describe` / `it` / `test` | Group and define test cases |
-| `beforeEach` / `afterEach` | Setup and teardown per test |
-| `jest.mock()` | Mock entire modules (hoisted) |
-| `jest.spyOn()` | Spy on object methods |
-| Snapshot testing | UI components, serializable output |
-| `test.each` | Parameterized / table-driven tests |
-| `async`/`await`, `done` | Async testing |
-| Custom matchers | Domain-specific assertions |
-
-## Assertion Patterns
-
-| Assertion | Use |
-| --------- | --- |
-| `toBe` | Strict equality (===) |
-| `toEqual` | Deep equality |
-| `toMatchObject` | Partial object match |
-| `toThrow` | Error thrown |
-| `toHaveBeenCalledWith` | Mock call arguments |
-| `resolves` / `rejects` | Promise outcomes |
-
-See `references/assertions.md` for full reference.
-
-## Configuration
-
-- **jest.config.ts** — TypeScript config with `moduleNameMapper`, `transform`, `coverage`
-- **tsconfig paths** — Map aliases (e.g., `@/` → `src/`)
-- **setupFiles** — Global setup (e.g., env vars, polyfills)
-
-See `references/config.md` for configuration guide.
-
-## File Naming
-
-- `{module}.test.ts` — Preferred (aligns with Jest default)
-- `{module}.spec.ts` — Alternative (common in Angular/Vue)
-
-Place tests next to source (`__tests__/` or colocated) or in `tests/` per project convention.
-
-## Scope
-
-**Can do (autonomous):**
-- Generate Jest unit and integration tests from test case specs
-- Add jest.mock, jest.spyOn, manual mocks
-- Create snapshot tests for components/output
-- Write parameterized tests (test.each)
-- Handle async tests (async/await, resolves/rejects)
-- Configure jest.config.ts patterns (moduleNameMapper, coverage)
-- Use Context7 MCP for current Jest docs
-
-**Cannot do (requires confirmation):**
-- Change production code to make it testable
-- Add tests for modules not in test case scope
-- Override project Jest configuration without approval
-
-**Will not do (out of scope):**
-- E2E tests (use Playwright/Cypress skills)
-- Run tests or interpret coverage reports
-- Modify CI/CD pipelines
-
-## References
-
-- `references/patterns.md` — Unit structure, mocking strategies, async, snapshots, error testing
-- `references/assertions.md` — Complete Jest assertion reference by category
-- `references/config.md` — jest.config, tsconfig paths, coverage, setupFiles
-- `references/best-practices.md` — Anti-patterns, AAA, isolation, descriptive names
-
-## Quality Checklist
-
-- [ ] No hardcoded sensitive data (use fixtures/env)
-- [ ] Proper mocking (dependencies isolated, no real I/O)
-- [ ] Assertions specific (no vague toBeTruthy for complex objects)
-- [ ] Tests independent (order-independent, no shared mutable state)
-- [ ] Descriptive test names (behavior/outcome, not implementation)
-- [ ] Each test case step has corresponding assertion(s)
-- [ ] Async tests use async/await or proper done/resolves
-
-## Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-| ------- | ------------ | --- |
-| Module not found | Path/alias mismatch | Check `moduleNameMapper` in jest.config, tsconfig paths |
-| Mock not working | Hoisting / import order | Use `jest.mock()` at top of file, before imports |
-| Timeout | Async not resolved | Increase `jest.setTimeout()`, ensure promises resolve |
-| Snapshot drift | Intentional change | Run `jest -u` to update; verify change is correct |
-| Coverage gaps | Missing branches | Add tests for error paths, edge cases |
-| Spy not called | Wrong target or timing | Verify spy on correct object, call after setup |

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

@@ -1,125 +0,0 @@
-# Jest Assertion Reference
-
-Organized by category. Use the most specific matcher for clear intent.
-
-## Equality
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toBe` | Strict equality (===) | `expect(1).toBe(1)` |
-| `toEqual` | Deep equality | `expect({ a: 1 }).toEqual({ a: 1 })` |
-| `toStrictEqual` | Deep + type check | `expect({ a: 1 }).toStrictEqual({ a: 1 })` |
-| `toMatchObject` | Partial object match | `expect(obj).toMatchObject({ a: 1 })` |
-| `toBeNull` | Exactly null | `expect(x).toBeNull()` |
-| `toBeUndefined` | Exactly undefined | `expect(x).toBeUndefined()` |
-| `toBeDefined` | Not undefined | `expect(x).toBeDefined()` |
-
-## Truthiness
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toBeTruthy` | Truthy value | `expect(1).toBeTruthy()` |
-| `toBeFalsy` | Falsy value | `expect(0).toBeFalsy()` |
-| `toBeTrue` | Exactly true | `expect(flag).toBe(true)` |
-| `toBeFalse` | Exactly false | `expect(flag).toBe(false)` |
-
-## Numbers
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toBeGreaterThan` | > | `expect(5).toBeGreaterThan(3)` |
-| `toBeGreaterThanOrEqual` | >= | `expect(5).toBeGreaterThanOrEqual(5)` |
-| `toBeLessThan` | < | `expect(2).toBeLessThan(5)` |
-| `toBeLessThanOrEqual` | <= | `expect(2).toBeLessThanOrEqual(2)` |
-| `toBeCloseTo` | Float approx | `expect(0.1 + 0.2).toBeCloseTo(0.3)` |
-
-## Strings
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toMatch` | Regex or substring | `expect('hello').toMatch(/hel/)` |
-| `toContain` | Substring | `expect('hello').toContain('ell')` |
-| `toHaveLength` | Length | `expect('hi').toHaveLength(2)` |
-
-## Arrays
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toContain` | Item in array | `expect([1,2]).toContain(2)` |
-| `toContainEqual` | Deep item match | `expect([{a:1}]).toContainEqual({a:1})` |
-| `toHaveLength` | Array length | `expect([1,2]).toHaveLength(2)` |
-| `toEqual` | Full array match | `expect(arr).toEqual([1,2,3])` |
-
-## Objects
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toMatchObject` | Partial match | `expect(obj).toMatchObject({ key: 1 })` |
-| `toHaveProperty` | Has key | `expect(obj).toHaveProperty('key')` |
-| `toHaveProperty('key', value)` | Key + value | `expect(obj).toHaveProperty('key', 1)` |
-| `toEqual` | Deep equality | `expect(obj).toEqual(expected)` |
-
-## Functions
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toThrow` | Throws | `expect(() => fn()).toThrow()` |
-| `toThrow('msg')` | Throws with message | `expect(() => fn()).toThrow('msg')` |
-| `toThrow(/regex/)` | Throws matching regex | `expect(() => fn()).toThrow(/error/)` |
-| `toThrow(ErrorType)` | Throws instance | `expect(() => fn()).toThrow(ValidationError)` |
-
-## Mocks / Spies
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toHaveBeenCalled` | Called at least once | `expect(mock).toHaveBeenCalled()` |
-| `toHaveBeenCalledTimes(n)` | Called n times | `expect(mock).toHaveBeenCalledTimes(2)` |
-| `toHaveBeenCalledWith(...args)` | Called with args | `expect(mock).toHaveBeenCalledWith(1, 2)` |
-| `toHaveBeenLastCalledWith(...args)` | Last call args | `expect(mock).toHaveBeenLastCalledWith(1)` |
-| `toHaveBeenNthCalledWith(n, ...args)` | Nth call args | `expect(mock).toHaveBeenNthCalledWith(2, 1, 2)` |
-| `toHaveReturnedWith(value)` | Returned value | `expect(mock).toHaveReturnedWith(42)` |
-| `not.toHaveBeenCalled` | Never called | `expect(mock).not.toHaveBeenCalled()` |
-
-## Promises
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `resolves` | Awaits and asserts | `await expect(promise).resolves.toBe(1)` |
-| `rejects` | Awaits rejection | `await expect(promise).rejects.toThrow()` |
-| `resolves.toEqual` | Resolved value | `await expect(promise).resolves.toEqual(obj)` |
-| `rejects.toThrow` | Rejected error | `await expect(promise).rejects.toThrow('err')` |
-
-## Errors
-
-| Matcher | Description | Example |
-| ------- | ----------- | ------- |
-| `toThrow` | Throws any | `expect(() => fn()).toThrow()` |
-| `toThrow(Error)` | Throws Error type | `expect(() => fn()).toThrow(TypeError)` |
-| `toThrow('message')` | Message match | `expect(() => fn()).toThrow('invalid')` |
-| `toThrow(/pattern/)` | Message regex | `expect(() => fn()).toThrow(/invalid/)` |
-
-## Negation
-
-Use `.not` before any matcher:
-
-```typescript
-expect(1).not.toBe(2);
-expect(mock).not.toHaveBeenCalled();
-```
-
-## Custom Matchers
-
-```typescript
-expect.extend({
-  toBeWithinRange(received, floor, ceiling) {
-    const pass = received >= floor && received <= ceiling;
-    return {
-      pass,
-      message: () =>
-        pass
-          ? `expected ${received} not to be within ${floor} - ${ceiling}`
-          : `expected ${received} to be within ${floor} - ${ceiling}`,
-    };
-  },
-});
-```

package/skills/qa-jest-writer/references/best-practices.md

@@ -1,136 +0,0 @@
-# Jest Best Practices and Anti-Patterns
-
-## AAA Pattern
-
-Structure each test as **Arrange, Act, Assert**:
-
-```typescript
-it('calculates total with tax', () => {
-  // Arrange
-  const items = [{ price: 10 }, { price: 20 }];
-  const taxRate = 0.1;
-
-  // Act
-  const total = calculateTotal(items, taxRate);
-
-  // Assert
-  expect(total).toBe(33);
-});
-```
-
-## Test Isolation
-
-- Each test must run independently
-- No shared mutable state between tests
-- Use `beforeEach` for fresh setup
-- Reset mocks with `jest.clearAllMocks()` or `jest.resetAllMocks()` when needed
-
-```typescript
-beforeEach(() => {
-  jest.clearAllMocks();
-});
-```
-
-## Descriptive Test Names
-
-| Avoid | Prefer |
-| ----- | ------ |
-| `it('works')` | `it('returns user when id is valid')` |
-| `it('test 1')` | `it('throws when input is null')` |
-| `it('handles error')` | `it('returns 400 when email is invalid')` |
-
-Use: **"should [expected behavior] when [condition]"**
-
-## Test Behavior, Not Implementation
-
-- Assert outcomes, not internal steps
-- Avoid testing private methods directly
-- Prefer testing through public API
-
-```typescript
-// Avoid: testing implementation
-expect(component.state.count).toBe(1);
-
-// Prefer: testing behavior
-expect(screen.getByText('Count: 1')).toBeInTheDocument();
-```
-
-## Mock Cleanup
-
-- Restore spies: `spy.mockRestore()` in `afterEach`
-- Clear mocks when reusing: `mockFn.mockClear()`
-- Reset modules when needed: `jest.resetModules()`
-
-```typescript
-afterEach(() => {
-  jest.restoreAllMocks();
-});
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Problem | Fix |
-| ------------ | ------- | --- |
-| Multiple assertions for unrelated behaviors | Hard to pinpoint failure | One behavior per test |
-| Testing implementation details | Brittle, breaks on refactor | Test observable behavior |
-| Shared mutable state | Flaky, order-dependent | Fresh setup per test |
-| `expect(x).toBeTruthy()` for objects | Vague, hides bugs | Use `toEqual`, `toMatchObject` |
-| Hardcoded secrets | Security risk | Use env, fixtures, faker |
-| Real I/O (DB, HTTP) in unit tests | Slow, flaky | Mock dependencies |
-| Empty catch blocks | Swallows errors | Let tests fail or assert on error |
-| Giant test files | Hard to maintain | Split by module/feature |
-| `any` in test types | Weak typing | Use proper types |
-
-## One Assertion Per Test (Guideline)
-
-Prefer one logical assertion per test. Multiple related assertions for the same outcome are fine:
-
-```typescript
-it('returns valid user object', () => {
-  const user = getUser(1);
-  expect(user).toHaveProperty('id', 1);
-  expect(user).toHaveProperty('name');
-  expect(user.email).toMatch(/^[\w.+-]+@[\w.-]+\.\w+$/);
-});
-```
-
-## Fixtures Over Hardcoded Data
-
-```typescript
-// fixtures/users.ts
-export const mockUser = {
-  id: 1,
-  name: 'Test User',
-  email: 'test@example.com',
-};
-```
-
-```typescript
-import { mockUser } from '../fixtures/users';
-jest.mocked(api.fetchUser).mockResolvedValue(mockUser);
-```
-
-## Async: Prefer async/await
-
-```typescript
-// Prefer
-it('fetches data', async () => {
-  const data = await fetchData();
-  expect(data).toBeDefined();
-});
-
-// Avoid when possible
-it('fetches data', (done) => {
-  fetchData().then((data) => {
-    expect(data).toBeDefined();
-    done();
-  });
-});
-```
-
-## Snapshot Discipline
-
-- Use for stable, structured output
-- Keep snapshots small and focused
-- Review diffs before `jest -u`
-- Prefer explicit assertions when behavior is more important than structure

package/skills/qa-jest-writer/references/config.md

@@ -1,134 +0,0 @@
-# Jest Configuration Guide
-
-## jest.config.ts (TypeScript)
-
-```typescript
-import type { Config } from 'jest';
-
-const config: Config = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
-  testMatch: ['**/*.test.ts', '**/*.spec.ts'],
-  moduleNameMapper: {
-    '^@/(.*)$': '<rootDir>/src/$1',
-  },
-  transform: {
-    '^.+\\.tsx?$': ['ts-jest', { useESM: true }],
-  },
-  collectCoverageFrom: [
-    'src/**/*.{ts,tsx}',
-    '!src/**/*.d.ts',
-    '!src/**/index.ts',
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html'],
-  setupFiles: ['<rootDir>/jest.setup.ts'],
-  testTimeout: 10000,
-};
-
-export default config;
-```
-
-## tsconfig Paths → moduleNameMapper
-
-When using path aliases in tsconfig:
-
-```json
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"],
-      "@utils/*": ["src/utils/*"]
-    }
-  }
-}
-```
-
-Map them in Jest:
-
-```typescript
-moduleNameMapper: {
-  '^@/(.*)$': '<rootDir>/src/$1',
-  '^@utils/(.*)$': '<rootDir>/src/utils/$1',
-},
-```
-
-## Coverage Setup
-
-```typescript
-collectCoverageFrom: [
-  'src/**/*.{ts,tsx}',
-  '!src/**/*.d.ts',
-  '!src/**/index.ts',
-  '!src/**/__tests__/**',
-],
-coverageDirectory: 'coverage',
-coverageReporters: ['text', 'lcov', 'html'],
-coverageThreshold: {
-  global: {
-    branches: 80,
-    functions: 80,
-    lines: 80,
-    statements: 80,
-  },
-},
-```
-
-## transform
-
-| Preset | Use Case |
-| ------ | -------- |
-| `ts-jest` | TypeScript |
-| `babel-jest` | Babel + TS/JS |
-| `@swc/jest` | Fast TS/JS via SWC |
-
-```typescript
-transform: {
-  '^.+\\.tsx?$': ['ts-jest', { useESM: true }],
-  '^.+\\.(js|jsx)$': 'babel-jest',
-},
-```
-
-## testMatch
-
-```typescript
-testMatch: [
-  '**/__tests__/**/*.[jt]s?(x)',
-  '**/?(*.)+(spec|test).[jt]s?(x)',
-],
-```
-
-## setupFiles
-
-Global setup (runs before each test file):
-
-```typescript
-setupFiles: ['<rootDir>/jest.setup.ts'],
-```
-
-```typescript
-// jest.setup.ts
-process.env.NODE_ENV = 'test';
-jest.setTimeout(10000);
-```
-
-## testEnvironment
-
-| Value | Use Case |
-| ----- | -------- |
-| `node` | Node.js (APIs, utils) |
-| `jsdom` | DOM (React, Vue) |
-| `jest-environment-jsdom` | Same as jsdom (Jest 28+) |
-
-## Common Options
-
-| Option | Description |
-| ------ | ----------- |
-| `clearMocks` | Clear mock calls between tests |
-| `restoreMocks` | Restore original implementations |
-| `testTimeout` | Default timeout (ms) |
-| `verbose` | Individual test results |
-| `roots` | Root directories for tests |
-| `moduleFileExtensions` | Resolve order (e.g. `['ts','tsx','js','json']`) |

package/skills/qa-jest-writer/references/patterns.md

@@ -1,172 +0,0 @@
-# Jest Test Patterns
-
-## Unit Test Structure
-
-```typescript
-describe('ModuleName', () => {
-  describe('functionName', () => {
-    beforeEach(() => {
-      // Reset state, create fresh instances
-    });
-
-    it('should do X when Y', () => {
-      // Arrange
-      const input = { ... };
-      // Act
-      const result = functionName(input);
-      // Assert
-      expect(result).toEqual(expected);
-    });
-  });
-});
-```
-
-- **describe** — Groups by module, then by function or scenario
-- **it** / **test** — One behavior per test
-- **beforeEach** — Fresh setup; avoid shared mutable state
-
-## Mocking Strategies
-
-### Manual Mocks
-
-Place in `__mocks__/` next to the module:
-
-```
-src/
-  services/
-    api.ts
-    __mocks__/
-      api.ts
-```
-
-```typescript
-// __mocks__/api.ts
-export const fetchUser = jest.fn();
-export const fetchPosts = jest.fn();
-```
-
-### Auto Mocks
-
-```typescript
-jest.mock('./api');
-// All exports become jest.fn()
-```
-
-### Factory Functions
-
-For configurable mocks:
-
-```typescript
-jest.mock('./api', () => ({
-  fetchUser: jest.fn(),
-  fetchPosts: jest.fn(),
-}));
-```
-
-### jest.spyOn
-
-Spy on existing methods without replacing the module:
-
-```typescript
-const spy = jest.spyOn(console, 'log').mockImplementation(() => {});
-// ... test
-spy.mockRestore();
-```
-
-### Mock Return Values
-
-```typescript
-jest.mocked(api.fetchUser).mockResolvedValue({ id: 1, name: 'Alice' });
-jest.mocked(api.fetchUser).mockRejectedValue(new Error('Network error'));
-```
-
-## Async Patterns
-
-### async/await
-
-```typescript
-it('fetches user', async () => {
-  const user = await fetchUser(1);
-  expect(user.name).toBe('Alice');
-});
-```
-
-### resolves / rejects
-
-```typescript
-await expect(fetchUser(1)).resolves.toMatchObject({ id: 1 });
-await expect(fetchUser(-1)).rejects.toThrow('Invalid id');
-```
-
-### done Callback (legacy)
-
-```typescript
-it('calls callback', (done) => {
-  someAsyncFn((err, result) => {
-    expect(err).toBeNull();
-    expect(result).toBeDefined();
-    done();
-  });
-});
-```
-
-## Snapshot Patterns
-
-### Basic Snapshot
-
-```typescript
-it('renders correctly', () => {
-  const { container } = render(<MyComponent />);
-  expect(container).toMatchSnapshot();
-});
-```
-
-### Inline Snapshot
-
-```typescript
-expect(result).toMatchInlineSnapshot(`
-  Object {
-    "status": "ok",
-    "count": 1,
-  }
-`);
-```
-
-### Snapshot Best Practices
-
-- Use for stable, serializable output (UI, JSON)
-- Avoid large snapshots; prefer focused assertions when possible
-- Review snapshot diffs before updating
-
-## Error Testing
-
-```typescript
-it('throws when input is invalid', () => {
-  expect(() => validateInput(null)).toThrow('Input is required');
-  expect(() => validateInput(null)).toThrow(/required/);
-});
-
-it('rejects with error', async () => {
-  await expect(asyncFn()).rejects.toThrow('Expected error');
-});
-```
-
-## Parameterized Tests (test.each)
-
-```typescript
-test.each([
-  [1, 1, 2],
-  [2, 3, 5],
-  [-1, 1, 0],
-])('adds %i + %i = %i', (a, b, expected) => {
-  expect(add(a, b)).toBe(expected);
-});
-
-test.each`
-  input    | expected
-  ${'a'}   | ${'A'}
-  ${'ab'}  | ${'AB'}
-`('uppercases $input to $expected', ({ input, expected }) => {
-  expect(input.toUpperCase()).toBe(expected);
-});
-```