n8n-mcp/tests/PHASE3_CONTEXT.md

Phase 3 Implementation Context

Quick Start for Implementation

You are implementing Phase 3 of the testing strategy. Phase 2 (test infrastructure) is complete. Your task is to write comprehensive unit tests for all services in src/services/.

Immediate Action Items

1. Start with Priority 1 Services (in order):

   • config-validator.ts - Complete existing tests (currently ~20% coverage)
   • enhanced-config-validator.ts - Complete existing tests (currently ~15% coverage)
   • workflow-validator.ts - Complete existing tests (currently ~10% coverage)

2. Use Existing Infrastructure:

   • Framework: Vitest (already configured)
   • Test location: tests/unit/services/
   • Factories: tests/fixtures/factories/
   • Imports: Use @/ alias for src, @tests/ for test utils

Critical Context

1. Validation Services Architecture

ConfigValidator (base)
    ↓
EnhancedConfigValidator (extends base, adds operation awareness)
    ↓
NodeSpecificValidators (used by both)

2. Key Testing Patterns

For Validators:

describe('ConfigValidator', () => {
  describe('validate', () => {
    it('should detect missing required fields', () => {
      const result = ConfigValidator.validate(nodeType, config, properties);
      expect(result.valid).toBe(false);
      expect(result.errors).toContainEqual(
        expect.objectContaining({
          type: 'missing_required',
          property: 'channel'
        })
      );
    });
  });
});

For API Client:

vi.mock('axios');
const mockAxios = axios as jest.Mocked<typeof axios>;

describe('N8nApiClient', () => {
  beforeEach(() => {
    mockAxios.create.mockReturnValue({
      get: vi.fn(),
      post: vi.fn(),
      // ... etc
    });
  });
});

3. Complex Scenarios to Test

ConfigValidator:

• Property visibility with displayOptions (show/hide conditions)
• Node-specific validation (HTTP Request, Webhook, Code nodes)
• Security validations (hardcoded credentials, SQL injection)
• Type validation (string, number, boolean, options)

WorkflowValidator:

• Invalid node types (missing package prefix)
• Connection validation (cycles, orphaned nodes)
• Expression validation within workflow context
• Error handling properties (onError, retryOnFail)
• AI Agent workflows with tool connections

WorkflowDiffEngine:

• All operation types (addNode, removeNode, updateNode, etc.)
• Transaction-like behavior (all succeed or all fail)
• Node name vs ID handling
• Connection cleanup when removing nodes

Testing Infrastructure Available

1. Database Mocking:

   vi.mock('better-sqlite3');
   

2. Node Factory (already exists):

   import { slackNodeFactory } from '@tests/fixtures/factories/node.factory';
   

3. Type Imports:

   import type { ValidationResult, ValidationError } from '@/services/config-validator';
   

Common Pitfalls to Avoid

1. Don't Mock Too Deep: Mock at service boundaries (database, HTTP), not internal methods
2. Test Behavior, Not Implementation: Focus on inputs/outputs, not internal state
3. Use Real Data Structures: Use actual n8n node/workflow structures from fixtures
4. Handle Async Properly: Many services have async methods, use async/await in tests

Coverage Goals

Priority	Service	Target Coverage	Key Focus Areas
1	config-validator	85%	displayOptions, node-specific validation
1	enhanced-config-validator	85%	operation modes, profiles
1	workflow-validator	90%	connections, expressions, error handling
2	n8n-api-client	85%	all endpoints, error scenarios
2	workflow-diff-engine	85%	all operations, validation
3	expression-validator	90%	syntax, context validation

Next Steps

1. Complete tests for Priority 1 services first
2. Create additional factories as needed
3. Track coverage with npm run test:coverage
4. Focus on edge cases and error scenarios
5. Ensure all async operations are properly tested

Resources

• Testing plan: /tests/PHASE3_TESTING_PLAN.md
• Service documentation: Check each service file's header comments
• n8n structures: Use actual examples from tests/fixtures/

Remember: The goal is reliable, maintainable tests that catch real bugs, not just high coverage numbers.