Cursor rule

1---
2description: Guidelines for implementing and maintaining tests for Task Master CLI
3globs: "**/*.test.js,tests/**/*"
4---
5 
6# Testing Guidelines for Task Master CLI
7 
8## Test Organization Structure
9 
10- **Unit Tests**
11  - Located in `tests/unit/`
12  - Test individual functions and utilities in isolation
13  - Mock all external dependencies
14  - Keep tests small, focused, and fast
15  - Example naming: `utils.test.js`, `task-manager.test.js`
16 
17- **Integration Tests**
18  - Located in `tests/integration/`
19  - Test interactions between modules
20  - Focus on component interfaces rather than implementation details
21  - Use more realistic but still controlled test environments
22  - Example naming: `task-workflow.test.js`, `command-integration.test.js`
23 
24- **End-to-End Tests**
25  - Located in `tests/e2e/`
26  - Test complete workflows from a user perspective
27  - Focus on CLI commands as they would be used by users
28  - Example naming: `create-task.e2e.test.js`, `expand-task.e2e.test.js`
29 
30- **Test Fixtures**
31  - Located in `tests/fixtures/`
32  - Provide reusable test data
33  - Keep fixtures small and representative
34  - Export fixtures as named exports for reuse
35 
36## Test File Organization
37 
38```javascript
39// 1. Imports
40import { jest } from '@jest/globals';
41 
42// 2. Mock setup (MUST come before importing the modules under test)
43jest.mock('fs');
44jest.mock('@anthropic-ai/sdk');
45jest.mock('../../scripts/modules/utils.js', () => ({
46  CONFIG: {
47    projectVersion: '1.5.0'
48  },
49  log: jest.fn()
50}));
51 
52// 3. Import modules AFTER all mocks are defined
53import { functionToTest } from '../../scripts/modules/module-name.js';
54import { testFixture } from '../fixtures/fixture-name.js';
55import fs from 'fs';
56 
57// 4. Set up spies on mocked modules (if needed)
58const mockReadFileSync = jest.spyOn(fs, 'readFileSync');
59 
60// 5. Test suite with descriptive name
61describe('Feature or Function Name', () => {
62  // 6. Setup and teardown (if needed)
63  beforeEach(() => {
64    jest.clearAllMocks();
65    // Additional setup code
66  });
67  
68  afterEach(() => {
69    // Cleanup code
70  });
71  
72  // 7. Grouped tests for related functionality
73  describe('specific functionality', () => {
74    // 8. Individual test cases with clear descriptions
75    test('should behave in expected way when given specific input', () => {
76      // Arrange - set up test data
77      const input = testFixture.sampleInput;
78      mockReadFileSync.mockReturnValue('mocked content');
79      
80      // Act - call the function being tested
81      const result = functionToTest(input);
82      
83      // Assert - verify the result
84      expect(result).toBe(expectedOutput);
85      expect(mockReadFileSync).toHaveBeenCalledWith(expect.stringContaining('path'));
86    });
87  });
88});
89```
90 
91## Jest Module Mocking Best Practices
92 
93- **Mock Hoisting Behavior**
94  - Jest hoists `jest.mock()` calls to the top of the file, even above imports
95  - Always declare mocks before importing the modules being tested
96  - Use the factory pattern for complex mocks that need access to other variables
97 
98```javascript
99  // ✅ DO: Place mocks before imports
100  jest.mock('commander');
101  import { program } from 'commander';
102  
103  // ❌ DON'T: Define variables and then try to use them in mocks
104  const mockFn = jest.fn();
105  jest.mock('module', () => ({
106    func: mockFn // This won't work due to hoisting!
107  }));
108```
109 
110- **Mocking Modules with Function References**
111  - Use `jest.spyOn()` after imports to create spies on mock functions
112  - Reference these spies in test assertions
113  
114```javascript
115  // Mock the module first
116  jest.mock('fs');
117  
118  // Import the mocked module
119  import fs from 'fs';
120  
121  // Create spies on the mock functions
122  const mockExistsSync = jest.spyOn(fs, 'existsSync').mockReturnValue(true);
123  
124  test('should call existsSync', () => {
125    // Call function that uses fs.existsSync
126    const result = functionUnderTest();
127    
128    // Verify the mock was called correctly
129    expect(mockExistsSync).toHaveBeenCalled();
130  });
131```
132 
133- **Testing Functions with Callbacks**
134  - Get the callback from your mock's call arguments
135  - Execute it directly with test inputs
136  - Verify the results match expectations
137  
138```javascript
139  jest.mock('commander');
140  import { program } from 'commander';
141  import { setupCLI } from '../../scripts/modules/commands.js';
142  
143  const mockVersion = jest.spyOn(program, 'version').mockReturnValue(program);
144  
145  test('version callback should return correct version', () => {
146    // Call the function that registers the callback
147    setupCLI();
148    
149    // Extract the callback function
150    const versionCallback = mockVersion.mock.calls[0][0];
151    expect(typeof versionCallback).toBe('function');
152    
153    // Execute the callback and verify results
154    const result = versionCallback();
155    expect(result).toBe('1.5.0');
156  });
157```
158 
159## ES Module Testing Strategies
160 
161When testing ES modules (`"type": "module"` in package.json), traditional mocking approaches require special handling to avoid reference and scoping issues.
162 
163- **Module Import Challenges**
164  - Functions imported from ES modules may still reference internal module-scoped variables
165  - Imported functions may not use your mocked dependencies even with proper jest.mock() setup
166  - ES module exports are read-only properties (cannot be reassigned during tests)
167 
168- **Mocking Entire Modules**
169```javascript
170  // Mock the entire module with custom implementation
171  jest.mock('../../scripts/modules/task-manager.js', () => {
172    // Get original implementation for functions you want to preserve
173    const originalModule = jest.requireActual('../../scripts/modules/task-manager.js');
174    
175    // Return mix of original and mocked functionality
176    return {
177      ...originalModule,
178      generateTaskFiles: jest.fn() // Replace specific functions
179    };
180  });
181  
182  // Import after mocks
183  import * as taskManager from '../../scripts/modules/task-manager.js';
184  
185  // Now you can use the mock directly
186  const { generateTaskFiles } = taskManager;
187```
188 
189- **Direct Implementation Testing**
190  - Instead of calling the actual function which may have module-scope reference issues:
191```javascript
192  test('should perform expected actions', () => {
193    // Setup mocks for this specific test
194    mockReadJSON.mockImplementationOnce(() => sampleData);
195    
196    // Manually simulate the function's behavior
197    const data = mockReadJSON('path/file.json');
198    mockValidateAndFixDependencies(data, 'path/file.json');
199    
200    // Skip calling the actual function and verify mocks directly
201    expect(mockReadJSON).toHaveBeenCalledWith('path/file.json');
202    expect(mockValidateAndFixDependencies).toHaveBeenCalledWith(data, 'path/file.json');
203  });
204```
205 
206- **Avoiding Module Property Assignment**
207```javascript
208  // ❌ DON'T: This causes "Cannot assign to read only property" errors
209  const utils = await import('../../scripts/modules/utils.js');
210  utils.readJSON = mockReadJSON; // Error: read-only property
211  
212  // ✅ DO: Use the module factory pattern in jest.mock()
213  jest.mock('../../scripts/modules/utils.js', () => ({
214    readJSON: mockReadJSONFunc,
215    writeJSON: mockWriteJSONFunc
216  }));
217```
218 
219- **Handling Mock Verification Failures**
220  - If verification like `expect(mockFn).toHaveBeenCalled()` fails:
221    1. Check that your mock setup is before imports
222    2. Ensure you're using the right mock instance
223    3. Verify your test invokes behavior that would call the mock
224    4. Use `jest.clearAllMocks()` in beforeEach to reset mock state
225    5. Consider implementing a simpler test that directly verifies mock behavior
226 
227- **Full Example Pattern**
228```javascript
229  // 1. Define mock implementations
230  const mockReadJSON = jest.fn();
231  const mockValidateAndFixDependencies = jest.fn();
232  
233  // 2. Mock modules
234  jest.mock('../../scripts/modules/utils.js', () => ({
235    readJSON: mockReadJSON,
236    // Include other functions as needed
237  }));
238  
239  jest.mock('../../scripts/modules/dependency-manager.js', () => ({
240    validateAndFixDependencies: mockValidateAndFixDependencies
241  }));
242  
243  // 3. Import after mocks
244  import * as taskManager from '../../scripts/modules/task-manager.js';
245  
246  describe('generateTaskFiles function', () => {
247    beforeEach(() => {
248      jest.clearAllMocks();
249    });
250    
251    test('should generate task files', () => {
252      // 4. Setup test-specific mock behavior
253      const sampleData = { tasks: [{ id: 1, title: 'Test' }] };
254      mockReadJSON.mockReturnValueOnce(sampleData);
255      
256      // 5. Create direct implementation test
257      // Instead of calling: taskManager.generateTaskFiles('path', 'dir')
258      
259      // Simulate reading data
260      const data = mockReadJSON('path');
261      expect(mockReadJSON).toHaveBeenCalledWith('path');
262      
263      // Simulate other operations the function would perform
264      mockValidateAndFixDependencies(data, 'path');
265      expect(mockValidateAndFixDependencies).toHaveBeenCalledWith(data, 'path');
266    });
267  });
268```
269 
270## Mocking Guidelines
271 
272- **File System Operations**
273```javascript
274  import mockFs from 'mock-fs';
275  
276  beforeEach(() => {
277    mockFs({
278      'tasks': {
279        'tasks.json': JSON.stringify({
280          meta: { projectName: 'Test Project' },
281          tasks: []
282        })
283      }
284    });
285  });
286  
287  afterEach(() => {
288    mockFs.restore();
289  });
290```
291 
292- **API Calls (Anthropic/Claude)**
293```javascript
294  import { Anthropic } from '@anthropic-ai/sdk';
295  
296  jest.mock('@anthropic-ai/sdk');
297  
298  beforeEach(() => {
299    Anthropic.mockImplementation(() => ({
300      messages: {
301        create: jest.fn().mockResolvedValue({
302          content: [{ text: 'Mocked response' }]
303        })
304      }
305    }));
306  });
307```
308 
309- **Environment Variables**
310```javascript
311  const originalEnv = process.env;
312  
313  beforeEach(() => {
314    jest.resetModules();
315    process.env = { ...originalEnv };
316    process.env.MODEL = 'test-model';
317  });
318  
319  afterEach(() => {
320    process.env = originalEnv;
321  });
322```
323 
324## Testing Common Components
325 
326- **CLI Commands**
327  - Mock the action handlers and verify they're called with correct arguments
328  - Test command registration and option parsing
329  - Use `commander` test utilities or custom mocks
330 
331- **Task Operations**
332  - Use sample task fixtures for consistent test data
333  - Mock file system operations
334  - Test both success and error paths
335 
336- **UI Functions**
337  - Mock console output and verify correct formatting
338  - Test conditional output logic
339  - When testing strings with emojis or formatting, use `toContain()` or `toMatch()` rather than exact `toBe()` comparisons
340  - For functions with different behavior modes (e.g., `forConsole`, `forTable` parameters), create separate tests for each mode
341  - Test the structure of formatted output (e.g., check that it's a comma-separated list with the right number of items) rather than exact string matching
342  - When testing chalk-formatted output, remember that strict equality comparison (`toBe()`) can fail even when the visible output looks identical
343  - Consider using more flexible assertions like checking for the presence of key elements when working with styled text
344  - Mock chalk functions to return the input text to make testing easier while still verifying correct function calls
345 
346## Test Quality Guidelines
347 
348- ✅ **DO**: Write tests before implementing features (TDD approach when possible)
349- ✅ **DO**: Test edge cases and error conditions, not just happy paths
350- ✅ **DO**: Keep tests independent and isolated from each other
351- ✅ **DO**: Use descriptive test names that explain the expected behavior
352- ✅ **DO**: Maintain test fixtures separate from test logic
353- ✅ **DO**: Aim for 80%+ code coverage, with critical paths at 100%
354- ✅ **DO**: Follow the mock-first-then-import pattern for all Jest mocks
355 
356- ❌ **DON'T**: Test implementation details that might change
357- ❌ **DON'T**: Write brittle tests that depend on specific output formatting
358- ❌ **DON'T**: Skip testing error handling and validation
359- ❌ **DON'T**: Duplicate test fixtures across multiple test files
360- ❌ **DON'T**: Write tests that depend on execution order
361- ❌ **DON'T**: Define mock variables before `jest.mock()` calls (they won't be accessible due to hoisting)
362 
363 
364- **Task File Operations**
365  - ✅ DO: Use test-specific file paths (e.g., 'test-tasks.json') for all operations
366  - ✅ DO: Mock `readJSON` and `writeJSON` to avoid real file system interactions
367  - ✅ DO: Verify file operations use the correct paths in `expect` statements
368  - ✅ DO: Use different paths for each test to avoid test interdependence
369  - ✅ DO: Verify modifications on the in-memory task objects passed to `writeJSON`
370  - ❌ DON'T: Modify real task files (tasks.json) during tests
371  - ❌ DON'T: Skip testing file operations because they're "just I/O"
372  
373```javascript
374  // ✅ DO: Test file operations without real file system changes
375  test('should update task status in tasks.json', async () => {
376    // Setup mock to return sample data
377    readJSON.mockResolvedValue(JSON.parse(JSON.stringify(sampleTasks)));
378    
379    // Use test-specific file path
380    await setTaskStatus('test-tasks.json', '2', 'done');
381    
382    // Verify correct file path was read
383    expect(readJSON).toHaveBeenCalledWith('test-tasks.json');
384    
385    // Verify correct file path was written with updated content
386    expect(writeJSON).toHaveBeenCalledWith(
387      'test-tasks.json',
388      expect.objectContaining({
389        tasks: expect.arrayContaining([
390          expect.objectContaining({
391            id: 2,
392            status: 'done'
393          })
394        ])
395      })
396    );
397  });
398```
399 
400## Running Tests
401 
402```bash
403# Run all tests
404npm test
405 
406# Run tests in watch mode
407npm run test:watch
408 
409# Run tests with coverage reporting
410npm run test:coverage
411 
412# Run a specific test file
413npm test -- tests/unit/specific-file.test.js
414 
415# Run tests matching a pattern
416npm test -- -t "pattern to match"
417```
418 
419## Troubleshooting Test Issues
420 
421- **Mock Functions Not Called**
422  - Ensure mocks are defined before imports (Jest hoists `jest.mock()` calls)
423  - Check that you're referencing the correct mock instance
424  - Verify the import paths match exactly
425 
426- **Unexpected Mock Behavior**
427  - Clear mocks between tests with `jest.clearAllMocks()` in `beforeEach`
428  - Check mock implementation for conditional behavior
429  - Ensure mock return values are correctly configured for each test
430 
431- **Tests Affecting Each Other**
432  - Isolate tests by properly mocking shared resources
433  - Reset state in `beforeEach` and `afterEach` hooks
434  - Avoid global state modifications
435 
436## Common Testing Pitfalls and Solutions
437 
438- **Complex Library Mocking**
439  - **Problem**: Trying to create full mocks of complex libraries like Commander.js can be error-prone
440  - **Solution**: Instead of mocking the entire library, test the command handlers directly by calling your action handlers with the expected arguments
441```javascript
442  // ❌ DON'T: Create complex mocks of Commander.js
443  class MockCommand {
444    constructor() { /* Complex mock implementation */ }
445    option() { /* ... */ }
446    action() { /* ... */ }
447    // Many methods to implement
448  }
449  
450  // ✅ DO: Test the command handlers directly
451  test('should use default PRD path when no arguments provided', async () => {
452    // Call the action handler directly with the right params
453    await parsePrdAction(undefined, { numTasks: '10', output: 'tasks/tasks.json' });
454    
455    // Assert on behavior
456    expect(mockParsePRD).toHaveBeenCalledWith('scripts/prd.txt', 'tasks/tasks.json', 10);
457  });
458```
459 
460- **ES Module Mocking Challenges**
461  - **Problem**: ES modules don't support `require()` and imports are read-only
462  - **Solution**: Use Jest's module factory pattern and ensure mocks are defined before imports
463```javascript
464  // ❌ DON'T: Try to modify imported modules
465  import { detectCamelCaseFlags } from '../../scripts/modules/utils.js';
466  detectCamelCaseFlags = jest.fn(); // Error: Assignment to constant variable
467  
468  // ❌ DON'T: Try to use require with ES modules
469  const utils = require('../../scripts/modules/utils.js'); // Error in ES modules
470  
471  // ✅ DO: Use Jest module factory pattern
472  jest.mock('../../scripts/modules/utils.js', () => ({
473    detectCamelCaseFlags: jest.fn(),
474    toKebabCase: jest.fn()
475  }));
476  
477  // Import after mocks are defined
478  import { detectCamelCaseFlags } from '../../scripts/modules/utils.js';
479```
480 
481- **Function Redeclaration Errors**
482  - **Problem**: Declaring the same function twice in a test file causes errors
483  - **Solution**: Use different function names or create local test-specific implementations
484```javascript
485  // ❌ DON'T: Redefine imported functions with the same name
486  import { detectCamelCaseFlags } from '../../scripts/modules/utils.js';
487  
488  function detectCamelCaseFlags() { /* Test implementation */ }
489  // Error: Identifier has already been declared
490  
491  // ✅ DO: Use a different name for test implementations
492  function testDetectCamelCaseFlags() { /* Test implementation */ }
493```
494 
495- **Console.log Circular References**
496  - **Problem**: Creating infinite recursion by spying on console.log while also allowing it to log
497  - **Solution**: Implement a mock that doesn't call the original function
498```javascript
499  // ❌ DON'T: Create circular references with console.log
500  const mockConsoleLog = jest.spyOn(console, 'log');
501  mockConsoleLog.mockImplementation(console.log); // Creates infinite recursion
502  
503  // ✅ DO: Use a non-recursive mock implementation
504  const mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => {});
505```
506 
507- **Mock Function Method Issues**
508  - **Problem**: Trying to use jest.fn() methods on imported functions that aren't properly mocked
509  - **Solution**: Create explicit jest.fn() mocks for functions you need to call jest methods on
510```javascript
511  // ❌ DON'T: Try to use jest methods on imported functions without proper mocking
512  import { parsePRD } from '../../scripts/modules/task-manager.js';
513  parsePRD.mockClear(); // Error: parsePRD.mockClear is not a function
514  
515  // ✅ DO: Create proper jest.fn() mocks
516  const mockParsePRD = jest.fn().mockResolvedValue(undefined);
517  jest.mock('../../scripts/modules/task-manager.js', () => ({
518    parsePRD: mockParsePRD
519  }));
520  // Now you can use:
521  mockParsePRD.mockClear();
522```
523 
524- **EventEmitter Max Listeners Warning**
525  - **Problem**: Commander.js adds many listeners in complex mocks, causing warnings
526  - **Solution**: Either increase the max listeners limit or avoid deep mocking
527```javascript
528  // Option 1: Increase max listeners if you must mock Commander
529  class MockCommand extends EventEmitter {
530    constructor() {
531      super();
532      this.setMaxListeners(20); // Avoid MaxListenersExceededWarning
533    }
534  }
535  
536  // Option 2 (preferred): Test command handlers directly instead
537  // (as shown in the first example)
538```
539 
540- **Test Isolation Issues**
541  - **Problem**: Tests affecting each other due to shared mock state
542  - **Solution**: Reset all mocks in beforeEach and use separate test-specific mocks
543```javascript
544  // ❌ DON'T: Allow mock state to persist between tests
545  const globalMock = jest.fn().mockReturnValue('test');
546  
547  // ✅ DO: Clear mocks before each test
548  beforeEach(() => {
549    jest.clearAllMocks();
550    // Set up test-specific mock behavior
551    mockFunction.mockReturnValue('test-specific value');
552  });
553```
554 
555## Reliable Testing Techniques
556 
557- **Create Simplified Test Functions**
558  - Create simplified versions of complex functions that focus only on core logic
559  - Remove file system operations, API calls, and other external dependencies
560  - Pass all dependencies as parameters to make testing easier
561  
562```javascript
563  // Original function (hard to test)
564  const setTaskStatus = async (taskId, newStatus) => {
565    const tasksPath = 'tasks/tasks.json';
566    const data = await readJSON(tasksPath);
567    // Update task status logic
568    await writeJSON(tasksPath, data);
569    return data;
570  };
571  
572  // Test-friendly simplified function (easy to test)
573  const testSetTaskStatus = (tasksData, taskIdInput, newStatus) => {
574    // Same core logic without file operations
575    // Update task status logic on provided tasksData object
576    return tasksData; // Return updated data for assertions
577  };
578```
579 
580- **Avoid Real File System Operations**
581  - Never write to real files during tests
582  - Create test-specific versions of file operation functions
583  - Mock all file system operations including read, write, exists, etc.
584  - Verify function behavior using the in-memory data structures
585  
586```javascript
587  // Mock file operations
588  const mockReadJSON = jest.fn();
589  const mockWriteJSON = jest.fn();
590  
591  jest.mock('../../scripts/modules/utils.js', () => ({
592    readJSON: mockReadJSON,
593    writeJSON: mockWriteJSON,
594  }));
595  
596  test('should update task status correctly', () => {
597    // Setup mock data
598    const testData = JSON.parse(JSON.stringify(sampleTasks));
599    mockReadJSON.mockReturnValue(testData);
600    
601    // Call the function that would normally modify files
602    const result = testSetTaskStatus(testData, '1', 'done');
603    
604    // Assert on the in-memory data structure
605    expect(result.tasks[0].status).toBe('done');
606  });
607```
608 
609- **Data Isolation Between Tests**
610  - Always create fresh copies of test data for each test
611  - Use `JSON.parse(JSON.stringify(original))` for deep cloning
612  - Reset all mocks before each test with `jest.clearAllMocks()`
613  - Avoid state that persists between tests
614  
615```javascript
616  beforeEach(() => {
617    jest.clearAllMocks();
618    // Deep clone the test data
619    testTasksData = JSON.parse(JSON.stringify(sampleTasks));
620  });
621```
622 
623- **Test All Path Variations**
624  - Regular tasks and subtasks
625  - Single items and multiple items
626  - Success paths and error paths
627  - Edge cases (empty data, invalid inputs, etc.)
628  
629```javascript
630  // Multiple test cases covering different scenarios
631  test('should update regular task status', () => {
632    /* test implementation */
633  });
634  
635  test('should update subtask status', () => {
636    /* test implementation */
637  });
638  
639  test('should update multiple tasks when given comma-separated IDs', () => {
640    /* test implementation */
641  });
642  
643  test('should throw error for non-existent task ID', () => {
644    /* test implementation */
645  });
646```
647 
648- **Stabilize Tests With Predictable Input/Output**
649  - Use consistent, predictable test fixtures
650  - Avoid random values or time-dependent data
651  - Make tests deterministic for reliable CI/CD
652  - Control all variables that might affect test outcomes
653  
654```javascript
655  // Use a specific known date instead of current date
656  const fixedDate = new Date('2023-01-01T12:00:00Z');
657  jest.spyOn(global, 'Date').mockImplementation(() => fixedDate);
658```
659 
660See [tests/README.md](mdc:tests/README.md) for more details on the testing approach.
661 
662Refer to [jest.config.js](mdc:jest.config.js) for Jest configuration options.