Cursor rule

1---
2description: 'Testing patterns and TDD workflow'
3globs: ['**/test/**/*.ts', '**/test/**/*.js', '**/__tests__/**/*.ts', '**/*.spec.ts', '**/*.test.ts']
4alwaysApply: true
5---
6 
7# Testing Standards
8 
9## Framework Stack
10 
11### Primary Testing Tools
12- **Mocha** - Test runner (used across all packages)
13- **Chai** - Assertion library
14- **@oclif/test** - Command testing support (for plugin packages)
15 
16### Test Setup
17- TypeScript compilation via ts-node/register
18- Source map support for stack traces
19- Global test timeout: 30 seconds (configurable per package)
20 
21## Test File Patterns
22 
23### Naming Conventions
24- **Primary**: `*.test.ts` (standard pattern across all packages)
25- **Location**: `test/unit/**/*.test.ts` (most packages)
26 
27### Directory Structure
28```
29packages/*/
30├── test/
31│   └── unit/
32│       ├── commands/          # Command-specific tests
33│       ├── services/          # Service/business logic tests
34│       └── utils/             # Utility function tests
35└── src/                        # Source code
36    ├── commands/              # CLI commands
37    ├── services/              # Business logic
38    └── utils/                 # Utilities
39```
40 
41## Mocha Configuration
42 
43### Standard Setup (.mocharc.json)
44```json
45{
46  "require": [
47    "test/helpers/init.js",
48    "ts-node/register", 
49    "source-map-support/register"
50  ],
51  "recursive": true,
52  "timeout": 30000,
53  "spec": "test/**/*.test.ts"
54}
55```
56 
57### TypeScript Compilation
58```json
59// package.json scripts
60{
61  "test": "mocha \"test/unit/**/*.test.ts\"",
62  "test:coverage": "nyc mocha \"test/unit/**/*.test.ts\""
63}
64```
65 
66## Test Structure
67 
68### Standard Test Pattern
69```typescript
70// ✅ GOOD - Comprehensive test structure
71describe('ConfigService', () => {
72  let service: ConfigService;
73 
74  beforeEach(() => {
75    service = new ConfigService();
76  });
77 
78  describe('loadConfig()', () => {
79    it('should load configuration successfully', async () => {
80      // Arrange
81      const expectedConfig = { region: 'us' };
82      
83      // Act
84      const result = await service.loadConfig();
85      
86      // Assert
87      expect(result).to.deep.equal(expectedConfig);
88    });
89 
90    it('should handle missing configuration', async () => {
91      // Arrange & Act & Assert
92      await expect(service.loadConfig()).to.be.rejectedWith('Config not found');
93    });
94  });
95});
96```
97 
98### Async/Await Pattern
99```typescript
100// ✅ GOOD - Use async/await in tests
101it('should process data asynchronously', async () => {
102  const result = await service.processAsync();
103  expect(result).to.exist;
104});
105 
106// ✅ GOOD - Explicit Promise handling
107it('should return a promise', () => {
108  return service.asyncMethod().then(result => {
109    expect(result).to.be.true;
110  });
111});
112```
113 
114## Mocking Patterns
115 
116### Class Mocking
117```typescript
118// ✅ GOOD - Mock class dependencies
119class MockConfigService {
120  async loadConfig() {
121    return { region: 'us' };
122  }
123}
124 
125it('should use mocked service', async () => {
126  const mockService = new MockConfigService();
127  const result = await mockService.loadConfig();
128  expect(result.region).to.equal('us');
129});
130```
131 
132### Function Stubs
133```typescript
134// ✅ GOOD - Stub module functions if needed
135beforeEach(() => {
136  // Stub file system operations
137  // Stub network calls
138});
139 
140afterEach(() => {
141  // Restore original implementations
142});
143```
144 
145## Command Testing
146 
147### OCLIF Test Pattern
148```typescript
149// ✅ GOOD - Test commands with @oclif/test
150import { test } from '@oclif/test';
151 
152describe('cm:config:region', () => {
153  test
154    .stdout()
155    .command(['cm:config:region', '--help'])
156    .it('shows help message', ctx => {
157      expect(ctx.stdout).to.contain('Display region');
158    });
159 
160  test
161    .stdout()
162    .command(['cm:config:region'])
163    .it('shows current region', ctx => {
164      expect(ctx.stdout).to.contain('us');
165    });
166});
167```
168 
169### Command Flag Testing
170```typescript
171// ✅ GOOD - Test command flags and arguments
172describe('cm:config:set', () => {
173  test
174    .command(['cm:config:set', '--help'])
175    .it('shows usage information');
176 
177  test
178    .command(['cm:config:set', '--region', 'eu'])
179    .it('sets region to eu');
180});
181```
182 
183## Error Testing
184 
185### Error Handling
186```typescript
187// ✅ GOOD - Test error scenarios
188it('should throw ValidationError on invalid input', async () => {
189  const invalidInput = '';
190  await expect(service.validate(invalidInput))
191    .to.be.rejectedWith('Invalid input');
192});
193 
194it('should handle network errors gracefully', async () => {
195  // Mock network failure
196  const result = await service.fetchWithRetry();
197  expect(result).to.be.null;
198});
199```
200 
201### Error Types
202```typescript
203// ✅ GOOD - Test specific error types
204it('should throw appropriate error', async () => {
205  try {
206    await service.failingOperation();
207  } catch (error) {
208    expect(error).to.be.instanceof(ValidationError);
209    expect(error.code).to.equal('INVALID_CONFIG');
210  }
211});
212```
213 
214## Test Data Management
215 
216### Mock Data Organization
217```typescript
218// ✅ GOOD - Organize test data
219const mockData = {
220  validConfig: {
221    region: 'us',
222    timeout: 30000,
223  },
224  invalidConfig: {
225    region: '',
226  },
227  users: [
228    { email: 'user1@example.com', name: 'User 1' },
229    { email: 'user2@example.com', name: 'User 2' },
230  ],
231};
232```
233 
234### Test Helpers
235```typescript
236// ✅ GOOD - Create reusable test utilities
237export function createMockConfig(overrides?: Partial<Config>): Config {
238  return {
239    region: 'us',
240    timeout: 30000,
241    ...overrides,
242  };
243}
244 
245export function createMockService(
246  config: Config = createMockConfig()
247): ConfigService {
248  return new ConfigService(config);
249}
250```
251 
252## Coverage
253 
254### Coverage Goals
255- **Team aspiration**: 80% minimum coverage
256- **Current enforcement**: Applied consistently across packages
257- **Focus areas**: Critical business logic and error paths
258 
259### Coverage Reporting
260```bash
261# Run tests with coverage
262pnpm test:coverage
263 
264# Coverage reports generated in:
265# - coverage/index.html (HTML report)
266# - coverage/coverage-summary.json (JSON report)
267```
268 
269## Critical Testing Rules
270 
271- **No real external calls** - Mock all dependencies
272- **Test both success and failure paths** - Cover error scenarios completely
273- **One assertion per test** - Focus each test on single behavior
274- **Use descriptive test names** - Test name should explain what's tested
275- **Arrange-Act-Assert** - Follow AAA pattern consistently
276- **Test command validation** - Verify flag validation and error messages
277- **Clean up after tests** - Restore any mocked state
278 
279## Best Practices
280 
281### Test Organization
282```typescript
283// ✅ GOOD - Organize related tests
284describe('AuthCommand', () => {
285  describe('login', () => {
286    it('should authenticate user');
287    it('should save token');
288  });
289  
290  describe('logout', () => {
291    it('should clear token');
292    it('should reset config');
293  });
294});
295```
296 
297### Async Test Patterns
298```typescript
299// ✅ GOOD - Handle async operations properly
300it('should complete async operation', async () => {
301  const promise = service.asyncMethod();
302  expect(promise).to.be.instanceof(Promise);
303  
304  const result = await promise;
305  expect(result).to.equal('success');
306});
307```
308 
309### Isolation
310```typescript
311// ✅ GOOD - Ensure test isolation
312describe('ConfigService', () => {
313  let service: ConfigService;
314  
315  beforeEach(() => {
316    service = new ConfigService();
317  });
318  
319  afterEach(() => {
320    // Clean up resources
321  });
322});
323```
324