hreshold: { global: { branches: 75, functions: 85, lines: 85, statements: 85, }, }, moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1', }, };

export default config;

The `moduleNameMapper` entry resolves TypeScript path aliases, which AI frequently mishandles when generating imports. Coverage thresholds act as a hard gate: if generated tests only cover happy paths, the CI pipeline will reject the commit.

### Step 4: Prompt Architecture

Effective AI prompting follows a four-part structure. Each part reduces ambiguity and constrains the output space.

1. **Implementation Context**: Paste the full function signature, type definitions, and internal logic.
2. **Style Reference**: Explicitly point to the anchor test file and request structural alignment.
3. **Category Specification**: List exact test categories instead of using vague terms like "comprehensive".
4. **Dependency Declaration**: Identify imported modules that require mocking and specify mock boundaries.

Example prompt structure:

Generate Jest unit tests for the calculateShipping function below. Match the structural style and assertion patterns in src/tests/shipping.test.ts. Cover the following categories:

• Standard delivery under weight limit
• Weight surcharge application
• Express delivery multiplier
• Negative weight rejection
• Zero distance calculation
• Invalid distance type handling Mock the external rateLookup module imported from ./rates.

Explicit category requests outperform open-ended instructions by 3-4x in branch coverage generation. The model stops guessing what "comprehensive" means and executes a deterministic checklist.

### Step 5: Validation Pipeline

AI-generated tests require systematic validation before merging. Apply the following checks:

- **Behavioral Naming**: Test titles must describe the condition and expected outcome, not just "returns value".
- **Mutation Verification**: Modify one line of the implementation (flip a comparison, remove a guard clause) and run the test. If it still passes, the assertion is passive.
- **Mock Boundary Check**: Verify mocks replace external dependencies, not internal logic. Over-mocking defeats the purpose of unit testing.
- **Async Compliance**: Ensure all promise-based tests use `await` and handle rejection paths.
- **Branch Exhaustion**: Confirm both `true` and `false` branches of conditionals are exercised.

Mutation verification is the most critical step. It separates active assertions from passive ones. A test that passes regardless of implementation changes provides zero safety net.

## Pitfall Guide

### 1. The Statement Coverage Illusion
**Explanation**: AI optimizes for line execution. It will generate tests that touch every line but skip conditional branches, leaving 50% of logic unverified.
**Fix**: Enforce `branches` coverage thresholds in `jest.config.ts`. Review coverage reports specifically for unexecuted branch markers.

### 2. Mock State Leakage
**Explanation**: AI frequently omits mock cleanup between tests. State from one test case bleeds into the next, causing intermittent failures or false positives.
**Fix**: Add `jest.clearAllMocks()` to an `afterEach` hook in your global setup or test file. For stateful modules, use `jest.resetModules()` before re-importing.

### 3. Environment Boundary Mismatch
**Explanation**: Functions interacting with DOM APIs, `window`, or `document` will throw reference errors in the default `node` environment.
**Fix**: Set `testEnvironment: 'jsdom'` for browser-facing modules. Keep `node` for backend utilities to maintain execution speed.

### 4. Path Alias Resolution Failure
**Explanation**: AI generates imports using raw paths (`../../utils/helpers`) instead of configured aliases (`@/utils/helpers`), breaking module resolution.
**Fix**: Always include `moduleNameMapper` in your Jest configuration. Verify alias patterns match your `tsconfig.json` paths exactly.

### 5. Async Assertion Omission
**Explanation**: AI sometimes writes tests for async functions without `await`, causing tests to pass immediately before assertions execute.
**Fix**: Enforce `async/await` syntax in your anchor tests. Use ESLint rules like `require-await` to catch missing awaits during code review.

### 6. Threshold Gaming
**Explanation**: Developers lower coverage thresholds to accommodate AI-generated tests, sacrificing quality for velocity.
**Fix**: Treat thresholds as non-negotiable gates. If AI tests fall short, refine the prompt categories or add manual edge cases. Never compromise thresholds for convenience.

### 7. Over-Mocking Internal Logic
**Explanation**: AI mocks functions that should be tested directly, creating tests that verify mocks instead of implementation.
**Fix**: Mock only external dependencies (APIs, databases, third-party SDKs). Internal helper functions should be exercised through the public interface.

## Production Bundle

### Action Checklist
- [ ] Install Jest, ts-jest, and @types/jest with TypeScript support enabled
- [ ] Write 2-3 manual anchor tests establishing naming, assertion, and mock conventions
- [ ] Configure coverage thresholds with branch minimums at 75% or higher
- [ ] Add moduleNameMapper for all TypeScript path aliases used in the project
- [ ] Structure AI prompts with explicit test categories and dependency declarations
- [ ] Run mutation checks by deliberately breaking implementation lines and verifying test failure
- [ ] Add jest.clearAllMocks() to afterEach hooks to prevent state leakage
- [ ] Enforce coverage gates in CI to block merges that fall below thresholds

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Backend Node.js utilities | `testEnvironment: 'node'` | Faster execution, no DOM overhead | Lower CI runtime cost |
| Frontend component logic | `testEnvironment: 'jsdom'` | Provides window/document APIs | Slightly higher memory usage |
| High-velocity startup | Jest with ts-jest | Mature ecosystem, extensive docs | Standard maintenance overhead |
| Vite-based frontend project | Vitest | Native Vite integration, faster cold starts | Requires config migration |
| Strict compliance project | Branch threshold ≥ 85% | Forces exhaustive conditional testing | Higher initial AI prompt refinement time |
| Rapid prototyping | Branch threshold ≥ 60% | Balances speed with basic safety | Acceptable for non-critical paths |

### Configuration Template

```typescript
// jest.config.ts
import type { Config } from 'jest';

const config: Config = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/__tests__/**/*.test.ts', '**/*.spec.ts'],
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/**/index.ts',
    '!src/**/types.ts',
    '!src/**/mocks/**',
  ],
  coverageThreshold: {
    global: {
      branches: 75,
      functions: 85,
      lines: 85,
      statements: 85,
    },
  },
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '^~/(.*)$': '<rootDir>/src/$1',
  },
  setupFilesAfterSetup: ['<rootDir>/jest.setup.ts'],
  transform: {
    '^.+\\.tsx?$': 'ts-jest',
  },
};

export default config;

// package.json scripts
{
  "scripts": {
    "test": "jest --passWithNoTests",
    "test:watch": "jest --watch --verbose",
    "test:coverage": "jest --coverage --coverageReporters=text",
    "test:coverage:html": "jest --coverage --coverageReporters=html",
    "test:mutation": "stryker run"
  }
}

// jest.setup.ts
afterEach(() => {
  jest.clearAllMocks();
  jest.restoreAllMocks();
});

Quick Start Guide

1. Initialize the environment: Run npm install --save-dev jest @types/jest ts-jest and create jest.config.ts using the template above.
2. Create anchor tests: Write two manual tests for a core utility function. Establish your describe hierarchy, matcher preferences, and mock patterns.
3. Configure coverage gates: Set branch thresholds to 75% and add moduleNameMapper for your path aliases. Run npm run test:coverage to verify baseline metrics.
4. Generate with structured prompts: Paste your function, reference the anchor test, list explicit categories, and declare dependencies. Run the generated tests immediately.
5. Validate and commit: Perform mutation checks, verify branch coverage meets thresholds, and push to CI. The pipeline will enforce quality gates automatically.

This workflow transforms AI test generation from a probabilistic experiment into a deterministic engineering practice. By constraining the model's output space with explicit types, coverage gates, and stylistic anchors, you achieve production-grade test suites without sacrificing development velocity.