metacoding 1.0.0 → 1.1.0

package/templates/typescript/typescript.testing.instructions.md

@@ -0,0 +1,740 @@
+---
+description: 'TypeScript/Node.js-specific testing patterns and frameworks'
+applyTo: 'test/**/*.{ts,js}'
+language: 'typescript'
+---
+
+# TypeScript/Node.js Testing Standards
+
+## Testing Framework and Setup
+
+### Primary Testing Framework: Jest
+
+```typescript
+// jest.config.js
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/test'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+};
+```
+
+### Test Case Naming Conventions
+
+**Area Prefixes for Node.js/Backend:**
+
+- `API` - API endpoint tests
+- `SRV` - Service layer tests
+- `DB` - Database/Data layer tests
+- `MW` - Middleware tests
+- `ROUTE` - Routing logic tests
+- `AUTH` - Authentication/Authorization tests
+- `UTIL` - Utility function tests
+- `CONFIG` - Configuration management tests
+- `CORE` - Core business logic tests
+- `INT` - Integration tests
+- `E2E` - End-to-end tests
+
+**Examples:**
+
+- `API-UNIT-001` - First unit test for API endpoints
+- `SRV-UNIT-001` - First unit test for Service layer
+- `DB-INT-001` - First integration test for Database
+- `E2E-FLOW-001` - First end-to-end workflow test
+
+## Unit Testing Patterns
+
+### Service Layer Testing
+
+```typescript
+// test/unit/user-service.test.ts
+import { UserService } from '../../src/services/user-service';
+import { UserRepository } from '../../src/repositories/user-repository';
+import { User } from '../../src/types/user';
+
+// Mock the repository
+jest.mock('../../src/repositories/user-repository');
+const MockUserRepository = UserRepository as jest.MockedClass<
+  typeof UserRepository
+>;
+
+describe('UserService', () => {
+  let userService: UserService;
+  let mockUserRepository: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockUserRepository =
+      new MockUserRepository() as jest.Mocked<UserRepository>;
+    userService = new UserService(mockUserRepository);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getUserById', () => {
+    it('should return user when user exists', async () => {
+      // Arrange
+      const userId = '123';
+      const expectedUser: User = {
+        id: userId,
+        name: 'John Doe',
+        email: 'john@example.com',
+      };
+      mockUserRepository.findById.mockResolvedValue(expectedUser);
+
+      // Act
+      const result = await userService.getUserById(userId);
+
+      // Assert
+      expect(result).toEqual(expectedUser);
+      expect(mockUserRepository.findById).toHaveBeenCalledWith(userId);
+      expect(mockUserRepository.findById).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error when user not found', async () => {
+      // Arrange
+      const userId = '999';
+      mockUserRepository.findById.mockResolvedValue(null);
+
+      // Act & Assert
+      await expect(userService.getUserById(userId)).rejects.toThrow(
+        'User not found'
+      );
+
+      expect(mockUserRepository.findById).toHaveBeenCalledWith(userId);
+    });
+  });
+});
+```
+
+### API Endpoint Testing
+
+```typescript
+// test/unit/user-controller.test.ts
+import request from 'supertest';
+import { app } from '../../src/app';
+import { UserService } from '../../src/services/user-service';
+
+// Mock the service
+jest.mock('../../src/services/user-service');
+const MockUserService = UserService as jest.MockedClass<typeof UserService>;
+
+describe('User Controller', () => {
+  let mockUserService: jest.Mocked<UserService>;
+
+  beforeEach(() => {
+    mockUserService = new MockUserService() as jest.Mocked<UserService>;
+    // Inject mock into controller if using dependency injection
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('GET /api/users/:id', () => {
+    it('should return user when valid id provided', async () => {
+      // Arrange
+      const userId = '123';
+      const mockUser = {
+        id: userId,
+        name: 'John Doe',
+        email: 'john@example.com',
+      };
+      mockUserService.getUserById.mockResolvedValue(mockUser);
+
+      // Act
+      const response = await request(app)
+        .get(`/api/users/${userId}`)
+        .expect(200);
+
+      // Assert
+      expect(response.body).toEqual(mockUser);
+      expect(mockUserService.getUserById).toHaveBeenCalledWith(userId);
+    });
+
+    it('should return 404 when user not found', async () => {
+      // Arrange
+      const userId = '999';
+      mockUserService.getUserById.mockRejectedValue(
+        new Error('User not found')
+      );
+
+      // Act
+      const response = await request(app)
+        .get(`/api/users/${userId}`)
+        .expect(404);
+
+      // Assert
+      expect(response.body).toEqual({ error: 'User not found' });
+    });
+
+    it('should return 400 when invalid id format', async () => {
+      // Arrange
+      const invalidId = 'invalid-id';
+
+      // Act
+      const response = await request(app)
+        .get(`/api/users/${invalidId}`)
+        .expect(400);
+
+      // Assert
+      expect(response.body).toEqual({ error: 'Invalid user ID format' });
+    });
+  });
+});
+```
+
+### Utility Function Testing
+
+```typescript
+// test/unit/string-utils.test.ts
+import { capitalize, slugify, truncate } from '../../src/utils/string-utils';
+
+describe('String Utils', () => {
+  describe('capitalize', () => {
+    it('should capitalize first letter of string', () => {
+      expect(capitalize('hello')).toBe('Hello');
+    });
+
+    it('should handle empty string', () => {
+      expect(capitalize('')).toBe('');
+    });
+
+    it('should handle single character', () => {
+      expect(capitalize('a')).toBe('A');
+    });
+
+    it('should not change already capitalized string', () => {
+      expect(capitalize('Hello')).toBe('Hello');
+    });
+  });
+
+  describe('slugify', () => {
+    it('should convert spaces to hyphens', () => {
+      expect(slugify('Hello World')).toBe('hello-world');
+    });
+
+    it('should remove special characters', () => {
+      expect(slugify('Hello! @World#')).toBe('hello-world');
+    });
+
+    it('should handle multiple spaces', () => {
+      expect(slugify('Hello   World')).toBe('hello-world');
+    });
+  });
+
+  describe('truncate', () => {
+    it('should truncate long strings', () => {
+      const longString = 'This is a very long string that should be truncated';
+      expect(truncate(longString, 20)).toBe('This is a very lo...');
+    });
+
+    it('should not truncate short strings', () => {
+      const shortString = 'Short';
+      expect(truncate(shortString, 20)).toBe('Short');
+    });
+  });
+});
+```
+
+## Integration Testing
+
+### Database Integration Testing
+
+```typescript
+// test/integration/user-repository.test.ts
+import { UserRepository } from '../../src/repositories/user-repository';
+import { DatabaseConnection } from '../../src/database/connection';
+import { User } from '../../src/types/user';
+
+describe('UserRepository Integration', () => {
+  let userRepository: UserRepository;
+  let db: DatabaseConnection;
+
+  beforeAll(async () => {
+    // Setup test database
+    db = new DatabaseConnection(process.env.TEST_DATABASE_URL);
+    await db.connect();
+    userRepository = new UserRepository(db);
+  });
+
+  afterAll(async () => {
+    await db.disconnect();
+  });
+
+  beforeEach(async () => {
+    // Clean database before each test
+    await db.query('DELETE FROM users');
+  });
+
+  describe('findById', () => {
+    it('should find existing user', async () => {
+      // Arrange
+      const userData: Omit<User, 'id'> = {
+        name: 'John Doe',
+        email: 'john@example.com',
+      };
+      const createdUser = await userRepository.create(userData);
+
+      // Act
+      const foundUser = await userRepository.findById(createdUser.id);
+
+      // Assert
+      expect(foundUser).toEqual(createdUser);
+    });
+
+    it('should return null for non-existent user', async () => {
+      // Act
+      const foundUser = await userRepository.findById('999');
+
+      // Assert
+      expect(foundUser).toBeNull();
+    });
+  });
+
+  describe('create', () => {
+    it('should create new user with generated id', async () => {
+      // Arrange
+      const userData: Omit<User, 'id'> = {
+        name: 'Jane Doe',
+        email: 'jane@example.com',
+      };
+
+      // Act
+      const createdUser = await userRepository.create(userData);
+
+      // Assert
+      expect(createdUser).toMatchObject(userData);
+      expect(createdUser.id).toBeDefined();
+      expect(typeof createdUser.id).toBe('string');
+    });
+
+    it('should enforce unique email constraint', async () => {
+      // Arrange
+      const userData: Omit<User, 'id'> = {
+        name: 'John Doe',
+        email: 'duplicate@example.com',
+      };
+      await userRepository.create(userData);
+
+      // Act & Assert
+      await expect(userRepository.create(userData)).rejects.toThrow(
+        'Email already exists'
+      );
+    });
+  });
+});
+```
+
+### API Integration Testing
+
+```typescript
+// test/integration/user-api.test.ts
+import request from 'supertest';
+import { app } from '../../src/app';
+import { DatabaseConnection } from '../../src/database/connection';
+
+describe('User API Integration', () => {
+  let db: DatabaseConnection;
+
+  beforeAll(async () => {
+    db = new DatabaseConnection(process.env.TEST_DATABASE_URL);
+    await db.connect();
+  });
+
+  afterAll(async () => {
+    await db.disconnect();
+  });
+
+  beforeEach(async () => {
+    await db.query('DELETE FROM users');
+  });
+
+  describe('POST /api/users', () => {
+    it('should create new user and return 201', async () => {
+      // Arrange
+      const userData = {
+        name: 'John Doe',
+        email: 'john@example.com',
+      };
+
+      // Act
+      const response = await request(app)
+        .post('/api/users')
+        .send(userData)
+        .expect(201);
+
+      // Assert
+      expect(response.body).toMatchObject(userData);
+      expect(response.body.id).toBeDefined();
+    });
+
+    it('should validate required fields', async () => {
+      // Arrange
+      const invalidData = {
+        name: 'John Doe',
+        // Missing email
+      };
+
+      // Act
+      const response = await request(app)
+        .post('/api/users')
+        .send(invalidData)
+        .expect(400);
+
+      // Assert
+      expect(response.body.error).toContain('email is required');
+    });
+  });
+
+  describe('GET /api/users', () => {
+    it('should return list of users', async () => {
+      // Arrange
+      const users = [
+        { name: 'John Doe', email: 'john@example.com' },
+        { name: 'Jane Doe', email: 'jane@example.com' },
+      ];
+
+      for (const user of users) {
+        await request(app).post('/api/users').send(user);
+      }
+
+      // Act
+      const response = await request(app).get('/api/users').expect(200);
+
+      // Assert
+      expect(response.body).toHaveLength(2);
+      expect(response.body[0]).toMatchObject(users[0]);
+      expect(response.body[1]).toMatchObject(users[1]);
+    });
+  });
+});
+```
+
+## Mocking Strategies
+
+### External Service Mocking
+
+```typescript
+// test/mocks/external-api.ts
+import nock from 'nock';
+
+export const mockExternalAPI = {
+  mockUserLookup: (userId: string, userData: any) => {
+    return nock('https://api.external-service.com')
+      .get(`/users/${userId}`)
+      .reply(200, userData);
+  },
+
+  mockUserLookupError: (userId: string, statusCode: number = 500) => {
+    return nock('https://api.external-service.com')
+      .get(`/users/${userId}`)
+      .reply(statusCode, { error: 'External service error' });
+  },
+
+  cleanup: () => {
+    nock.cleanAll();
+  },
+};
+
+// Usage in tests
+describe('External Service Integration', () => {
+  afterEach(() => {
+    mockExternalAPI.cleanup();
+  });
+
+  it('should handle external API success', async () => {
+    // Arrange
+    const userId = '123';
+    const userData = { id: userId, name: 'John Doe' };
+    mockExternalAPI.mockUserLookup(userId, userData);
+
+    // Act & Assert
+    const result = await externalService.getUser(userId);
+    expect(result).toEqual(userData);
+  });
+});
+```
+
+### File System Mocking
+
+```typescript
+// test/unit/file-service.test.ts
+import fs from 'fs/promises';
+import { FileService } from '../../src/services/file-service';
+
+// Mock fs module
+jest.mock('fs/promises');
+const mockFs = fs as jest.Mocked<typeof fs>;
+
+describe('FileService', () => {
+  let fileService: FileService;
+
+  beforeEach(() => {
+    fileService = new FileService();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('readConfig', () => {
+    it('should read and parse JSON config file', async () => {
+      // Arrange
+      const configData = { host: 'localhost', port: 3000 };
+      const configJson = JSON.stringify(configData);
+      mockFs.readFile.mockResolvedValue(configJson);
+
+      // Act
+      const result = await fileService.readConfig('/path/to/config.json');
+
+      // Assert
+      expect(result).toEqual(configData);
+      expect(mockFs.readFile).toHaveBeenCalledWith(
+        '/path/to/config.json',
+        'utf8'
+      );
+    });
+
+    it('should handle file read errors', async () => {
+      // Arrange
+      mockFs.readFile.mockRejectedValue(new Error('File not found'));
+
+      // Act & Assert
+      await expect(
+        fileService.readConfig('/nonexistent/config.json')
+      ).rejects.toThrow('File not found');
+    });
+  });
+});
+```
+
+## Async Testing Patterns
+
+### Promise Testing
+
+```typescript
+// test/unit/async-service.test.ts
+import { AsyncService } from '../../src/services/async-service';
+
+describe('AsyncService', () => {
+  let asyncService: AsyncService;
+
+  beforeEach(() => {
+    asyncService = new AsyncService();
+  });
+
+  describe('processData', () => {
+    it('should process data asynchronously', async () => {
+      // Arrange
+      const inputData = ['item1', 'item2', 'item3'];
+
+      // Act
+      const result = await asyncService.processData(inputData);
+
+      // Assert
+      expect(result).toHaveLength(3);
+      expect(result[0]).toContain('processed');
+    });
+
+    it('should handle processing errors', async () => {
+      // Arrange
+      const invalidData = [null, undefined];
+
+      // Act & Assert
+      await expect(asyncService.processData(invalidData)).rejects.toThrow(
+        'Invalid data provided'
+      );
+    });
+  });
+
+  describe('processWithTimeout', () => {
+    it('should complete within timeout', async () => {
+      // Arrange
+      const data = 'test data';
+      const timeout = 1000;
+
+      // Act
+      const startTime = Date.now();
+      const result = await asyncService.processWithTimeout(data, timeout);
+      const endTime = Date.now();
+
+      // Assert
+      expect(result).toBeDefined();
+      expect(endTime - startTime).toBeLessThan(timeout);
+    });
+
+    it('should timeout for long operations', async () => {
+      // Arrange
+      const data = 'long processing data';
+      const shortTimeout = 100;
+
+      // Act & Assert
+      await expect(
+        asyncService.processWithTimeout(data, shortTimeout)
+      ).rejects.toThrow('Operation timed out');
+    });
+  });
+});
+```
+
+### Event Emitter Testing
+
+```typescript
+// test/unit/event-service.test.ts
+import { EventService } from '../../src/services/event-service';
+
+describe('EventService', () => {
+  let eventService: EventService;
+
+  beforeEach(() => {
+    eventService = new EventService();
+  });
+
+  afterEach(() => {
+    eventService.removeAllListeners();
+  });
+
+  describe('user events', () => {
+    it('should emit user created event', (done) => {
+      // Arrange
+      const userData = { id: '123', name: 'John Doe' };
+
+      // Act
+      eventService.on('user:created', (data) => {
+        // Assert
+        expect(data).toEqual(userData);
+        done();
+      });
+
+      eventService.createUser(userData);
+    });
+
+    it('should handle multiple listeners', () => {
+      // Arrange
+      const userData = { id: '123', name: 'John Doe' };
+      const listener1 = jest.fn();
+      const listener2 = jest.fn();
+
+      eventService.on('user:created', listener1);
+      eventService.on('user:created', listener2);
+
+      // Act
+      eventService.createUser(userData);
+
+      // Assert
+      expect(listener1).toHaveBeenCalledWith(userData);
+      expect(listener2).toHaveBeenCalledWith(userData);
+    });
+  });
+});
+```
+
+## Performance Testing
+
+### Benchmark Testing
+
+```typescript
+// test/performance/string-utils.perf.test.ts
+import { performance } from 'perf_hooks';
+import { processLargeString } from '../../src/utils/string-utils';
+
+describe('String Utils Performance', () => {
+  const PERFORMANCE_THRESHOLD = 100; // milliseconds
+
+  describe('processLargeString', () => {
+    it('should process large string within performance threshold', () => {
+      // Arrange
+      const largeString = 'x'.repeat(1000000); // 1MB string
+
+      // Act
+      const startTime = performance.now();
+      const result = processLargeString(largeString);
+      const endTime = performance.now();
+
+      // Assert
+      expect(result).toBeDefined();
+      expect(endTime - startTime).toBeLessThan(PERFORMANCE_THRESHOLD);
+    });
+  });
+});
+```
+
+## Test Utilities and Helpers
+
+### Test Data Factories
+
+```typescript
+// test/factories/user-factory.ts
+import { User } from '../../src/types/user';
+
+export class UserFactory {
+  static create(overrides: Partial<User> = {}): User {
+    return {
+      id: Math.random().toString(36).substr(2, 9),
+      name: 'Test User',
+      email: 'test@example.com',
+      createdAt: new Date(),
+      ...overrides,
+    };
+  }
+
+  static createMany(count: number, overrides: Partial<User> = {}): User[] {
+    return Array.from({ length: count }, (_, index) =>
+      this.create({
+        ...overrides,
+        email: `test${index}@example.com`,
+      })
+    );
+  }
+}
+
+// Usage in tests
+describe('User Service', () => {
+  it('should process multiple users', () => {
+    const users = UserFactory.createMany(5);
+    expect(users).toHaveLength(5);
+    expect(users[0].email).toBe('test0@example.com');
+  });
+});
+```
+
+### Custom Matchers
+
+```typescript
+// test/matchers/custom-matchers.ts
+export const customMatchers = {
+  toBeValidUser(received: any) {
+    const pass =
+      typeof received === 'object' &&
+      typeof received.id === 'string' &&
+      typeof received.name === 'string' &&
+      typeof received.email === 'string' &&
+      received.email.includes('@');
+
+    return {
+      message: () => `Expected ${received} to be a valid user object`,
+      pass,
+    };
+  },
+};
+
+// Setup in test files
+expect.extend(customMatchers);
+
+// Usage
+describe('User Service', () => {
+  it('should return valid user', () => {
+    const user = userService.getUser('123');
+    expect(user).toBeValidUser();
+  });
+});
+```