TypeScript单元测试指南：Jest与NestJS测试工作流与最佳实践

typescript-unit-testing by bmad-labs/skills

211 周安装量

5 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bmad-labs/skills --skill typescript-unit-testing

Node.js TypeScript 测试

🇨🇳中文介绍

单元测试技能

单元测试通过模拟所有外部依赖，独立验证单个函数、方法和类。

工作流

对于单元测试任务的引导式、分步执行，请使用相应的工作流：

工作流	目的	何时使用
Setup	初始化测试基础设施	新项目或缺少测试设置时
Writing	编写新的单元测试	为组件创建测试时
Reviewing	审查现有测试	代码审查、质量审计时
Running	执行测试	运行测试、分析结果时
Debugging

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

minimal-run-and-audit：AI论文复现执行与审计技能，标准化测试与报告

17,300 周安装

Web应用安全最佳实践指南：HTTPS、输入验证、CSRF防护与合规性

14,100 周安装

代码审查最佳实践指南：完整流程、安全与性能审查清单

12,400 周安装

Vue 3 调试指南：解决响应式、计算属性与监听器常见错误

11,900 周安装

用户说/想要	要加载的工作流	文件
"设置测试"、"配置 Jest"、"为项目添加测试"、"安装测试依赖"	Setup	`workflows/setup/workflow.md`
"编写测试"、"添加测试"、"创建测试"、"测试这个服务/控制器"	Writing	`workflows/writing/workflow.md`
"审查测试"、"检查测试质量"、"审计测试"、"这些测试好吗？"	Reviewing	`workflows/reviewing/workflow.md`
"运行测试"、"执行测试"、"检查测试是否通过"、"显示测试结果"	Running	`workflows/running/workflow.md`
"修复测试"、"调试测试"、"测试失败了"、"为什么这个测试坏了？"	Debugging	`workflows/debugging/workflow.md`
"加速测试"、"优化测试"、"测试很慢"、"修复未关闭的句柄"	Optimizing	`workflows/optimizing/workflow.md`

references/
├── common/              # 核心测试基础
│   ├── knowledge.md     # 测试理念和测试金字塔
│   ├── rules.md         # 强制性测试规则（AAA、命名、覆盖率）
│   ├── assertions.md    # 断言模式和匹配器
│   ├── examples.md      # 按类别划分的综合示例
│   ├── detect-open-handles.md   # 未关闭句柄检测和清理
│   └── performance-optimization.md  # Jest 运行时优化
│
├── nestjs/              # NestJS 组件测试
│   ├── services.md      # 服务/用例测试模式
│   ├── controllers.md   # 控制器测试模式
│   ├── guards.md        # 守卫测试模式
│   ├── interceptors.md  # 拦截器测试模式
│   └── pipes-filters.md # 管道和过滤器测试
│
├── mocking/             # 模拟模式和策略
│   ├── deep-mocked.md   # @golevelup/ts-jest 模式
│   ├── jest-native.md   # Jest.fn、spyOn、模拟模式
│   └── factories.md     # 测试数据工厂模式
│
├── repository/          # 存储库测试
│   ├── mongodb.md       # mongodb-memory-server 模式
│   └── postgres.md      # pg-mem 模式
│
├── kafka/               # NestJS Kafka 微服务测试
│   └── kafka.md         # ClientKafka、@MessagePattern、@EventPattern 处理器
│
└── redis/               # Redis 缓存测试
    └── redis.md         # 缓存操作、健康检查、优雅降级

强制：阅读 references/common/rules.md - AAA 模式、命名、覆盖率
阅读 references/common/assertions.md - 断言最佳实践
阅读特定组件的文件：
- 服务：references/nestjs/services.md
- 控制器：references/nestjs/controllers.md
- 守卫：references/nestjs/guards.md
- 拦截器：references/nestjs/interceptors.md
- 管道/过滤器：references/nestjs/pipes-filters.md

阅读 references/mocking/deep-mocked.md - DeepMocked 模式
阅读 references/mocking/jest-native.md - 原生 Jest 模式
阅读 references/mocking/factories.md - 测试数据工厂

# 初始化会话（在测试会话开始时执行一次）
export UT_SESSION=$(date +%s)-$$

# 标准模式 - 将输出重定向到临时文件（无控制台输出）
npm test > /tmp/ut-${UT_SESSION}-output.log 2>&1

# 仅读取摘要（最后 50 行）
tail -50 /tmp/ut-${UT_SESSION}-output.log

# 获取失败详情
grep -B 2 -A 15 "FAIL\|✕" /tmp/ut-${UT_SESSION}-output.log

# 完成后清理
rm -f /tmp/ut-${UT_SESSION}-*.log /tmp/ut-${UT_SESSION}-*.md

/tmp/ut-${UT_SESSION}-output.log - 完整的测试输出
/tmp/ut-${UT_SESSION}-failures.md - 用于逐个修复的跟踪文件
/tmp/ut-${UT_SESSION}-debug.log - 调试运行
/tmp/ut-${UT_SESSION}-verify.log - 验证运行
/tmp/ut-${UT_SESSION}-coverage.log - 覆盖率输出

it('should return user when found', async () => {
  // Arrange
  const userId = 'user-123';
  mockRepository.findById.mockResolvedValue({
    id: userId,
    email: 'test@example.com',
    name: 'Test User',
  });

  // Act
  const result = await target.getUser(userId);

  // Assert
  expect(result).toEqual({
    id: userId,
    email: 'test@example.com',
    name: 'Test User',
  });
  expect(mockRepository.findById).toHaveBeenCalledWith(userId);
});

import { Test, TestingModule } from '@nestjs/testing';
import { createMock, DeepMocked } from '@golevelup/ts-jest';
import { MockLoggerService } from 'src/shared/logger/services/mock-logger.service';

describe('UserService', () => {
  let target: UserService;
  let mockRepository: DeepMocked<UserRepository>;

  beforeEach(async () => {
    // Arrange: Create mocks
    mockRepository = createMock<UserRepository>();

    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UserService,
        { provide: UserRepository, useValue: mockRepository },
      ],
    })
      .setLogger(new MockLoggerService())
      .compile();

    target = module.get<UserService>(UserService);
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  describe('getUser', () => {
    it('should return user when found', async () => {
      // Arrange
      mockRepository.findById.mockResolvedValue({
        id: 'user-123',
        email: 'test@example.com',
      });

      // Act
      const result = await target.getUser('user-123');

      // Assert
      expect(result).toEqual({ id: 'user-123', email: 'test@example.com' });
    });

    it('should throw NotFoundException when user not found', async () => {
      // Arrange
      mockRepository.findById.mockResolvedValue(null);

      // Act & Assert
      await expect(target.getUser('invalid')).rejects.toThrow(NotFoundException);
    });
  });
});

类别	优先级	描述
正常路径	强制	有效输入产生预期输出
边界情况	强制	空数组、空值、边界值
错误情况	强制	未找到、验证失败
异常行为	强制	正确的类型、错误代码、消息
业务规则	强制	领域逻辑、计算
输入验证	强制	无效输入、类型不匹配

初始化会话（在开始时执行一次）：
```
export UT_SESSION=$(date +%s)-$$
```
创建跟踪文件：/tmp/ut-${UT_SESSION}-failures.md，包含所有失败的测试
选择一个失败的测试 - 仅处理此测试

仅运行该测试（切勿运行完整套件）：

npm test -- -t "test name" > /tmp/ut-${UT_SESSION}-debug.log 2>&1
tail -50 /tmp/ut-${UT_SESSION}-debug.log

修复问题 - 分析错误，进行针对性修复

验证修复 - 运行同一测试 3-5 次：

for i in {1..5}; do npm test -- -t "test name" > /tmp/ut-${UT_SESSION}-run$i.log 2>&1 && echo "Run $i: PASS" || echo "Run $i: FAIL"; done

在跟踪文件中标记为已修复
移动到下一个失败的测试 - 重复步骤 3-7
在所有单个测试通过后，仅运行一次完整套件
清理：rm -f /tmp/ut-${UT_SESSION}-*.log /tmp/ut-${UT_SESSION}-*.md

变量	约定
被测系统	`target`
模拟对象	`mock` 前缀（`mockRepository`、`mockService`）
模拟类型	`DeepMocked<T>`

不要	原因	应改为
仅断言存在性	无法捕获错误的值	断言具体的值
条件断言	非确定性	分离测试用例
测试私有方法	与实现耦合	通过公共接口测试
在测试之间共享状态	导致测试不稳定	在 beforeEach 中重新设置
在服务中模拟存储库	测试实现	模拟接口
跳过模拟验证	不验证行为	验证模拟调用
测试接口/枚举/常量	无行为可测试	跳过这些文件

使用 target 表示被测系统
所有模拟对象使用 mock 前缀
使用 DeepMocked<T> 类型
包含 .setLogger(new MockLoggerService())
遵循带注释的 AAA 模式
在 afterEach 中重置模拟对象

🇺🇸English

Unit Testing Skill

Unit testing validates individual functions, methods, and classes in isolation by mocking all external dependencies.

Workflows

For guided, step-by-step execution of unit testing tasks, use the appropriate workflow:

Workflow	Purpose	When to Use
Setup	Initialize test infrastructure	New project or missing test setup
Writing	Write new unit tests	Creating tests for components
Reviewing	Review existing tests	Code review, quality audit
Running	Execute tests	Running tests, analyzing results
Debugging	Fix failing tests	Tests failing, need diagnosis
Optimizing	Improve test performance	Slow tests, maintainability

Workflow Selection Guide

IMPORTANT : Before starting any testing task, identify the user's intent and load the appropriate workflow.

Detect User Intent → Select Workflow

User Says / Wants	Workflow to Load	File
"Set up tests", "configure Jest", "add testing to project", "install test dependencies"	Setup	`workflows/setup/workflow.md`
"Write tests", "add tests", "create tests", "test this service/controller"	Writing	`workflows/writing/workflow.md`
"Review tests", "check test quality", "audit tests", "are these tests good?"	Reviewing	`workflows/reviewing/workflow.md`
"Run tests", "execute tests", "check if tests pass", "show test results"	Running	`workflows/running/workflow.md`

Workflow Execution Protocol

ALWAYS load the workflow file first - Read the full workflow before taking action
Follow each step in order - Complete checkpoints before proceeding
Load knowledge files as directed - Each workflow specifies which references/ files to read
Verify compliance after completion - Re-read relevant reference files to ensure quality

Knowledge Base Structure

references/
├── common/              # Core testing fundamentals
│   ├── knowledge.md     # Testing philosophy and test pyramid
│   ├── rules.md         # Mandatory testing rules (AAA, naming, coverage)
│   ├── assertions.md    # Assertion patterns and matchers
│   ├── examples.md      # Comprehensive examples by category
│   ├── detect-open-handles.md   # Open handle detection and cleanup
│   └── performance-optimization.md  # Jest runtime optimization
│
├── nestjs/              # NestJS component testing
│   ├── services.md      # Service/usecase testing patterns
│   ├── controllers.md   # Controller testing patterns
│   ├── guards.md        # Guard testing patterns
│   ├── interceptors.md  # Interceptor testing patterns
│   └── pipes-filters.md # Pipe and filter testing
│
├── mocking/             # Mock patterns and strategies
│   ├── deep-mocked.md   # @golevelup/ts-jest patterns
│   ├── jest-native.md   # Jest.fn, spyOn, mock patterns
│   └── factories.md     # Test data factory patterns
│
├── repository/          # Repository testing
│   ├── mongodb.md       # mongodb-memory-server patterns
│   └── postgres.md      # pg-mem patterns
│
├── kafka/               # NestJS Kafka microservices testing
│   └── kafka.md         # ClientKafka, @MessagePattern, @EventPattern handlers
│
└── redis/               # Redis cache testing
    └── redis.md         # Cache operations, health checks, graceful degradation

Quick Reference by Task

Write Unit Tests

MANDATORY : Read references/common/rules.md - AAA pattern, naming, coverage
Read references/common/assertions.md - Assertion best practices
Read component-specific files:
- Services : references/nestjs/services.md
- Controllers : references/nestjs/controllers.md
- Guards : references/nestjs/guards.md
- Interceptors : references/nestjs/interceptors.md
- Pipes/Filters : references/nestjs/pipes-filters.md

Setup Mocking

Read references/mocking/deep-mocked.md - DeepMocked patterns
Read references/mocking/jest-native.md - Native Jest patterns
Read references/mocking/factories.md - Test data factories

Test Repositories

MongoDB : references/repository/mongodb.md
PostgreSQL : references/repository/postgres.md

Test Kafka (NestJS Microservices)

Read references/kafka/kafka.md - ClientKafka mocking, @MessagePattern/@EventPattern handlers, emit/send testing

Test Redis

Read references/redis/redis.md - Cache operations, health checks, graceful degradation

Examples

Read references/common/examples.md for comprehensive patterns

Optimize Test Performance

Read references/common/performance-optimization.md - Worker config, caching, CI optimization
Read references/common/detect-open-handles.md - Fix open handles preventing clean exit

Debug Open Handles

Read references/common/detect-open-handles.md - Detection commands, common handle types, cleanup patterns

Core Principles

0. Context Efficiency (Temp File Output)

ALWAYS redirect unit test output to temp files, NOT console. Test output can be verbose and bloats agent context.

IMPORTANT : Use unique session ID in filenames to prevent conflicts when multiple agents run.

# Initialize session (once at start of testing session)
export UT_SESSION=$(date +%s)-$$

# Standard pattern - redirect output to temp file (NO console output)
npm test > /tmp/ut-${UT_SESSION}-output.log 2>&1

# Read summary only (last 50 lines)
tail -50 /tmp/ut-${UT_SESSION}-output.log

# Get failure details
grep -B 2 -A 15 "FAIL\|✕" /tmp/ut-${UT_SESSION}-output.log

# Cleanup when done
rm -f /tmp/ut-${UT_SESSION}-*.log /tmp/ut-${UT_SESSION}-*.md

Temp Files (with ${UT_SESSION} unique per agent):

/tmp/ut-${UT_SESSION}-output.log - Full test output
/tmp/ut-${UT_SESSION}-failures.md - Tracking file for one-by-one fixing
/tmp/ut-${UT_SESSION}-debug.log - Debug runs
/tmp/ut-${UT_SESSION}-verify.log - Verification runs
/tmp/ut-${UT_SESSION}-coverage.log - Coverage output

1. AAA Pattern (Mandatory)

ALL unit tests MUST follow Arrange-Act-Assert:

it('should return user when found', async () => {
  // Arrange
  const userId = 'user-123';
  mockRepository.findById.mockResolvedValue({
    id: userId,
    email: 'test@example.com',
    name: 'Test User',
  });

  // Act
  const result = await target.getUser(userId);

  // Assert
  expect(result).toEqual({
    id: userId,
    email: 'test@example.com',
    name: 'Test User',
  });
  expect(mockRepository.findById).toHaveBeenCalledWith(userId);
});

2. Use `target` for SUT

Always name the system under test as target:

let target: UserService;
let mockRepository: DeepMocked<UserRepository>;

3. DeepMocked Pattern

Use @golevelup/ts-jest for type-safe mocks:

import { createMock, DeepMocked } from '@golevelup/ts-jest';

let mockService: DeepMocked<UserService>;

beforeEach(() => {
  mockService = createMock<UserService>();
});

4. Specific Assertions

Assert exact values, not just existence:

// WRONG
expect(result).toBeDefined();
expect(result.id).toBeDefined();

// CORRECT
expect(result).toEqual({
  id: 'user-123',
  email: 'test@example.com',
  name: 'Test User',
});

5. Mock All Dependencies

Mock external services, never real databases for unit tests:

// Unit Test: Mock repository
{ provide: UserRepository, useValue: mockRepository }

// Repository Test: Use in-memory database
const mongoServer = await createMongoMemoryServer();

Standard Test Template

import { Test, TestingModule } from '@nestjs/testing';
import { createMock, DeepMocked } from '@golevelup/ts-jest';
import { MockLoggerService } from 'src/shared/logger/services/mock-logger.service';

describe('UserService', () => {
  let target: UserService;
  let mockRepository: DeepMocked<UserRepository>;

  beforeEach(async () => {
    // Arrange: Create mocks
    mockRepository = createMock<UserRepository>();

    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UserService,
        { provide: UserRepository, useValue: mockRepository },
      ],
    })
      .setLogger(new MockLoggerService())
      .compile();

    target = module.get<UserService>(UserService);
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  describe('getUser', () => {
    it('should return user when found', async () => {
      // Arrange
      mockRepository.findById.mockResolvedValue({
        id: 'user-123',
        email: 'test@example.com',
      });

      // Act
      const result = await target.getUser('user-123');

      // Assert
      expect(result).toEqual({ id: 'user-123', email: 'test@example.com' });
    });

    it('should throw NotFoundException when user not found', async () => {
      // Arrange
      mockRepository.findById.mockResolvedValue(null);

      // Act & Assert
      await expect(target.getUser('invalid')).rejects.toThrow(NotFoundException);
    });
  });
});

Test Coverage Requirements

Category	Priority	Description
Happy path	MANDATORY	Valid inputs producing expected outputs
Edge cases	MANDATORY	Empty arrays, null values, boundaries
Error cases	MANDATORY	Not found, validation failures
Exception behavior	MANDATORY	Correct type, error code, message
Business rules	MANDATORY	Domain logic, calculations
Input validation	MANDATORY	Invalid inputs, type mismatches

Coverage Target: 80%+ for new code

Failure Resolution Protocol

CRITICAL: Fix ONE test at a time. NEVER run full suite repeatedly while fixing.

When unit tests fail:

Initialize session (once at start):
```
export UT_SESSION=$(date +%s)-$$
```
Create tracking file : /tmp/ut-${UT_SESSION}-failures.md with all failing tests
Select ONE failing test - work on only this test

Run ONLY that test (never full suite):

npm test -- -t "test name" > /tmp/ut-${UT_SESSION}-debug.log 2>&1
tail -50 /tmp/ut-${UT_SESSION}-debug.log

Fix the issue - analyze error, make targeted fix

Verify fix - run same test 3-5 times:

for i in {1..5}; do npm test -- -t "test name" > /tmp/ut-${UT_SESSION}-run$i.log 2>&1 && echo "Run $i: PASS" || echo "Run $i: FAIL"; done

Mark as FIXED in tracking file
- repeat steps 3-7

WHY : Running full suite wastes time and context. Each failing test pollutes output, making debugging harder.

Naming Conventions

Test Files

Pattern: *.spec.ts
Location: Co-located with source file

Test Structure

describe('ClassName', () => {
  describe('methodName', () => {
    it('should [expected behavior] when [condition]', () => {});
  });
});

Variable Names

Variable	Convention
SUT	`target`
Mocks	`mock` prefix (`mockRepository`, `mockService`)
Mock Type	`DeepMocked<T>`

What NOT to Unit Test

Do NOT create unit tests for:

Interfaces - Type definitions only, no runtime behavior
Enums - Static value mappings, no logic to test
Constants - Static values, no behavior
Type aliases - Type definitions only
Plain DTOs - Data structures without logic

Only test files containing executable logic (classes with methods, functions with behavior).

Anti-Patterns to Avoid

Don't	Why	Do Instead
Assert only existence	Doesn't catch wrong values	Assert specific values
Conditional assertions	Non-deterministic	Separate test cases
Test private methods	Couples to implementation	Test via public interface
Share state between tests	Causes flaky tests	Fresh setup in beforeEach
Mock repositories in services	Tests implementation	Mock interfaces
Skip mock verification	Doesn't validate behavior	Verify mock calls
Test interfaces/enums/constants	No behavior to test	Skip these files

Checklist

Setup:

Use target for system under test
Use mock prefix for all mocks
Use DeepMocked<T> type
Include .setLogger(new MockLoggerService())
Follow AAA pattern with comments
Reset mocks in afterEach

Coverage:

Happy path tests for all public methods
Edge case tests (empty, null, boundaries)
Error case tests (not found, validation failures)
Exception type and error code verification
Mock call verification (parameters + count)

Quality:

80%+ coverage on new code
No assertions on log calls
No test interdependence
Tests fail when any field differs

Weekly Installs

103

Repository

bmad-labs/skills

GitHub Stars

First Seen

Jan 26, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode90

claude-code86

github-copilot82

codex81

gemini-cli79

cursor71

TypeScript单元测试指南：Jest与NestJS测试工作流与最佳实践

🇨🇳中文介绍

单元测试技能

工作流

相关 Skills

工作流选择指南

检测用户意图 → 选择工作流

工作流执行协议

知识库结构

按任务快速参考

编写单元测试

设置模拟

测试存储库

测试 Kafka（NestJS 微服务）

测试 Redis

示例

优化测试性能

调试未关闭句柄

核心原则

0. 上下文效率（临时文件输出）

1. AAA 模式（强制）

2. 使用 target 表示被测系统

3. DeepMocked 模式

4. 具体断言

5. 模拟所有依赖项

标准测试模板

测试覆盖率要求

失败解决协议

命名约定

测试文件

测试结构

变量名

不应进行单元测试的内容

应避免的反模式

检查清单