# Testing Infrastructure Guide
Complete guide to testing the n8n MCP Workflow Builder, including test scripts, running tests, and writing new tests.
---
## Quick Start
Run comprehensive tests:
```bash
# Build the project
npm run build
# Start MCP server (separate terminal)
npm start
# Run all tests (new terminal)
node test-mcp-tools.js
```
---
## Table of Contents
1. [Test Scripts Overview](#test-scripts-overview)
2. [Running Tests](#running-tests)
3. [Test Configuration](#test-configuration)
4. [Interpreting Test Results](#interpreting-test-results)
5. [Writing New Tests](#writing-new-tests)
6. [Unit Testing with Jest](#unit-testing-with-jest)
7. [Integration Testing](#integration-testing)
8. [Best Practices](#best-practices)
---
## Test Scripts Overview
### Main Test Suite
**`test-mcp-tools.js`** - Comprehensive MCP tool testing
**Coverage:**
- ✅ Workflow CRUD operations (create, read, update, delete)
- ✅ Workflow activation/deactivation
- ✅ Tag management (create, list, update, delete)
- ✅ Execution management (list, get, delete, retry)
- ✅ Multi-instance routing
- ✅ Error handling validation
- ✅ Automatic cleanup
**Configuration flags:**
```javascript
const testFlags = {
runWorkflowTests: true, // Test workflow operations
runTagTests: true, // Test tag operations
runExecutionTests: true, // Test execution operations
runCleanup: true // Clean up test data (set false to keep)
};
```
### Specialized Test Scripts
**Credential Tests:**
- `test-credentials-all-methods-direct.js` - All credential operations
- `test-credentials-api-direct.js` - Direct API credential testing
- `test-credentials-create.js` - Credential creation validation
- `test-credentials-delete-and-schema.js` - Deletion and schema testing
- `test-credentials-informative-messages.js` - Error message validation
**Workflow Tests:**
- `test-activate-methods.js` - Workflow activation testing
- `test-patch-workflow.js` - Workflow update operations
- `test-workflows-validation.js` - Workflow validation
**Tag Tests:**
- `test-check-tags.js` - Tag existence validation
- `test-create-tag-simple.js` - Basic tag creation
- `test-different-tag-names.js` - Tag naming validation
- `test-tags-validation.js` - Comprehensive tag testing
**Execution Tests:**
- `test-executions-validation.js` - Execution operation validation
- `test-retry-quick.js` - Retry mechanism testing
**Integration Tests:**
- `test-comprehensive.js` - Full integration testing
- `test-e2e-all-tools.js` - End-to-end tool testing
### Unit Tests (Jest)
**Location:** `src/services/__tests__/`
**Coverage:**
- Service layer testing
- API wrapper validation
- Configuration loading
- Error handling
- Multi-instance logic
---
## Running Tests
### Prerequisites
1. **n8n instance running and accessible:**
```bash
# Check n8n is accessible
curl https://your-n8n-host/api/v1/workflows \
-H "X-N8N-API-KEY: your_api_key"
```
2. **Configuration file created:**
- `.config.json` for multi-instance testing
- `.env` for single-instance testing
3. **MCP server built:**
```bash
npm run build
```
4. **MCP server running:**
```bash
# Terminal 1: Start server
npm start
# Or with debug mode
DEBUG=true npm start
```
### Running Main Test Suite
```bash
# Terminal 2: Run tests
node test-mcp-tools.js
```
**Expected Output:**
```
🧪 MCP n8n Workflow Builder - Comprehensive Test Suite
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Test Configuration
├─ MCP Server URL: http://localhost:3456/mcp
├─ Health Check URL: http://localhost:3456/health
├─ Test Workflow Name: Test Workflow MCP
└─ Cleanup: Enabled
🏥 Health Check...
✅ MCP server is healthy
🔧 Testing Workflow Operations...
✅ Create workflow
✅ List workflows
✅ Get workflow details
✅ Update workflow
✅ Activate workflow
✅ Deactivate workflow
✅ Delete workflow
🏷️ Testing Tag Operations...
✅ Create tag
✅ List tags
✅ Get tag details
✅ Update tag
✅ Delete tag
🔄 Testing Execution Operations...
✅ List executions
✅ Get execution details
✅ Delete execution
🧹 Cleanup...
✅ Test data removed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ All tests passed successfully!
```
### Running Specific Test Categories
**Workflow tests only:**
```javascript
// Edit test-mcp-tools.js
const testFlags = {
runWorkflowTests: true,
runTagTests: false, // Disable
runExecutionTests: false, // Disable
runCleanup: true
};
```
**Keep test data for inspection:**
```javascript
const testFlags = {
runWorkflowTests: true,
runTagTests: true,
runExecutionTests: true,
runCleanup: false // Disable cleanup
};
```
### Running Credential Tests
```bash
# Test all credential operations
node test-credentials-all-methods-direct.js
# Test credential creation
node test-credentials-create.js
# Test schema validation
node test-credentials-delete-and-schema.js
```
### Running Unit Tests (Jest)
```bash
# Run all unit tests
npm test
# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
# Run specific test file
npm test -- src/services/__tests__/environmentManager.test.ts
```
---
## Test Configuration
### test-mcp-tools.js Configuration
**Location:** Top of `test-mcp-tools.js` file
```javascript
const config = {
// MCP server connection
mcpServerUrl: 'http://localhost:3456/mcp',
healthCheckUrl: 'http://localhost:3456/health',
// Test data
testWorkflowName: 'Test Workflow MCP',
testTagName: 'test-tag-' + Date.now(),
// Test flags
testFlags: {
runWorkflowTests: true,
runTagTests: true,
runExecutionTests: true,
runCleanup: true
},
// Timeout settings
requestTimeout: 30000, // 30 seconds
// Multi-instance testing (optional)
testInstance: 'staging' // Or undefined for default
};
```
### Environment Variables for Tests
```bash
# Set test instance
TEST_INSTANCE=staging node test-mcp-tools.js
# Enable debug output
DEBUG=true node test-mcp-tools.js
# Custom MCP server port
MCP_PORT=58921 npm start
# Then update mcpServerUrl in test config
```
### Multi-Instance Test Configuration
**Testing specific instance:**
```javascript
// In test script
const params = {
instance: 'staging', // Test staging environment
name: 'Test Workflow',
// ... other parameters
};
```
**Testing all instances:**
```javascript
const instances = ['production', 'staging', 'development'];
for (const instance of instances) {
console.log(`\nTesting instance: ${instance}`);
// Run tests for this instance
await testWorkflowOperations(instance);
await testTagOperations(instance);
await testExecutionOperations(instance);
}
```
---
## Interpreting Test Results
### Success Indicators
```
✅ Create workflow
✅ List workflows
✅ Get workflow details
```
**Meaning:**
- Operation completed successfully
- No errors encountered
- Data validated correctly
- Response format correct
### Failure Patterns
```
❌ Create workflow
Error: Request failed with status code 401
Authentication failed
```
**Analysis:**
- Operation failed
- HTTP status code provided (401 = auth error)
- Error message explains cause
- Stack trace available in debug mode
### Common Test Errors
**Authentication failures:**
```
❌ List workflows
Error: Request failed with status code 401
Unauthorized: Invalid API key
```
**Solution:** Check API key in configuration
**Connection refused:**
```
❌ Health check failed
Error: connect ECONNREFUSED 127.0.0.1:3456
```
**Solution:** Start MCP server (`npm start`)
**Validation errors:**
```
❌ Create workflow
Error: Workflow validation failed
Missing required trigger node
```
**Solution:** Add valid trigger node to workflow
### Performance Metrics
Tests include timing information:
```
✅ Create workflow (234ms)
✅ List workflows (45ms)
✅ Get workflow details (123ms)
```
**Performance thresholds:**
- `< 100ms` - Excellent (cached or simple operation)
- `100-500ms` - Good (typical API call)
- `500-2000ms` - Acceptable (complex operation)
- `> 2000ms` - Slow (investigate)
---
## Writing New Tests
### Test Structure
```javascript
// test-my-feature.js
const axios = require('axios');
const config = {
mcpServerUrl: 'http://localhost:3456/mcp',
healthCheckUrl: 'http://localhost:3456/health'
};
async function runTests() {
console.log('🧪 Testing My Feature');
try {
// 1. Health check
await healthCheck();
// 2. Test operations
await testOperation1();
await testOperation2();
// 3. Cleanup
await cleanup();
console.log('✅ All tests passed!');
} catch (error) {
console.error('❌ Test failed:', error.message);
process.exit(1);
}
}
async function healthCheck() {
const response = await axios.get(config.healthCheckUrl);
if (response.data.status !== 'ok') {
throw new Error('Server not healthy');
}
console.log('✅ Health check passed');
}
async function testOperation1() {
const response = await axios.post(config.mcpServerUrl, {
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: {
name: 'my_tool',
arguments: {
// ... tool parameters
}
}
});
// Validate response
if (response.data.error) {
throw new Error(response.data.error.message);
}
const result = JSON.parse(response.data.result.content[0].text);
// Assertions
if (!result.id) {
throw new Error('Missing result ID');
}
console.log('✅ Operation 1 passed');
}
async function cleanup() {
// Delete test data
console.log('🧹 Cleaning up...');
}
// Run tests
runTests();
```
### Using Test Utilities
```javascript
// Common test helper functions
async function callTool(toolName, args) {
const response = await axios.post(config.mcpServerUrl, {
jsonrpc: '2.0',
id: Date.now(),
method: 'tools/call',
params: {
name: toolName,
arguments: args
}
});
if (response.data.error) {
throw new Error(response.data.error.message);
}
return JSON.parse(response.data.result.content[0].text);
}
function assert(condition, message) {
if (!condition) {
throw new Error(`Assertion failed: ${message}`);
}
}
function assertEqual(actual, expected, message) {
if (actual !== expected) {
throw new Error(
`${message}\nExpected: ${expected}\nActual: ${actual}`
);
}
}
```
### Test Cleanup Procedures
```javascript
async function cleanup() {
const createdResources = [];
try {
// Track created resources
const workflow = await createWorkflow();
createdResources.push({ type: 'workflow', id: workflow.id });
const tag = await createTag();
createdResources.push({ type: 'tag', id: tag.id });
// Run tests...
} finally {
// Always cleanup, even if tests fail
console.log('🧹 Cleaning up test data...');
for (const resource of createdResources.reverse()) {
try {
if (resource.type === 'workflow') {
await deleteWorkflow(resource.id);
} else if (resource.type === 'tag') {
await deleteTag(resource.id);
}
} catch (error) {
console.warn(`Failed to cleanup ${resource.type} ${resource.id}`);
}
}
}
}
```
---
## Unit Testing with Jest
### Test File Structure
```typescript
// src/services/__tests__/n8nApiWrapper.test.ts
import { N8NApiWrapper } from '../n8nApiWrapper';
import { EnvironmentManager } from '../environmentManager';
describe('N8NApiWrapper', () => {
let apiWrapper: N8NApiWrapper;
beforeEach(() => {
// Setup
apiWrapper = new N8NApiWrapper();
});
afterEach(() => {
// Cleanup
jest.clearAllMocks();
});
describe('listWorkflows', () => {
it('should list workflows successfully', async () => {
// Test implementation
const result = await apiWrapper.listWorkflows({
instance: 'test',
limit: 10
});
expect(result).toHaveProperty('data');
expect(Array.isArray(result.data)).toBe(true);
});
it('should handle errors gracefully', async () => {
// Error handling test
await expect(
apiWrapper.listWorkflows({ instance: 'invalid' })
).rejects.toThrow('Instance not found');
});
});
});
```
### Running Specific Tests
```bash
# Run tests matching pattern
npm test -- --testNamePattern="listWorkflows"
# Run specific file
npm test -- n8nApiWrapper.test.ts
# Run with coverage
npm run test:coverage
# Update snapshots
npm test -- --updateSnapshot
```
### Test Coverage Requirements
**Minimum coverage thresholds:**
- Statements: 80%
- Branches: 75%
- Functions: 80%
- Lines: 80%
**Check coverage:**
```bash
npm run test:coverage
# View HTML report
open coverage/lcov-report/index.html
```
---
## Integration Testing
### End-to-End Test Flow
```javascript
// test-e2e-workflow-lifecycle.js
async function testWorkflowLifecycle() {
console.log('🔄 Testing complete workflow lifecycle...');
let workflowId;
let executionId;
try {
// 1. Create workflow
console.log('1️⃣ Creating workflow...');
const workflow = await createWorkflow({
name: 'E2E Test Workflow',
nodes: [...],
connections: [...]
});
workflowId = workflow.id;
console.log(`✅ Created workflow ${workflowId}`);
// 2. Add tags
console.log('2️⃣ Adding tags...');
const tag = await createTag('e2e-test');
await updateWorkflow(workflowId, {
tags: [tag.id]
});
console.log('✅ Tags added');
// 3. Activate workflow
console.log('3️⃣ Activating workflow...');
await activateWorkflow(workflowId);
console.log('✅ Workflow activated');
// 4. Execute workflow (if webhook)
console.log('4️⃣ Executing workflow...');
const execution = await executeWorkflow(workflowId);
executionId = execution.id;
console.log(`✅ Execution started: ${executionId}`);
// 5. Monitor execution
console.log('5️⃣ Monitoring execution...');
await waitForExecution(executionId);
console.log('✅ Execution completed');
// 6. Verify results
console.log('6️⃣ Verifying results...');
const executionDetails = await getExecution(executionId);
if (executionDetails.finished) {
console.log('✅ Workflow executed successfully');
}
} finally {
// Cleanup
if (workflowId) await deleteWorkflow(workflowId);
if (executionId) await deleteExecution(executionId);
}
}
```
### Multi-Instance Integration Tests
```javascript
async function testMultiInstanceIntegration() {
const instances = ['production', 'staging', 'development'];
for (const instance of instances) {
console.log(`\n📍 Testing instance: ${instance}`);
// Test instance-specific operations
await testInstanceWorkflows(instance);
await testInstanceTags(instance);
await testInstanceExecutions(instance);
console.log(`✅ Instance ${instance} tests passed`);
}
}
```
---
## Best Practices
### Test Isolation
```javascript
// ✅ Good - Tests are independent
test('create workflow', async () => {
const workflow = await createWorkflow({
name: 'Test-' + Date.now() // Unique name
});
await deleteWorkflow(workflow.id); // Cleanup
});
// ❌ Bad - Tests depend on each other
let sharedWorkflowId;
test('create workflow', async () => {
const workflow = await createWorkflow();
sharedWorkflowId = workflow.id; // Shared state
});
test('update workflow', async () => {
await updateWorkflow(sharedWorkflowId); // Depends on previous test
});
```
### Cleanup After Tests
```javascript
// ✅ Good - Always cleanup
async function testWithCleanup() {
let workflowId;
try {
workflowId = await createWorkflow();
// Run tests...
} finally {
if (workflowId) {
await deleteWorkflow(workflowId);
}
}
}
```
### Meaningful Test Names
```javascript
// ✅ Good - Descriptive names
test('should create workflow with valid trigger node', async () => {});
test('should reject workflow without trigger node', async () => {});
test('should handle API authentication errors gracefully', async () => {});
// ❌ Bad - Unclear names
test('test1', async () => {});
test('workflow', async () => {});
test('it works', async () => {});
```
### Comprehensive Assertions
```javascript
// ✅ Good - Thorough validation
const workflow = await createWorkflow();
expect(workflow).toHaveProperty('id');
expect(workflow).toHaveProperty('name');
expect(workflow).toHaveProperty('active');
expect(workflow.active).toBe(false);
expect(workflow.nodes).toBeInstanceOf(Array);
expect(workflow.nodes.length).toBeGreaterThan(0);
// ❌ Bad - Minimal validation
const workflow = await createWorkflow();
expect(workflow).toBeDefined();
```
### Edge Case Coverage
```javascript
// Test various scenarios
describe('workflow creation', () => {
it('should create minimal workflow', async () => {});
it('should create complex workflow with many nodes', async () => {});
it('should handle empty connections', async () => {});
it('should reject invalid node types', async () => {});
it('should handle special characters in names', async () => {});
});
```
---
## Next Steps
- **[Error Reference](error-reference.md)** - Debug test failures
- **[Debug Mode](debug-mode.md)** - Enable detailed logging
- **[Contributing](../about/contributing.md)** - Contribute tests
- **[FAQ](faq.md)** - Testing questions
---
**Document Version:** 1.0
**Last Updated:** December 2025
**Related:** [Debug Mode](debug-mode.md), [Error Reference](error-reference.md), [Contributing](../about/contributing.md)
