Skip to content

ever-co/ever-works / .agents/skills/nestjs-best-practices

nestjs-best-practices

Verified

NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.

FileKindSize
AGENTS.mdmarkdown154.2 KB
README.mdmarkdown4.7 KB
SKILL.mdskill md4.8 KB
rules/_sections.mdmarkdown2.1 KB
rules/_template.mdmarkdown633 B
rules/api-use-dto-serialization.mdmarkdown4.2 KB
rules/api-use-interceptors.mdmarkdown5.4 KB
rules/api-use-pipes.mdmarkdown5.3 KB
rules/api-versioning.mdmarkdown4.7 KB
rules/arch-avoid-circular-deps.mdmarkdown1.9 KB
rules/arch-feature-modules.mdmarkdown2.3 KB
rules/arch-module-sharing.mdmarkdown3.7 KB
rules/arch-single-responsibility.mdmarkdown2.8 KB
rules/arch-use-events.mdmarkdown2.9 KB
rules/arch-use-repository-pattern.mdmarkdown2.7 KB
rules/db-avoid-n-plus-one.mdmarkdown3.8 KB
rules/db-use-migrations.mdmarkdown3.7 KB
rules/db-use-transactions.mdmarkdown3.6 KB
rules/devops-graceful-shutdown.mdmarkdown5.5 KB
rules/devops-use-config-module.mdmarkdown4.2 KB
rules/devops-use-logging.mdmarkdown5.1 KB
rules/di-avoid-service-locator.mdmarkdown2.8 KB
rules/di-interface-segregation.mdmarkdown5.0 KB
rules/di-liskov-substitution.mdmarkdown6.8 KB
rules/di-prefer-constructor-injection.mdmarkdown2.2 KB
rules/di-scope-awareness.mdmarkdown2.5 KB
rules/di-use-interfaces-tokens.mdmarkdown2.5 KB
rules/error-handle-async-errors.mdmarkdown3.4 KB
rules/error-throw-http-exceptions.mdmarkdown3.0 KB
rules/error-use-exception-filters.mdmarkdown3.4 KB
rules/micro-use-health-checks.mdmarkdown6.1 KB
rules/micro-use-patterns.mdmarkdown5.0 KB
rules/micro-use-queues.mdmarkdown5.7 KB
rules/perf-async-hooks.mdmarkdown2.8 KB
rules/perf-lazy-loading.mdmarkdown3.6 KB
rules/perf-optimize-database.mdmarkdown3.0 KB
rules/perf-use-caching.mdmarkdown3.3 KB
rules/security-auth-jwt.mdmarkdown3.8 KB
rules/security-rate-limiting.mdmarkdown3.1 KB
rules/security-sanitize-output.mdmarkdown3.7 KB
rules/security-use-guards.mdmarkdown3.4 KB
rules/security-validate-all-input.mdmarkdown3.2 KB
rules/test-e2e-supertest.mdmarkdown4.4 KB
rules/test-mock-external-services.mdmarkdown4.2 KB
rules/test-use-testing-module.mdmarkdown4.1 KB
scripts/build-agents.tsscript8.1 KB
scripts/build.shscript369 B
scripts/package-lock.jsonmanifest7.7 KB
scripts/package.jsonmanifest410 B

rules/test-use-testing-module.md

View on GitHub
---
title: Use Testing Module for Unit Tests
impact: HIGH
impactDescription: Enables proper isolated testing with mocked dependencies
tags: testing, unit-tests, mocking, jest
---

## Use Testing Module for Unit Tests

Use `@nestjs/testing` module to create isolated test environments with mocked dependencies. This ensures your tests run fast, don't depend on external services, and properly test your business logic in isolation.

**Incorrect (manual instantiation bypassing DI):**

```typescript
// Instantiate services manually without DI
describe('UsersService', () => {
	it('should create user', async () => {
		// Manual instantiation bypasses DI
		const repo = new UserRepository(); // Real repo!
		const service = new UsersService(repo);

		const user = await service.create({ name: 'Test' });
		// This hits the real database!
	});
});

// Test implementation details
describe('UsersController', () => {
	it('should call service', async () => {
		const service = { create: jest.fn() };
		const controller = new UsersController(service as any);

		await controller.create({ name: 'Test' });

		expect(service.create).toHaveBeenCalled(); // Tests implementation, not behavior
	});
});
```

**Correct (use Test.createTestingModule with mocked dependencies):**

```typescript
// Use Test.createTestingModule for proper DI
import { Test, TestingModule } from '@nestjs/testing';

describe('UsersService', () => {
	let service: UsersService;
	let repo: jest.Mocked<UserRepository>;

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

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

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

	describe('create', () => {
		it('should save and return user', async () => {
			const dto = { name: 'John', email: 'john@test.com' };
			const expectedUser = { id: '1', ...dto };

			repo.save.mockResolvedValue(expectedUser);

			const result = await service.create(dto);

			expect(result).toEqual(expectedUser);
			expect(repo.save).toHaveBeenCalledWith(dto);
		});

		it('should throw on duplicate email', async () => {
			repo.findOne.mockResolvedValue({ id: '1', email: 'test@test.com' });

			await expect(service.create({ name: 'Test', email: 'test@test.com' })).rejects.toThrow(ConflictException);
		});
	});

	describe('findById', () => {
		it('should return user when found', async () => {
			const user = { id: '1', name: 'John' };
			repo.findOne.mockResolvedValue(user);

			const result = await service.findById('1');

			expect(result).toEqual(user);
		});

		it('should throw NotFoundException when not found', async () => {
			repo.findOne.mockResolvedValue(null);

			await expect(service.findById('999')).rejects.toThrow(NotFoundException);
		});
	});
});

// Testing guards and interceptors
describe('RolesGuard', () => {
	let guard: RolesGuard;
	let reflector: Reflector;

	beforeEach(async () => {
		const module = await Test.createTestingModule({
			providers: [RolesGuard, Reflector]
		}).compile();

		guard = module.get<RolesGuard>(RolesGuard);
		reflector = module.get<Reflector>(Reflector);
	});

	it('should allow when no roles required', () => {
		const context = createMockExecutionContext({ user: { roles: [] } });
		jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);

		expect(guard.canActivate(context)).toBe(true);
	});

	it('should allow admin for admin-only route', () => {
		const context = createMockExecutionContext({ user: { roles: ['admin'] } });
		jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(['admin']);

		expect(guard.canActivate(context)).toBe(true);
	});
});

function createMockExecutionContext(request: Partial<Request>): ExecutionContext {
	return {
		switchToHttp: () => ({
			getRequest: () => request
		}),
		getHandler: () => jest.fn(),
		getClass: () => jest.fn()
	} as ExecutionContext;
}
```

Reference: [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall