# Workflows API Validation Testing Guide

**Story 2.1: Validate & Test Workflows API**

This guide explains how to run comprehensive validation tests for all 8 Workflows API methods against a live n8n instance.

## Prerequisites

### 1. Live n8n Instance

You need access to a running n8n instance (v1.82.3 or later) with:
- API access enabled
- Valid API key with workflow management permissions
- Network accessibility from your test environment

### 2. Project Setup

```bash
# Install dependencies
npm install

# Build the project
npm run build
```

### 3. Configuration

#### Option A: Using .config.json (Multi-Instance)

Create or update `.config.json` in the project root:

```json
{
  "environments": {
    "production": {
      "n8n_host": "https://your-n8n-instance.com",
      "n8n_api_key": "your_api_key_here"
    },
    "staging": {
      "n8n_host": "https://staging-n8n.com",
      "n8n_api_key": "staging_api_key"
    }
  },
  "defaultEnv": "production"
}
```

#### Option B: Using .env (Single Instance)

Create `.env` file in project root:

```bash
N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key_here
MCP_PORT=3456
```

**Important**: Provide the base URL without `/api/v1`. The server automatically appends `/api/v1`.

## Running Validation Tests

### 1. Start MCP Server

In one terminal:

```bash
npm start
```

The server should start on `http://localhost:3456` (or your configured `MCP_PORT`).

Verify health:
```bash
curl http://localhost:3456/health
```

Expected response:
```json
{"status":"ok"}
```

### 2. Run Validation Tests

In another terminal:

```bash
node test-workflows-validation.js
```

### 3. Test Execution Options

Edit `test-workflows-validation.js` to control which tests run:

```javascript
const testFlags = {
  runListWorkflowsTests: true,      // GET /workflows
  runGetWorkflowTests: true,         // GET /workflows/{id}
  runCreateWorkflowTests: true,      // POST /workflows
  runUpdateWorkflowTests: true,      // PUT /workflows/{id}
  runDeleteWorkflowTests: true,      // DELETE /workflows/{id}
  runActivateWorkflowTests: true,    // PUT /workflows/{id}/activate
  runDeactivateWorkflowTests: true,  // PUT /workflows/{id}/deactivate
  runExecuteWorkflowTests: true,     // Execute workflow
  runMultiInstanceTests: false,      // Requires multi-instance config
  runErrorHandlingTests: true,       // Error scenarios
  runCleanup: true                   // Delete test workflows after
};
```

### 4. Debug Mode

Enable detailed logging:

```bash
DEBUG=true node test-workflows-validation.js
```

## Test Coverage

The validation suite includes **54+ comprehensive tests**:

### Task 2: list_workflows (7 tests)
- ✓ List all workflows without filters
- ✓ Response structure validation
- ✓ Filter by active=true
- ✓ Filter by active=false
- ✓ Pagination with limit parameter
- ✓ Multi-instance routing
- ✓ Error handling (401, malformed params)

### Task 3: get_workflow (5 tests)
- ✓ Retrieve existing workflow by ID
- ✓ Complete structure validation
- ✓ Nodes and connections validation
- ✓ Multi-instance retrieval
- ✓ 404 error for non-existent ID

### Task 4: create_workflow (6 tests)
- ✓ Create minimal workflow (name only)
- ✓ Create complete workflow with nodes
- ✓ Create complex workflow (10+ nodes)
- ✓ Verify nodes and connections preserved
- ✓ Multi-instance creation
- ✓ Error handling (400 for invalid data)

### Task 5: update_workflow (6 tests)
- ✓ Update workflow name
- ✓ Update workflow structure
- ✓ Verify changes persisted
- ✓ Multi-instance update
- ✓ 404 error for non-existent workflow
- ✓ Error handling validation

### Task 6: delete_workflow (5 tests)
- ✓ Delete existing workflow
- ✓ Verify deletion (workflow not retrievable)
- ✓ Multi-instance deletion
- ✓ 404 error for non-existent workflow
- ✓ Idempotency check

### Task 7: activate_workflow (6 tests)
- ✓ Activate inactive workflow
- ✓ Verify active status changes
- ✓ Persistence validation
- ✓ Idempotency (activate already active)
- ✓ Multi-instance activation
- ✓ 404 error handling

### Task 8: deactivate_workflow (5 tests)
- ✓ Deactivate active workflow
- ✓ Verify inactive status
- ✓ Idempotency check
- ✓ Multi-instance deactivation
- ✓ Error handling

### Task 9: execute_workflow (5 tests)
- ✓ Known limitation: Manual trigger workflows
- ✓ Error handling for non-existent workflow
- ✓ Documentation vs implementation comparison

### Task 10: Multi-Instance (3 tests)
- ✓ List workflows from default instance
- ✓ List workflows from specific instance
- ✓ Instance isolation validation

### Task 11: Error Handling (6 tests)
- ✓ 401 Unauthorized (invalid API key)
- ✓ 404 Not Found (non-existent resources)
- ✓ 400 Bad Request (malformed data)
- ✓ Error response format consistency
- ✓ Multi-instance error handling
- ✓ Error message clarity

## Test Output

### Successful Test Run

```
======================================================================
  Workflows API Validation Test Suite - Story 2.1
======================================================================

[INFO] Testing 8 Workflows API methods against live n8n instance
[INFO] MCP Server: http://localhost:3456/mcp

--- Pre-flight Checks ---

[INFO] Server health: ok

--- Task 2: Validate list_workflows ---

[TEST] list_workflows - List all workflows: ✓ PASS - Found 15 workflows
[TEST] list_workflows - Response structure validation: ✓ PASS - All required fields present
[TEST] list_workflows - Filter active=true: ✓ PASS - 8 active workflows
...

======================================================================
  Test Summary Report
======================================================================
Total tests executed: 54
Passed: 54 (100%)
Failed: 0
Skipped: 0

✓ ALL TESTS PASSED!
======================================================================
```

### Failed Test Example

```
[TEST] create_workflow - Complete workflow: ✗ FAIL - Node/connection mismatch

======================================================================
  Test Summary Report
======================================================================
Total tests executed: 54
Passed: 53 (98%)
Failed: 1

❌ Failed tests:
   - create_workflow - Complete workflow

⚠️  1 test(s) need attention
======================================================================
```

## Validation Findings

The test suite automatically tracks discrepancies between documentation and implementation:

```
⚠️  Validation Findings: 1
   1. [execute_workflow] Manual trigger workflows cannot be executed via REST API - n8n v1.82.3 limitation
```

These findings are logged to help identify:
- Documentation inaccuracies
- Missing functionality
- API behavior differences
- Implementation gaps

## Test Data Cleanup

Tests automatically clean up created workflows unless `runCleanup: false`.

All test workflows are prefixed with `ValidationTest_` for easy identification.

Manual cleanup:
```bash
# List test workflows in n8n UI and delete manually
# Or use list_workflows tool to find and delete by name prefix
```

## Multi-Instance Testing

To test multi-instance routing:

1. Configure multiple environments in `.config.json`
2. Set `runMultiInstanceTests: true` in test flags
3. Run tests

The suite will validate:
- Workflow isolation between instances
- Correct routing to specified instance
- Default instance fallback
- Invalid instance error handling

## Troubleshooting

### Server Not Starting

```bash
# Check if port is in use
lsof -i :3456

# Use different port
MCP_PORT=3457 npm start
```

Update test config:
```javascript
const config = {
  mcpServerUrl: 'http://localhost:3457/mcp',
  healthCheckUrl: 'http://localhost:3457/health',
  ...
};
```

### Connection Errors

Verify n8n instance accessibility:
```bash
curl -H "X-N8N-API-KEY: your_api_key" https://your-n8n-instance.com/api/v1/workflows
```

### API Key Permissions

Ensure your API key has permissions for:
- List workflows
- Create workflows
- Update workflows
- Delete workflows
- Activate/deactivate workflows

### Test Failures

1. **Enable debug mode**: `DEBUG=true node test-workflows-validation.js`
2. **Disable cleanup**: Set `runCleanup: false` to inspect created workflows
3. **Run individual test suites**: Set specific flags to `false` to isolate issues
4. **Check n8n version**: Tests validated against n8n v1.82.3+

## Integration with Test Infrastructure

### Existing Test Suite

The validation tests complement existing tests:

```bash
# Run all tests
npm test                          # Jest unit tests
node test-mcp-tools.js            # MCP tool integration tests
node test-comprehensive.js        # Comprehensive integration tests
node test-workflows-validation.js # Workflows API validation (Story 2.1)
```

### CI/CD Integration

Add to your CI pipeline:

```yaml
# .github/workflows/test.yml
- name: Build project
  run: npm run build

- name: Start MCP server
  run: npm start &

- name: Wait for server
  run: sleep 5

- name: Run validation tests
  run: node test-workflows-validation.js
  env:
    N8N_HOST: ${{ secrets.N8N_HOST }}
    N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
```

## Expected Results

After running validation tests, you should have:

1. **Test Results**: Pass/fail status for all 54 tests
2. **Validation Report**: Any discrepancies between docs and implementation
3. **Coverage Metrics**: Percentage of successful tests per API method
4. **Findings List**: Documentation updates needed

## Next Steps

After completing validation:

1. **Document findings** in Story 2.1 Dev Agent Record
2. **Update validation report** (Task 12)
3. **Address any failures** found during testing
4. **Update documentation** based on validation findings
5. **Proceed to Story 2.2** (Executions API validation)

## Reference

- **Story**: `docs/stories/2.1.validate-workflows-api.md`
- **Epic**: `docs/epic-2-api-implementation-validation.md`
- **API Docs**: `docs/n8n-api-docs/10-WORKFLOWS-API.md`
- **Implementation**: `src/index.ts`, `src/services/n8nApiWrapper.ts`