qa-skills 3.0.0

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

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

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

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

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

@@ -0,0 +1,172 @@
+# 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);
+});
+```