n8n-mcp/tests/unit/MULTI_TENANT_TEST_COVERAGE.md

Multi-Tenant Support Test Coverage Summary

This document summarizes the comprehensive test suites created for the multi-tenant support implementation in n8n-mcp.

Test Files Created

1. tests/unit/mcp/multi-tenant-tool-listing.test.ts

Focus: MCP Server ListToolsRequestSchema handler multi-tenant logic

Coverage Areas:

• Environment variable configuration (backward compatibility)
• Instance context configuration (multi-tenant support)
• ENABLE_MULTI_TENANT flag support
• shouldIncludeManagementTools logic truth table
• Tool availability logic with different configurations
• Combined configuration scenarios
• Edge cases and security validation
• Tool count validation and structure consistency

Key Test Scenarios:

• ✅ Environment variables only (N8N_API_URL, N8N_API_KEY)
• ✅ Instance context only (runtime configuration)
• ✅ Multi-tenant flag only (ENABLE_MULTI_TENANT=true)
• ✅ No configuration (documentation tools only)
• ✅ All combinations of the above
• ✅ Malformed instance context handling
• ✅ Security logging verification

2. tests/unit/types/instance-context-multi-tenant.test.ts

Focus: Enhanced URL validation in instance-context.ts

Coverage Areas:

• IPv4 address validation (valid and invalid ranges)
• IPv6 address validation (various formats)
• Localhost and development URLs
• Port validation (1-65535 range)
• Domain name validation (subdomains, TLDs)
• Protocol validation (http/https only)
• Edge cases and malformed URLs
• Real-world n8n deployment patterns
• Security and XSS prevention
• URL encoding handling

Key Test Scenarios:

• ✅ Valid IPv4: private networks, public IPs, localhost
• ✅ Invalid IPv4: out-of-range octets, malformed addresses
• ✅ Valid IPv6: loopback, documentation prefix, full addresses
• ✅ Valid ports: 1-65535 range, common development ports
• ✅ Invalid ports: negative, above 65535, non-numeric
• ✅ Domain patterns: subdomains, enterprise domains, development URLs
• ✅ Security validation: XSS attempts, file protocols, injection attempts
• ✅ Real n8n URLs: cloud, tenant, self-hosted patterns

3. tests/unit/http-server/multi-tenant-support.test.ts

Focus: HTTP server multi-tenant functions and session management

Coverage Areas:

• Header extraction and type safety
• Instance context creation from headers
• Session ID generation with configuration hashing
• Context switching between tenants
• Security logging with sanitization
• Session management and cleanup
• Race condition prevention
• Memory management

Key Test Scenarios:

• ✅ Multi-tenant header extraction (x-n8n-url, x-n8n-key, etc.)
• ✅ Instance context validation from headers
• ✅ Session isolation between tenants
• ✅ Configuration-based session ID generation
• ✅ Header type safety (arrays, non-strings)
• ✅ Missing/corrupt session data handling
• ✅ Memory pressure and cleanup strategies

4. tests/unit/multi-tenant-integration.test.ts

Focus: End-to-end integration testing of multi-tenant features

Coverage Areas:

• Real-world URL patterns and validation
• Environment variable handling
• Header processing simulation
• Configuration priority logic
• Session management concepts
• Error scenarios and recovery
• Security validation across components

Key Test Scenarios:

• ✅ Complete n8n deployment URL patterns
• ✅ API key validation (valid/invalid patterns)
• ✅ Environment flag handling (ENABLE_MULTI_TENANT)
• ✅ Header processing edge cases
• ✅ Configuration priority matrix
• ✅ Session isolation concepts
• ✅ Comprehensive error handling
• ✅ Specific validation error messages

Test Coverage Metrics

Instance Context Validation

• Statements: 83.78% (93/111)
• Branches: 81.53% (53/65)
• Functions: 100% (4/4)
• Lines: 83.78% (93/111)

Test Quality Metrics

• Total Test Cases: 200+ individual test scenarios
• Error Scenarios Covered: 50+ edge cases and error conditions
• Security Tests: 15+ XSS, injection, and protocol abuse tests
• Integration Scenarios: 40+ end-to-end validation tests

Key Features Tested

Backward Compatibility

• ✅ Environment variable configuration (N8N_API_URL, N8N_API_KEY)
• ✅ Existing tool listing behavior preserved
• ✅ Graceful degradation when multi-tenant features are disabled

Multi-Tenant Support

• ✅ Runtime instance context configuration
• ✅ HTTP header-based tenant identification
• ✅ Session isolation between tenants
• ✅ Dynamic tool registration based on context

Security

• ✅ URL validation against XSS and injection attempts
• ✅ API key validation with placeholder detection
• ✅ Sensitive data sanitization in logs
• ✅ Protocol restriction (http/https only)

Error Handling

• ✅ Graceful handling of malformed configurations
• ✅ Specific error messages for debugging
• ✅ Non-throwing validation functions
• ✅ Recovery from invalid session data

Test Patterns Used

Arrange-Act-Assert

All tests follow the clear AAA pattern for maintainability and readability.

Comprehensive Mocking

• Logger mocking for isolation
• Environment variable mocking for clean state
• Dependency injection for testability

Data-Driven Testing

• Parameterized tests for URL patterns
• Truth table testing for configuration logic
• Matrix testing for scenario combinations

Edge Case Coverage

• Boundary value testing (ports, IP ranges)
• Invalid input testing (malformed URLs, empty strings)
• Security testing (XSS, injection attempts)

Running the Tests

# Run all multi-tenant tests
npm test tests/unit/mcp/multi-tenant-tool-listing.test.ts
npm test tests/unit/types/instance-context-multi-tenant.test.ts
npm test tests/unit/http-server/multi-tenant-support.test.ts
npm test tests/unit/multi-tenant-integration.test.ts

# Run with coverage
npm run test:coverage

# Run specific test patterns
npm test -- --grep "multi-tenant"

Test Maintenance Notes

Mock Updates

When updating the logger or other core utilities, ensure mocks are updated accordingly.

Environment Variables

Tests properly isolate environment variables to prevent cross-test pollution.

Real-World Patterns

URL validation tests are based on actual n8n deployment patterns and should be updated as new deployment methods are supported.

Security Tests

Security-focused tests should be regularly reviewed and updated as new attack vectors are discovered.

Future Test Enhancements

Performance Testing

• Session management under load
• Memory usage during high tenant count
• Configuration validation performance

End-to-End Testing

• Full HTTP request/response cycles
• Multi-tenant workflow execution
• Session persistence across requests

Integration Testing

• Database adapter integration with multi-tenant contexts
• MCP protocol compliance with dynamic tool sets
• Error propagation across component boundaries