DEV Community: Bhaumik

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Thu, 09 Jul 2026 09:27:33 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor's .cursor/rules/ system is the only IDE-native mechanism that injects persistent, project-scoped instructions into every AI interaction — this is what prevents hallucination at the source.

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

typescript
import { renderHook, act } from '@testing-library/react';
const { result } = renderHook(() => useMyHook());
act(() => result.current.doSomething());
expect(result.current.value).toBe('expected');

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)

python
def test_raises_when_user_not_found(mocker):
mock_repo = mocker.Mock()
mock_repo.find_by_id.return_value = None
service = UserService(mock_repo)
with pytest.raises(UserNotFoundException):
service.get_user("missing-id")


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state

typescript
fixture.detectChanges(); // trigger ngOnInit
const button = fixture.debugElement.query(By.css('[data-testid="submit"]'));
button.nativeElement.click();
fixture.detectChanges();
expect(fixture.debugElement.query(By.css('.error-msg'))).toBeTruthy();


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

php
it('throws exception when user not found', function () {
// Arrange
$repo = Mockery::mock(UserRepositoryInterface::class);
$repo->shouldReceive('findById')->once()->andReturn(null);
$service = new UserService($repo);

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)

php
it('validates email format', function (string $email, bool $valid) {
expect(validateEmail($email))->toBe($valid);
})->with([
['valid@email.com', true],
['notanemail', false],
['', false],
['@nodomain.com', false],
]);


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Can You Vibe Code a Laravel App in 2026?

Bhaumik — Mon, 29 Jun 2026 07:06:13 +0000

Vibe coding went mainstream in 2025. You describe what you want in plain English, an AI builds it, and you refine by talking instead of typing. The catch for our world is simple: almost every vibe coding tool ships JavaScript or React, not Laravel. So the question Laravel developers keep asking is fair. Can you actually vibe code a real, shippable Laravel app in 2026?

The short answer is yes, but only if the tool understands Laravel from the inside.

What vibe coding actually means for Laravel

Vibe coding is not autocomplete. Autocomplete finishes the line you are already writing. Vibe coding builds the thing you describe: models, migrations, controllers, routes, CRUD, auth, and the views to go with them. You stay in the loop by reviewing and prompting, not by hand writing every scaffold.

For a Laravel developer, the difference between a generic builder and a Laravel-native one is enormous. A generic tool can produce PHP, but it does not produce idiomatic Eloquent relationships, convention-correct migrations, Blade or Livewire views, or routes structured the way Laravel expects. You end up reworking the output, which erases the time the AI was supposed to save. If you want a deeper look at the category, our roundup of vibe coding tools breaks down where each approach fits.

Why most AI tools still miss Laravel

The AI coding wave was built for JavaScript, TypeScript, and Python first. That left more than two million Laravel developers working around tools that treat PHP as an afterthought. The result is predictable: prompts that should produce a clean resource controller instead produce something close, but not Laravel. Close is expensive. Close means a code review, a refactor, and a quiet decision to go back to writing the boilerplate by hand.

This is the gap that matters in 2026. Laravel is one of the largest frameworks in the world, the ecosystem is maturing fast around Laravel 13+ and PHP 8.3+, and the developers shipping on it want the same describe-it-and-build-it experience everyone else got two years ago. They just want it to actually run on a Laravel stack they can own.

How LaraCopilot approaches it

LaraCopilot is built specifically for Laravel, so vibe coding behaves the way a Laravel developer would expect. You describe the application in plain English and it generates production-ready Laravel apps: Eloquent models, migrations, controllers, full CRUD, authentication flows, and REST or GraphQL endpoints. Output is PSR-compliant and Laravel Pint formatted by default, so it reads like code a senior engineer on your team would write, not code you have to translate. You pick the UI layer too, whether that is Blade, Livewire, or Inertia with React or Vue.

If you are starting from a description rather than a blank artisan command, our guide on using a Laravel AI code generator walks through how the generation flow works step by step, from prompt to running app.

A real example

A founder used this exact flow to build a local marketplace with authentication, billing, and a dashboard in under two hours. The same scope had previously been estimated at three weeks of manual Laravel work. The app went live and onboarded more than two hundred users immediately. That is the practical promise of vibe coding for Laravel: not a toy prototype, but a production-ready app you can ship and own.

The proof shows up at scale too. More than 6,000 developers are now building this way, with over 2.4 million lines of Laravel generated and 98 percent customer satisfaction, all without a dollar of paid acquisition. For a closer look at speed, see how teams build Laravel apps in minutes using AI.

So, can you vibe code Laravel in 2026?

Yes, when the tool is Laravel-native. Vibe coding only works for our stack when the AI generates the conventions Laravel runs on, not a generic approximation you have to fix. The boilerplate you write on every project, the CRUD, the auth, the APIs, is exactly the part worth handing off, so you can spend your time on business logic and problem solving.

Meet LaraCopilot, your AI full-stack assistant built for Laravel developers. Try LaraCopilot Now.

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Fri, 26 Jun 2026 05:27:22 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Fri, 26 Jun 2026 05:03:03 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Wed, 24 Jun 2026 07:04:19 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Tue, 23 Jun 2026 12:09:13 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

(untitled)

Bhaumik — Tue, 23 Jun 2026 11:33:09 +0000

TDD Industry Standard Guide — Full Stack R&D Reference

Scope: Node.js · NestJS · Express.js · React · Next.js · Angular · Python · Laravel

Audience: Engineering teams adopting or scaling TDD practices

Version: 2025 — reflects current ecosystem state

Part 1 — What Is TDD and How It Works

1.1 Core Philosophy

TDD (Test-Driven Development) is a development methodology where tests are written before the production code. It inverts the traditional flow — instead of writing code then checking if it works, you first define what "working" means.

Red → Green → Refactor cycle:

1. RED    — Write a failing test for a behavior that doesn't exist yet
2. GREEN  — Write the minimum code required to make that test pass
3. REFACTOR — Clean up the code without breaking the test

This isn't just about testing — it's a design discipline. Forcing yourself to write tests first exposes bad API design, tight coupling, and unclear responsibilities before they're baked into code.

1.2 TDD vs BDD vs ATDD

Approach	Who writes	Language	Focus
TDD	Developer	Code/assertions	Unit behavior
BDD	Dev + QA	Gherkin (Given/When/Then)	User scenarios
ATDD	Dev + QA + Business	Acceptance criteria	System behavior

In practice, most production teams use TDD for units + BDD for integration/E2E. Pure ATDD is rare outside regulated industries.

1.3 The Test Pyramid (Industry Standard Model)

          /\
         /  \
        / E2E \          ~10% — Slow, expensive, brittle
       /--------\
      /Integration\      ~20% — Services, DB, APIs
     /--------------\
    /   Unit Tests   \   ~70% — Fast, isolated, numerous
   /------------------\

Invert this ratio = test anti-pattern (too many E2E tests = slow CI, fragile suite).

Part 2 — Test Types and What to Cover

2.1 Unit Tests

Test a single function, class, or module in isolation
All dependencies are mocked/stubbed
Should run in < 50ms per test

Cover:

Pure functions (transformation, calculation, formatting)
Service layer business logic
Guards, interceptors, middlewares
Validators and DTOs
Utility helpers

2.2 Integration Tests

Test two or more real components together
May hit a real DB (test DB), real service layer, real HTTP handler
Slower than unit tests but critical for wiring validation

Cover:

Controller → Service → Repository chain
Database queries with real schema
Auth flows (token issuance + validation)
Event-driven pipelines (queue → handler)

2.3 E2E Tests

Test the full system from HTTP request to response
Often uses a real or in-memory database
Validates complete user workflows

Cover:

Critical user journeys (login, checkout, form submission)
API contract validation
Cross-service flows in microservices

2.4 Contract Tests (Underused but Valuable)

Tests API contracts between producer and consumer
Tool: Pact.js (Node), Pactflow (SaaS)
Essential in microservices architectures

2.5 Snapshot Tests

Capture rendered output and detect unintended changes
Best for UI components (React, Angular)
Overuse leads to meaningless "approve all snapshots" habit

2.6 Test Case Identification Strategy

Before writing tests, apply these techniques:

Equivalence Partitioning — Group inputs into classes that behave the same

Boundary Value Analysis — Test at edges (0, -1, max, max+1)

Decision Table Testing — Matrix of conditions vs outcomes

State Transition — For stateful flows (e.g., order status machine)

For each function/module ask:
  ✓ Happy path — expected input → expected output
  ✓ Edge cases — empty, null, zero, max values
  ✓ Error paths — invalid input, network fail, DB error
  ✓ Security paths — injection, unauthorized access, rate limits
  ✓ Concurrency — race conditions, duplicate requests

Part 3 — Stack-Specific Setup

3.1 Node.js (Generic)

Packages:

{
  "devDependencies": {
    "jest": "^29.x",
    "ts-jest": "^29.x",
    "@types/jest": "^29.x",
    "supertest": "^6.x",
    "nock": "^13.x",
    "faker": "^8.x"
  }
}

jest.config.ts:

export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/*.spec.ts', '**/*.test.ts'],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  },
  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.module.ts', '!src/main.ts']
}

3.2 NestJS (Primary Recommendation for Node APIs)

Packages (built-in + additions):

{
  "devDependencies": {
    "@nestjs/testing": "^10.x",
    "jest": "^29.x",
    "ts-jest": "^29.x",
    "supertest": "^6.x",
    "@testcontainers/postgresql": "^10.x"
  }
}

Unit Test — Service (Red → Green example):

// users.service.spec.ts — RED phase
describe('UsersService', () => {
  let service: UsersService;
  let repo: jest.Mocked<UserRepository>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: UserRepository,
          useValue: {
            findOne: jest.fn(),
            save: jest.fn(),
          }
        }
      ]
    }).compile();

    service = module.get(UsersService);
    repo = module.get(UserRepository);
  });

  it('should throw NotFoundException when user does not exist', async () => {
    repo.findOne.mockResolvedValue(null);
    await expect(service.findById('non-existent-id')).rejects.toThrow(NotFoundException);
  });
});

Integration Test — Controller with real HTTP:

// users.e2e-spec.ts
describe('POST /users', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const module = await Test.createTestingModule({
      imports: [AppModule]
    }).compile();
    app = module.createNestApplication();
    await app.init();
  });

  it('should create user and return 201', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({ email: 'test@example.com', password: 'securePass123' })
      .expect(201)
      .expect(res => {
        expect(res.body).toHaveProperty('id');
        expect(res.body.email).toBe('test@example.com');
      });
  });
});

Testcontainers (Real DB in CI):

const container = await new PostgreSqlContainer('postgres:15').start();
// inject connection string into TypeORM config

3.3 Express.js

// Minimal setup, no DI framework — use jest + supertest
import request from 'supertest';
import app from '../app'; // your express app

describe('GET /health', () => {
  it('returns 200 with status ok', async () => {
    const res = await request(app).get('/health');
    expect(res.status).toBe(200);
    expect(res.body.status).toBe('ok');
  });
});

Key difference from NestJS: No built-in DI, so use dependency injection manually or use a light container like awilix for testability.

3.4 React.js

Packages:

{
  "devDependencies": {
    "@testing-library/react": "^14.x",
    "@testing-library/user-event": "^14.x",
    "@testing-library/jest-dom": "^6.x",
    "msw": "^2.x",
    "vitest": "^1.x"
  }
}

Vitest is now preferred over Jest for React/Vite projects (2024+)

// LoginForm.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

describe('LoginForm', () => {
  it('should show error when email is invalid', async () => {
    render(<LoginForm onSubmit={jest.fn()} />);
    await userEvent.type(screen.getByLabelText('Email'), 'notvalid');
    await userEvent.click(screen.getByRole('button', { name: /submit/i }));
    expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
  });
});

MSW for API Mocking (industry standard):

import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  http.get('/api/users', () => HttpResponse.json([{ id: 1, name: 'Bhaumik' }]))
);

3.5 Next.js

Additional considerations:

Test Server Components differently from Client Components
Use @testing-library/react for client components
Use Playwright or Cypress for full E2E (including SSR flows)

// app/actions/create-user.test.ts (Server Action testing)
import { createUser } from './create-user';

it('should return validation error for short password', async () => {
  const result = await createUser({ email: 'a@b.com', password: '123' });
  expect(result.error).toBe('Password too short');
});

3.6 Angular

Built-in: Jasmine + Karma (legacy) → now migrating to Jest + Vitest

// users.component.spec.ts
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { provideHttpClientTesting } from '@angular/common/http/testing';

describe('UsersComponent', () => {
  let component: UsersComponent;
  let fixture: ComponentFixture<UsersComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [UsersComponent],
      providers: [provideHttpClientTesting()]
    }).compileComponents();
    fixture = TestBed.createComponent(UsersComponent);
    component = fixture.componentInstance;
  });

  it('should display users from service', () => {
    expect(component).toBeTruthy();
  });
});

Angular 17+ recommendation: Use @analogjs/vitest-angular for faster testing.

3.7 Python

Packages:

pytest
pytest-cov
pytest-asyncio
pytest-mock
factory-boy
httpx (for async API tests)

# test_user_service.py
import pytest
from unittest.mock import AsyncMock
from app.services.user_service import UserService

@pytest.mark.asyncio
async def test_raises_not_found_when_user_missing():
    repo = AsyncMock()
    repo.find_by_id.return_value = None
    service = UserService(repo)

    with pytest.raises(UserNotFoundException):
        await service.get_user("missing-id")

FastAPI integration test:

from httpx import AsyncClient
from app.main import app

@pytest.mark.asyncio
async def test_create_user_returns_201():
    async with AsyncClient(app=app, base_url="http://test") as client:
        response = await client.post("/users", json={"email": "a@b.com"})
    assert response.status_code == 201

3.8 Laravel

Built-in: PHPUnit + Pest (recommended for modern projects)

// tests/Unit/UserServiceTest.php (Pest)
it('throws exception when user not found', function () {
    $repo = Mockery::mock(UserRepository::class);
    $repo->shouldReceive('findById')->andReturn(null);

    $service = new UserService($repo);
    expect(fn () => $service->getUser('abc'))->toThrow(UserNotFoundException::class);
});

// Feature test (Integration)
it('creates user via API', function () {
    $response = $this->postJson('/api/users', [
        'email' => 'test@example.com',
        'password' => 'securePass123'
    ]);
    $response->assertStatus(201)->assertJsonStructure(['id', 'email']);
    $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
});

Part 4 — TDD Flow in Practice

4.1 Standard TDD Workflow

Feature Requirement
        │
        ▼
  Identify Test Cases
  (unit → integration → e2e)
        │
        ▼
   Write Failing Test ──────────────────────┐
        │                                   │
        ▼                                   │
   Run Test → FAIL (RED) ✓                  │
        │                                   │
        ▼                                   │
   Write Minimum Code to Pass               │
        │                                   │
        ▼                                   │
   Run Test → PASS (GREEN) ✓                │
        │                                   │
        ▼                                   │
   Refactor (extract, simplify, type)       │
        │                                   │
        ▼                                   │
   Run All Tests → PASS ✓                   │
        │                                   │
        ▼                                   │
   Next Test Case ──────────────────────────┘
        │
        ▼
   PR + CI enforces coverage gate

4.2 TDD for New Projects

1. Set up test infrastructure FIRST (jest, coverage config, CI pipeline)
2. Define interfaces/contracts before implementations
3. Write service interface → test against interface → implement
4. Bottom-up: Repository → Service → Controller → E2E
5. Enforce coverage thresholds from day 1 (80% min)
6. Commit convention: test commits separate from feature commits

4.3 TDD for Legacy Projects (Retroactive)

This is harder. Use the Strangler Fig Pattern:

1. Do NOT rewrite everything — add tests around existing code first
2. Identify critical paths → write characterization tests first
   (these capture CURRENT behavior, not ideal behavior)
3. Refactor module by module, protected by characterization tests
4. Replace legacy code with TDD-developed replacements incrementally
5. Track coverage per module — set increasing baselines per sprint

Tool: Istanbul/c8 (JS), Coverage.py (Python), Xdebug (PHP)

Use --coverage-threshold flags per directory for gradual enforcement.

Part 5 — AI-Assisted TDD: The Wrapper System

This is your key architectural challenge: how do you ensure AI-generated code also meets your TDD standards?

5.1 The Problem

AI tools (Cursor, GitHub Copilot, Claude) generate code without context of your test standards. Developers may accept generated code without tests, leading to:

Inconsistent test naming conventions
Missing edge case coverage
Wrong test granularity
Tests that don't follow AAA (Arrange-Act-Assert) pattern

5.2 The Solution: TDD Standards Wrapper System

Layer 1 — Project-Level Rules File (.cursorrules or CLAUDE.md)

# TDD Contract — All Code Generated Must Follow These Rules

## Test Requirements
- Every function/method must have a corresponding .spec.ts file
- Tests follow AAA: Arrange → Act → Assert — labeled with comments
- Unit tests must mock ALL external dependencies
- No test should depend on another test's state
- Minimum one test per: happy path, error path, edge case

## Naming Convention
- Test file: [module].spec.ts (unit) / [module].e2e-spec.ts (integration)
- Describe block: class/function name
- It block: "should [expected behavior] when [condition]"

## Coverage Gate
- Lines: 80%, Branches: 75%, Functions: 80%
- New modules must not lower global coverage

## Test Structure Template
describe('[ModuleName]', () => {
  // Setup
  beforeEach(() => { /* setup */ });
  afterEach(() => { /* cleanup */ });

  describe('[methodName]', () => {
    it('should [behavior] when [condition]', () => {
      // Arrange
      // Act
      // Assert
    });
  });
});

Layer 2 — AI Prompt Wrapper (System Prompt / Custom Instructions)

When using Claude/Cursor for code generation, prefix with:

You are a senior engineer following strict TDD standards.
For every code change you make:
1. First output the test file (.spec.ts) using Jest + AAA pattern
2. Then output the implementation file
3. All external deps must be mocked in unit tests
4. Follow naming: "should [behavior] when [condition]"
5. Include: happy path, null/undefined edge case, error case
6. Do NOT write implementation before the test

Store this as:

/prompts/tdd-code-gen.md — for manual use
Cursor .cursorrules — auto-injected to all AI interactions
VS Code snippet — for quick scaffold generation

Layer 3 — Pre-commit Hooks (Enforcement)

// package.json
{
  "lint-staged": {
    "src/**/*.ts": ["jest --findRelatedTests --passWithNoTests --coverage"]
  },
  "husky": {
    "pre-commit": "lint-staged",
    "pre-push": "jest --coverage --coverageThreshold='{\"global\":{\"lines\":80}}'"
  }
}

Layer 4 — CI Pipeline Gate

# .github/workflows/test.yml
- name: Run Tests with Coverage
  run: |
    npm run test:cov
    # Fail if coverage drops below threshold
    npx jest --coverage --coverageThreshold='{"global":{"lines":80,"branches":75}}'

Layer 5 — ESLint Test Rules

// eslint plugin: eslint-plugin-jest
{
  "plugins": ["jest"],
  "rules": {
    "jest/expect-expect": "error",
    "jest/no-disabled-tests": "warn",
    "jest/no-focused-tests": "error",
    "jest/valid-expect": "error",
    "jest/consistent-test-it": ["error", { "fn": "it" }]
  }
}

Part 6 — Test Generation: Manual vs Automated

6.1 Manual Generation (AI-Assisted, Human-Reviewed)

Workflow:

Developer writes interface/type → prompts AI for test scaffold
AI generates test file using prompt wrapper (Layer 2)
Developer reviews, adds domain-specific edge cases
AI fills implementation given tests

Cursor workflow:

1. Create users.service.ts with method signatures only
2. Cmd+K: "Generate TDD tests for this service following .cursorrules"
3. Review + commit test file
4. Cmd+K: "Implement service methods to make these tests pass"
5. Run tests → iterate

6.2 Automated Generation Tools

Tool	Language	Type	Notes
Copilot Test Agent	All	AI-gen	GitHub Copilot feature
CodiumAI / Qodo	JS/TS/Python	AI-gen unit	Best for auto unit test gen
diffblue Cover	Java	AI	Enterprise Java only
Pynguin	Python	Search-based	Academic, generates pytest
TestPilot	JS	AI	Microsoft Research tool
jest-auto-spies	TS	Helper	Auto-generates spy objects

CodiumAI/Qodo is the current industry leader for automatic test generation in JS/TS/Python. It analyzes function signatures and generates multiple test cases automatically.

6.3 Scaffold Generation CLI (Custom Team Tool)

Build your own test scaffold generator:

// scripts/generate-test.ts
import { execSync } from 'child_process';
import * as fs from 'fs';

const moduleName = process.argv[2]; // e.g., "users"

const template = `
import { Test } from '@nestjs/testing';
import { ${toPascalCase(moduleName)}Service } from './${moduleName}.service';

describe('${toPascalCase(moduleName)}Service', () => {
  let service: ${toPascalCase(moduleName)}Service;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [${toPascalCase(moduleName)}Service]
    }).compile();
    service = module.get(${toPascalCase(moduleName)}Service);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });
});
`;

fs.writeFileSync(`src/${moduleName}/${moduleName}.service.spec.ts`, template);
console.log(`✓ Test scaffold created: ${moduleName}.service.spec.ts`);

// package.json
{
  "scripts": {
    "generate:test": "ts-node scripts/generate-test.ts"
  }
}

Usage: npm run generate:test users

Part 7 — Team Alignment & Standards

7.1 Developer Onboarding Doc (1-pager)

Every new developer should receive this contract:

TDD Contract — [Team Name]

1. No PR is merged without tests
2. Tests are written BEFORE implementation (or alongside for legacy)
3. Test naming: "should [behavior] when [condition]"
4. Pyramid ratio: 70% unit / 20% integration / 10% E2E
5. Coverage gate: 80% enforced in CI — PRs that drop coverage are blocked
6. Mocks: use jest.fn() / jest.spyOn() for external deps
7. Test data: use factory functions, never hardcoded magic values
8. AI-generated code must include AI-generated tests (use .cursorrules)
9. Failing tests in main branch = P0 incident
10. Review tests as carefully as implementation — they ARE documentation

7.2 PR Review Checklist for Tests

□ Does every new function have at least one test?
□ Are failure/error paths tested?
□ Are external deps properly mocked?
□ Do tests follow AAA pattern?
□ Are test descriptions meaningful (not "it works")?
□ Is there test data factory used (no magic strings)?
□ Does coverage remain above threshold?
□ Are integration tests using real DB (testcontainers) or proper mocks?

7.3 Test Factory Pattern (Team Standard)

// test/factories/user.factory.ts
import { faker } from '@faker-js/faker';

export const createUserDto = (overrides = {}) => ({
  id: faker.string.uuid(),
  email: faker.internet.email(),
  name: faker.person.fullName(),
  createdAt: new Date(),
  ...overrides
});

// Usage in tests:
const user = createUserDto({ email: 'specific@test.com' });

Part 8 — Package Ecosystem Summary

JavaScript / TypeScript

Package	Purpose	Verdict
Jest	Test runner + assertions	Industry standard for Node/NestJS
Vitest	Vite-native test runner	Preferred for React/Next.js/Vite
Supertest	HTTP integration testing	Standard for Express/NestJS
MSW	API mock server (browser + Node)	Industry standard for React
Testcontainers	Real DB in Docker for tests	Best for integration tests
@faker-js/faker	Test data generation	Standard
jest-mock-extended	TypeScript-aware auto-mocking	Recommended for NestJS
Pact.js	Consumer-driven contract tests	Microservices only
Playwright	E2E browser testing	Now preferred over Cypress
Cypress	E2E browser testing	Still strong, but Playwright winning

Python

Package	Purpose
pytest	Standard test runner
pytest-cov	Coverage
pytest-asyncio	Async test support
factory-boy	Test data factories
respx / httpx	HTTP mocking for async
pytest-mock	Mock integration

Laravel / PHP

Package	Purpose
Pest	Modern test framework (recommended)
PHPUnit	Legacy but still supported
Mockery	Mocking
Laravel Dusk	Browser E2E

Part 9 — What the Industry Is Doing Now

9.1 Current Trends (2024–2025)

AI-assisted test generation is mainstream now. GitHub Copilot, Cursor, and Qodo are being used to scaffold tests. The shift is: AI writes first drafts, engineers review and enforce standards.

Vitest is winning in frontend. For Vite-based projects (Vite + React, Next.js app router), Vitest is significantly faster than Jest due to native ESM support and Vite transform reuse.

Testcontainers adoption is rising. Instead of mocking DB entirely, teams spin up real PostgreSQL/Redis/MongoDB containers in CI via Testcontainers. Tests are more realistic but still isolated.

Contract testing in microservices is growing. Pact and Pactflow adoption is increasing as teams feel the pain of mismatched API contracts between services.

Playwright over Cypress for E2E. Playwright's multi-browser support, built-in parallelism, and better CI performance has made it the new default.

Test coverage as a PR gate, not a metric. Teams are moving away from tracking coverage as a KPI toward using it purely as a blocking threshold.

9.2 What Most Teams Actually Do

Reality check — not everyone does pure TDD:

Approach	Prevalence	Notes
Test-after (write code then test)	~50% of teams	Pragmatic, but riskier
TDD on critical paths only	~30% of teams	Balanced approach
Pure TDD	~10% of teams	Often fintech, healthcare
No tests	~10% of teams	Startups pre-product-market-fit

The pragmatic hybrid is most common: TDD for services/domain logic, integration tests for DB layer, Playwright for critical user flows.

Part 10 — Future Scope and Roadmap

10.1 Your Adoption Plan

Phase 1 — Foundation (Week 1–2)

Configure Jest/Vitest per stack
Set up coverage thresholds in CI
Add pre-commit hooks (Husky + lint-staged)
Create .cursorrules with TDD prompt wrapper
Create test factory templates per module

Phase 2 — Culture (Week 3–4)

PR checklist enforcement
Onboarding doc for new devs
First "TDD session" — pair-program a feature end-to-end
Retroactive coverage tracking for legacy modules

Phase 3 — Automation (Month 2)

Build test scaffold generator CLI
Evaluate Qodo/CodiumAI for auto test gen
Integrate Testcontainers for integration tests
Add contract tests for any inter-service APIs

Phase 4 — Maturity (Month 3+)

Coverage reports in PR comments (via jest-coverage-comment action)
Mutation testing with Stryker (tests your tests)
Test quality metrics (flakiness tracking, test execution time)

10.2 Mutation Testing (Advanced)

Mutation testing checks if your tests are actually meaningful:

npm install --save-dev @stryker-mutator/core @stryker-mutator/jest-runner
npx stryker run

Stryker introduces small bugs ("mutants") into your code and checks if your tests catch them. Mutation score > 70% means your tests have real value.

Appendix: Quick Reference

TDD Command Cheat Sheet

# NestJS
npm run test              # unit tests
npm run test:e2e          # integration/e2e tests  
npm run test:cov          # with coverage report

# React/Next.js (Vitest)
npx vitest                # watch mode
npx vitest run --coverage # single run with coverage

# Python
pytest tests/ -v --cov=app --cov-report=html

# Laravel
php artisan test --coverage
./vendor/bin/pest --coverage

Coverage Report Integration (GitHub Actions)

- uses: ArtiomTr/jest-coverage-report-action@v2
  with:
    test-script: npm run test:cov
    threshold: 80

Guide maintained by engineering team. Update when packages release major versions or architectural patterns shift.

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Tue, 23 Jun 2026 11:32:31 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Tue, 23 Jun 2026 10:41:05 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

Unit Test AI Guide — Zero Hallucination, Cross-Stack Standard

Bhaumik — Tue, 23 Jun 2026 10:23:07 +0000

Focus: Unit Tests ONLY — no integration, no E2E

Stacks: Node.js (NestJS/Express) · React.js · Python · Angular · Laravel

Goal: AI generates unit tests consistently, deterministically, without hallucination

IDE: Cursor (Primary) + Claude (Secondary)

Part 1 — Best Single Library Per Stack (Final Decision)

Do not mix libraries. Pick one per stack, configure it fully, never deviate.

Stack	Library	Why This One
Node.js / NestJS / Express	`Jest`	Native DI mocking, `@nestjs/testing` built around it, widest ecosystem
React.js	`Vitest` + `@testing-library/react`	Native Vite/ESM support, Jest-compatible API, 3–10x faster
Python	`pytest`	De facto standard, fixture system eliminates boilerplate, best plugin ecosystem
Angular	`Jest` (replace Karma)	Karma is deprecated in Angular 17+; Jest is the official migration target
Laravel	`Pest`	Modern syntax, built on PHPUnit, higher signal-to-noise ratio

Rule: If someone suggests a second library for the same stack, reject it. One library per stack, configured once, followed always.

Part 2 — IDE: Cursor (Only Choice for This Goal)

Why Cursor and Not VS Code / WebStorm

Capability	Cursor	VS Code + Copilot	WebStorm
Project-level AI rules	✅ `.cursor/rules/`	❌	❌
Codebase-aware context	✅ `@codebase`	Partial	Partial
Run terminal + read output	✅ Composer	❌	❌
Multi-file generation	✅ Agent mode	Limited	❌
Custom instructions per filetype	✅	❌	❌
MCP server integration	✅	❌	❌

Cursor Setup for This Project

project-root/
├── .cursor/
│   └── rules/
│       ├── unit-test-global.mdc       ← applies to all files
│       ├── unit-test-nestjs.mdc       ← applies to *.service.ts, *.guard.ts
│       ├── unit-test-react.mdc        ← applies to *.tsx, *.component.tsx
│       ├── unit-test-python.mdc       ← applies to *.py
│       ├── unit-test-angular.mdc      ← applies to *.component.ts, *.service.ts
│       └── unit-test-laravel.mdc      ← applies to *Service.php, *Model.php
├── CLAUDE.md                          ← Claude project memory file
└── ...

Part 3 — Cursor Rules Files (Anti-Hallucination Core)

These files are injected into every AI prompt automatically when working on matching files.

3.1 Global Unit Test Rule

File: .cursor/rules/unit-test-global.mdc

---
description: Global unit test rules — applies to all files in this project
globs: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.tsx", "**/*_test.py", "**/Test*.php"]
alwaysApply: true
---

# Unit Test Contract — MUST FOLLOW, NO EXCEPTIONS

## What is a unit test here
- Tests ONE class or function in complete isolation
- ALL external dependencies are mocked — no real DB, no real HTTP, no real file system
- Each test runs independently — no shared mutable state between tests
- Runs in < 100ms

## Structure: AAA — Always, Without Exception
Every test MUST have these three sections, with comments:

// Arrange — set up inputs, mocks, expected values
// Act — call the single function/method under test
// Assert — verify exactly one outcome


## Naming Convention — Mandatory
- File: `[module-name].spec.ts` or `[module-name].unit.spec.ts`
- Describe block: exact class or function name
- It/test block: "should [expected behavior] when [specific condition]"
  GOOD: "should throw NotFoundException when user does not exist"
  BAD:  "user not found", "test 1", "works correctly"

## What to test per function — minimum coverage
1. Happy path — valid input → expected output
2. Null/undefined input — how does it fail safely
3. Empty input — empty string, empty array, zero
4. Error path — when dependency throws, what happens
5. Boundary — max length, negative numbers, boolean edge

## What NOT to include in unit tests
- Database queries (mock the repository)
- HTTP calls (mock the service/axios/fetch)
- File system operations (mock fs)
- Timer behavior (use jest.useFakeTimers)
- Random values (mock Math.random or faker with fixed seed)

## AI Instruction
When asked to generate a unit test:
1. READ the function signature and types first
2. IDENTIFY all dependencies (constructor args, imported modules)
3. MOCK every dependency — never use real implementations
4. Generate minimum 4 test cases per method (happy, null, error, edge)
5. NEVER import from test doubles or assume what isn't in the source file
6. If you are unsure of a type — ASK, do not assume

3.2 NestJS Rule

File: .cursor/rules/unit-test-nestjs.mdc

---
description: NestJS unit test rules
globs: ["src/**/*.service.ts", "src/**/*.guard.ts", "src/**/*.interceptor.ts", "src/**/*.pipe.ts"]
---

# NestJS Unit Test Rules

## Library: Jest + @nestjs/testing + jest-mock-extended

## Always use Test.createTestingModule

typescript
const module = await Test.createTestingModule({
providers: [
SubjectService,
{ provide: DependencyService, useValue: mockDependency }
]
}).compile();


## Mock Pattern — jest-mock-extended

typescript
import { createMock } from '@golevelup/ts-jest';
// OR
import { mock } from 'jest-mock-extended';

const mockUserRepo = mock();


## Never
- Never use `new SubjectService()` directly — always use TestingModule
- Never let `useValue` contain real implementations
- Never test more than one service per describe block

## Repository Mock Template

typescript
const mockRepo = {
findOne: jest.fn(),
save: jest.fn(),
delete: jest.fn(),
findAll: jest.fn(),
update: jest.fn(),
};


## Required imports for every NestJS spec file

typescript
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException, BadRequestException } from '@nestjs/common';

markdown

3.3 React Rule

File: .cursor/rules/unit-test-react.mdc

---
description: React unit test rules
globs: ["src/**/*.tsx", "src/**/*.component.tsx", "src/hooks/**/*.ts"]
---

# React Unit Test Rules

## Library: Vitest + @testing-library/react + @testing-library/user-event

## Required setup in vitest.config.ts

typescript
export default defineConfig({
test: {
environment: 'jsdom',
globals: true,
setupFiles: ['./src/test/setup.ts']
}
})


## setup.ts

typescript
import '@testing-library/jest-dom';


## Component test structure

typescript
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { vi } from 'vitest';


## Mocking rules for React
- Mock ALL hooks that call APIs: `vi.mock('../hooks/useUsers')`
- Mock ALL context providers — wrap with test-specific providers
- Mock router: use `MemoryRouter` from react-router-dom
- NEVER mock internal state (useState) — test behavior, not implementation

## Query priority (RTL best practice — mandatory)
1. getByRole — prefer always
2. getByLabelText — for forms
3. getByText — for content
4. getByTestId — LAST RESORT only, requires data-testid attribute

## User event — always use userEvent, never fireEvent

typescript
const user = userEvent.setup();
await user.click(button);
await user.type(input, 'value');


## Custom hook testing

markdown

3.4 Python Rule

File: .cursor/rules/unit-test-python.mdc

---
description: Python unit test rules
globs: ["**/*.py", "!**/*migrations*"]
---

# Python Unit Test Rules

## Library: pytest + pytest-mock + factory-boy

## File naming
- Source: `app/services/user_service.py`
- Test:   `tests/unit/test_user_service.py`
- ALWAYS mirror the source directory structure under tests/unit/

## Class under test — always use dependency injection

python

GOOD — injectable dependency

class UserService:
def init(self, repo: UserRepository):
self.repo = repo

BAD — untestable

class UserService:
def init(self):
self.repo = UserRepository() # can't mock this


## Mock pattern — pytest-mock (mocker fixture)


## Async tests — pytest-asyncio

python
import pytest

@pytest.mark.asyncio
async def test_async_service(mocker):
mock_repo = mocker.AsyncMock()
...


## Fixture pattern — for shared setup

python
@pytest.fixture
def user_service(mocker):
repo = mocker.Mock()
return UserService(repo), repo

def test_get_user_happy_path(user_service):
service, repo = user_service
repo.find_by_id.return_value = User(id="1", email="a@b.com")
result = service.get_user("1")
assert result.email == "a@b.com"


## Naming
- File: `test_[module_name].py`
- Function: `test_[expected_behavior]_when_[condition]`

shell

3.5 Angular Rule

File: .cursor/rules/unit-test-angular.mdc

---
description: Angular unit test rules
globs: ["src/app/**/*.component.ts", "src/app/**/*.service.ts", "src/app/**/*.pipe.ts", "src/app/**/*.guard.ts"]
---

# Angular Unit Test Rules

## Library: Jest (NOT Karma — Karma is deprecated Angular 17+)

## Migration from Karma to Jest (one-time)

bash
ng add @angular-builders/jest


## TestBed configuration — always minimal

typescript
await TestBed.configureTestingModule({
imports: [ComponentUnderTest], // standalone components
providers: [
{ provide: UserService, useValue: mockUserService }
]
}).compileComponents();


## Service mock pattern

typescript
const mockUserService = {
getUser: jest.fn(),
createUser: jest.fn(),
};


## Component test — check DOM behavior, not internal state


## Pipe test — pure function, no TestBed needed

typescript
it('should transform date correctly', () => {
const pipe = new DateFormatPipe();
expect(pipe.transform(new Date('2024-01-01'))).toBe('Jan 1, 2024');
});


## Guard/resolver test — inject and call directly

typescript
const guard = TestBed.inject(AuthGuard);
const result = await guard.canActivate(mockRoute, mockState);
expect(result).toBe(false);

php

3.6 Laravel Rule

File: .cursor/rules/unit-test-laravel.mdc

---
description: Laravel unit test rules
globs: ["app/Services/**/*.php", "app/Models/**/*.php", "app/Http/Requests/**/*.php", "app/Actions/**/*.php"]
---

# Laravel Unit Test Rules

## Library: Pest (NOT PHPUnit directly — Pest wraps it with better syntax)

## File location
- Source: `app/Services/UserService.php`
- Test:   `tests/Unit/Services/UserServiceTest.php`

## Class under test — use constructor injection

php
class UserService {
public function __construct(
private readonly UserRepositoryInterface $repo
) {}
}


## Mock pattern — Mockery (included with Pest/PHPUnit)

// Act & Assert
expect(fn () => $service->getUser('abc'))
    ->toThrow(UserNotFoundException::class);

});


## Data provider pattern (Pest datasets)


## What NOT to do in unit tests
- Never call $this->get() or $this->post() — that is feature testing
- Never use RefreshDatabase — that is feature/integration testing
- Never resolve from service container — inject directly

markdown

Part 4 — CLAUDE.md (Claude Project Memory)

Place this at project root. Claude reads it on every session automatically.

File: CLAUDE.md

# Project: [Your Project Name]
# Claude Unit Test Instructions

## Stack
- Backend: NestJS + TypeScript
- Frontend: React + Vite + TypeScript
- Testing: Jest (NestJS) + Vitest (React) + Pest (Laravel) + pytest (Python)

## Unit Test Rules — NON-NEGOTIABLE

### When asked to generate a unit test:
1. NEVER generate integration or E2E tests unless explicitly asked
2. ALWAYS mock every external dependency
3. ALWAYS follow AAA (Arrange-Act-Assert) with comments
4. ALWAYS generate minimum 4 cases: happy path, null/empty, error thrown, edge case
5. NEVER use `any` type in TypeScript tests
6. NEVER leave `TODO` comments in generated tests

### Naming
- NestJS: `[name].service.spec.ts` inside same directory as source
- React: `[ComponentName].test.tsx` inside `__tests__/` or same directory
- Python: `test_[module].py` under `tests/unit/`
- Laravel: `[Name]Test.php` under `tests/Unit/`

### Test should describe BEHAVIOR, not implementation
GOOD: "should return empty array when no users match search"
BAD: "test getUserByFilter"

### If you are unsure of the correct mock structure:
- Ask what the dependency interface looks like
- Do NOT invent method names that don't exist in the source

### Coverage target: 80% lines, 75% branches per module

## Project Structure Reference
src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts   ← unit test lives here
      users.repository.ts
      users.repository.spec.ts

Part 5 — MCP Servers for Unit Testing in Cursor + Claude

MCP (Model Context Protocol) servers extend AI capabilities. For unit testing, these are the relevant ones:

5.1 Filesystem MCP (Built-in Cursor — use directly)

Cursor already has filesystem access. No extra MCP needed to read source files and generate tests. The .cursor/rules/ system handles this.

5.2 Available MCP Servers for Testing Workflows

1. @executeautomation/playwright-mcp-server

Scope: E2E only — not relevant for unit tests
Skip for this use case

2. @modelcontextprotocol/server-filesystem

Gives Claude access to project files
Use in Claude Desktop to read source → generate tests
Install: configured in claude_desktop_config.json

3. Custom Testing MCP (Build This — Highest Value)

Build a lightweight MCP server that:

Reads a source file
Extracts function signatures + types
Returns structured JSON to Claude
Claude generates tests from structure, not guesswork

// mcp-test-generator/src/index.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import * as ts from 'typescript';

const server = new Server({ name: 'test-generator', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler('tools/call', async (req) => {
  if (req.params.name === 'extract_signatures') {
    const { filePath } = req.params.arguments;
    const signatures = extractFunctionSignatures(filePath); // parse AST
    return { content: [{ type: 'text', text: JSON.stringify(signatures) }] };
  }
});

function extractFunctionSignatures(filePath: string) {
  // Use TypeScript compiler API to extract:
  // - class name
  // - method names
  // - parameter types
  // - return types
  // - injected dependencies (constructor params)
  const program = ts.createProgram([filePath], {});
  const sourceFile = program.getSourceFile(filePath);
  // ... AST traversal
  return { className, methods, dependencies };
}

Why this matters: When Claude receives typed signatures instead of raw source code, it cannot hallucinate — it generates tests from concrete types, not guesses.

5.3 Claude Desktop MCP Config

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"]
    },
    "test-generator": {
      "command": "node",
      "args": ["/path/to/your/mcp-test-generator/dist/index.js"]
    }
  }
}

5.4 Cursor MCP Config

// .cursor/mcp.json (project-level)
{
  "mcpServers": {
    "test-generator": {
      "command": "node",
      "args": ["./tools/mcp-test-generator/dist/index.js"]
    }
  }
}

Part 6 — Anti-Hallucination Prompt Templates

The root cause of AI hallucination in tests: AI invents method names, wrong mock structures, non-existent imports. These prompts eliminate that.

6.1 Cursor Cmd+K Prompt (Use This Exactly)

Generate a unit test file for this [NestJS service / React component / Python class / Angular service / Laravel service].

Rules:
- Library: [Jest / Vitest / pytest / Jest / Pest]
- Test only THIS file — no integration
- Mock ALL dependencies listed in the constructor/props
- Follow AAA pattern with comments
- Minimum 4 test cases per public method
- Use ONLY methods/properties that exist in this source file
- Do NOT import anything not shown in the source
- Naming: "should [behavior] when [condition]"

6.2 Claude Prompt (For CLAUDE.md aware sessions)

Read [filename].
Extract:
1. Class/function name
2. All public methods with parameter types and return types
3. All constructor dependencies (for mocking)

Then generate the unit test file following CLAUDE.md rules.
Do NOT assume any method exists unless you can see it in the source.

6.3 Batch Test Generation Prompt

For each file in [directory], generate a corresponding .spec.ts file.
Process one file at a time.
For each file:
  1. Read the source
  2. List the public methods you found (confirm before generating)
  3. Generate the test file
  4. Show the test file path

Do not proceed to the next file until the current one is confirmed.

Part 7 — Project Structure Convention

All stacks follow the same proximity principle: test file lives next to source file.

Node.js / NestJS / Angular

src/
  modules/
    users/
      users.service.ts
      users.service.spec.ts        ← unit test
      users.repository.ts
      users.repository.spec.ts     ← unit test
      users.guard.ts
      users.guard.spec.ts          ← unit test

React

src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx            ← unit test
      UserCard.stories.tsx         ← storybook (optional)
  hooks/
    useUserData.ts
    useUserData.test.ts            ← unit test

Python

app/
  services/
    user_service.py
tests/
  unit/
    services/
      test_user_service.py        ← mirrors app/ structure

Laravel

app/
  Services/
    UserService.php
tests/
  Unit/
    Services/
      UserServiceTest.php         ← mirrors app/ structure

Part 8 — CI Enforcement

All of this means nothing without enforcement. The pipeline is the final gate.

GitHub Actions — Multi-stack parallel

name: Unit Tests

on: [push, pull_request]

jobs:
  nestjs-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:unit -- --coverage --coverageThreshold='{"global":{"lines":80}}'

  react-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx vitest run --coverage

  python-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install -r requirements-dev.txt
      - run: pytest tests/unit/ --cov=app --cov-fail-under=80

  laravel-unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: { php-version: '8.3' }
      - run: composer install
      - run: ./vendor/bin/pest --coverage --min=80

Pre-commit Hook (Husky — Node stacks)

// package.json
{
  "lint-staged": {
    "src/**/*.service.ts": ["jest --findRelatedTests --passWithNoTests"],
    "src/**/*.tsx": ["vitest related --run"]
  }
}

Part 9 — Quick Start Checklist

New Project

□ Install test library (one per stack — see Part 1)
□ Configure jest.config.ts / vitest.config.ts / pytest.ini / pest.php
□ Create .cursor/rules/ directory with all rule files from Part 3
□ Create CLAUDE.md at project root from Part 4
□ Add coverage thresholds to config
□ Add pre-commit hooks (Husky for Node, pre-commit for Python)
□ Add CI workflow from Part 8
□ Create test factory files (one per major entity)
□ Write first failing test → implement → green → commit

Existing Project

□ Add test library without touching existing code
□ Add .cursor/rules/ + CLAUDE.md
□ Run coverage on existing code → document current baseline
□ Pick 3 critical services → generate tests → set as new baseline
□ Add CI with threshold = current baseline (not ideal — current)
□ Raise threshold by 5% per sprint

Appendix — Install Commands Per Stack

NestJS

npm install --save-dev jest ts-jest @types/jest @nestjs/testing jest-mock-extended @golevelup/ts-jest
npx ts-jest config:init

React (Vite)

npm install --save-dev vitest @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Python

pip install pytest pytest-cov pytest-mock pytest-asyncio factory-boy

Angular

ng add @angular-builders/jest
npm install --save-dev jest jest-preset-angular @types/jest

Laravel

composer require pestphp/pest pestphp/pest-plugin-laravel --dev
./vendor/bin/pest --init

Last updated: 2025 — verify library major versions before adopting

My First Automated Post

Bhaumik — Mon, 22 Jun 2026 13:12:30 +0000

This post was published automatically using BlogBot.

Why automation matters

Saving time is not just about efficiency — it compounds.

How it works

One markdown file. One command. Published.

My First Automated Post

Bhaumik — Mon, 22 Jun 2026 05:10:55 +0000

This post was published automatically using BlogBot.

Why automation matters

Saving time is not just about efficiency — it compounds.

How it works

One markdown file. One command. Published.