jest-nestjs

name: jest-nestjs description: > Jest + NestJS testing patterns for unit and e2e tests in Aurora projects. Trigger: When writing tests, mocking dependencies, or implementing test coverage in NestJS/Aurora. license: MIT metadata: author: aurora version: "1.1" auto_invoke: "Writing tests, mocking services, testing handlers" allowed-tools: Read, Edit, Write, Glob, Grep, Bash

When to Use

Use this skill when:

• Writing unit tests for handlers, services, or aggregates
• Creating e2e tests for API endpoints
• Mocking NestJS dependencies (repositories, services, event bus)
• Testing CQRS commands and queries
• Testing Aurora-generated code
• Setting up test fixtures and factories

Testing Philosophy in Aurora/NestJS

Unit Tests: Test individual components in isolation

• Handlers (Command/Query), Services, Aggregates/Value Objects, Mappers

e2e Tests: Test complete flows through the API layer

• REST endpoints, GraphQL resolvers, Authentication, Database interactions

Detailed References

• Unit Testing Patterns — Command/query handlers, mocking repos, mocking external services, bus mocks
• E2E Testing Patterns — REST controllers, GraphQL resolvers
• Aurora-Specific Testing — Value objects, aggregates, test organization

Best Practices

✅ DO

1. Isolate tests: Each test should be independent
2. Use descriptive names: "should throw error when price is negative"
3. Follow AAA pattern: Arrange, Act, Assert
4. Mock external dependencies: Database, APIs, services
5. Test edge cases: Null, undefined, empty arrays, boundaries
6. Test error paths: Exceptions, validation errors
7. Use factories/fixtures: Reusable test data builders
8. Keep tests fast: Unit tests < 100ms, e2e < 1s
9. Clean up: Use afterEach to reset state
10. Test one thing: One assertion per test (when possible)

❌ DON'T

1. Don't test implementation details: Test behavior, not internals
2. Don't test framework code: Trust NestJS, TypeORM, etc.
3. Don't share state: Between tests or describe blocks
4. Don't use real database: In unit tests (use mocks)
5. Don't skip tests: Fix or remove broken tests
6. Don't test getters/setters: Unless they have logic
7. Don't duplicate tests: Avoid redundant test cases
8. Don't test generated code: Trust Aurora generation (test custom logic only)
9. Don't ignore coverage: Aim for >80% on custom code

Coverage Guidelines

Target Coverage:

• Custom handlers: 100% (all custom logic)
• Services: 90%+ (critical business logic)
• Aggregates: 90%+ (domain rules)
• Value Objects: 80%+ (validation logic)
• Controllers/Resolvers: 80%+ (e2e coverage acceptable)
• Generated code: Skip (trust Aurora)

Run Coverage:

npm run test:cov       # Unit tests with coverage
npm run test:e2e       # e2e tests
npm run test:watch     # Watch mode for TDD

Jest Configuration

jest.config.js (typical Aurora setup):

module.exports = {
    moduleFileExtensions: ['js', 'json', 'ts'],
    rootDir: 'src',
    testRegex: '.*\\.spec\\.ts$',
    transform: {
        '^.+\\.(t|j)s$': 'ts-jest',
    },
    collectCoverageFrom: [
        '**/*.(t|j)s',
        '!**/*.module.ts',
        '!**/*.index.ts',
        '!**/node_modules/**',
        '!**/dist/**',
        '!**/infrastructure/seeds/**',
    ],
    coverageDirectory: '../coverage',
    testEnvironment: 'node',
    moduleNameMapper: {
        '^@app/(.*)$': '<rootDir>/$1',
        '^@core/(.*)$': '<rootDir>/@core/$1',
        '^@api/(.*)$': '<rootDir>/@api/$1',
    },
};

Quick Reference

Remember

• Unit tests = Fast, isolated, mock dependencies
• e2e tests = Slow, integrated, real dependencies
• Test custom logic only: Don't test Aurora-generated code
• Mark your code: Use #region AI-generated code in handlers
• TDD when possible: Write test → Implement → Refactor