# Executions API Validation Testing Guide

**Story:** 2.2 - Validate & Test Executions API
**Status:** In Progress
**Test Suite:** `test-executions-validation.js`

## Overview

Comprehensive validation testing for all 3 Executions API methods implemented in the n8n Workflow Builder MCP Server:

- `list_executions` - List and filter execution history
- `get_execution` - Retrieve detailed execution information
- `delete_execution` - Remove execution records

## Prerequisites

### 1. Running n8n Instance

You need access to a live n8n instance (v1.82.3 or later) with:
- Valid API key
- Existing workflow executions (for comprehensive testing)

**Recommended:** Execute some workflows manually through the n8n web interface before running tests to ensure test data availability.

### 2. Environment Configuration

**Option A: Multi-instance configuration (`.config.json`)**

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

**Option B: Single instance configuration (`.env`)**

```env
N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key_here
```

**Important:** Both `.config.json` and `.env` are gitignored for security.

### 3. Built Project

```bash
npm run build
```

## Running the Tests

### Basic Test Execution

```bash
# 1. Build the project
npm run build

# 2. Start the MCP server in background
npm start &

# 3. Wait for server to start (2-3 seconds)
sleep 3

# 4. Run executions validation tests
node test-executions-validation.js
```

### Test Configuration

Edit `test-executions-validation.js` to customize test behavior:

```javascript
const config = {
  testFlags: {
    generateExecutions: true,  // Create test workflows (note: executions must be manual)
    runListTests: true,        // Test list_executions method
    runGetTests: true,         // Test get_execution method
    runDeleteTests: true,      // Test delete_execution method
    runCleanup: true           // Clean up test data after tests
  }
};
```

## Test Categories

### 1. list_executions Tests (6 tests)

Tests the execution listing and filtering functionality:

- **List all executions** - Basic listing functionality
- **Response structure** - Validate required fields (id, finished, mode, startedAt, workflowId)
- **Pagination limit** - Test limit parameter
- **Cursor pagination** - Test cursor-based pagination with nextCursor
- **Filter by workflowId** - Test workflow-specific filtering
- **includeData parameter** - Test data inclusion/exclusion

**Expected Fields in Response:**
```json
{
  "data": [
    {
      "id": "string",
      "finished": boolean,
      "mode": "string",
      "startedAt": "ISO 8601 date",
      "stoppedAt": "ISO 8601 date or null",
      "workflowId": "string"
    }
  ],
  "nextCursor": "string or null"
}
```

### 2. get_execution Tests (4 tests)

Tests individual execution retrieval:

- **Retrieve by ID** - Get specific execution
- **Structure validation** - Verify all required fields present
- **Data completeness** - Test includeData parameter
- **404 handling** - Non-existent execution IDs

**Expected Response:**
```json
{
  "id": "string",
  "finished": boolean,
  "mode": "string",
  "startedAt": "ISO 8601 date",
  "stoppedAt": "ISO 8601 date",
  "workflowId": "string",
  "data": { ... }  // When includeData=true
}
```

### 3. delete_execution Tests (2 tests)

Tests execution deletion:

- **Delete and verify** - Delete execution and confirm removal
- **404 handling** - Non-existent execution IDs

### 4. Error Handling Validation

Integrated across all test categories:
- 404 errors for non-existent resources
- Error response format validation
- Invalid parameter handling

## Understanding Test Results

### Success Output Example

```
======================================================================
  Executions API Validation Test Suite - Story 2.2
======================================================================

[INFO] Testing 3 Executions API methods against live n8n instance

--- Pre-flight Checks ---
[INFO] Server health: ok
[INFO] Found 25 existing executions

--- Task 2: Validate list_executions ---
[TEST] list_executions - List all executions: ✓ PASS - Found 25 executions
[TEST] list_executions - Response structure validation: ✓ PASS
[TEST] list_executions - Pagination limit: ✓ PASS - Returned 3 executions (limit: 3)
[TEST] list_executions - Cursor pagination: ✓ PASS - Next page retrieved
[TEST] list_executions - Filter by workflowId: ✓ PASS
[TEST] list_executions - includeData parameter: ✓ PASS

--- Task 3: Validate get_execution ---
[TEST] get_execution - Retrieve by ID: ✓ PASS
[TEST] get_execution - Structure validation: ✓ PASS
[TEST] get_execution - Data completeness: ✓ PASS
[TEST] get_execution - 404 for non-existent ID: ✓ PASS

--- Task 4: Validate delete_execution ---
[TEST] delete_execution - Delete and verify: ✓ PASS
[TEST] delete_execution - 404 for non-existent ID: ✓ PASS

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

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

### Result Categories

- **✓ PASS** - Test passed successfully
- **✗ FAIL** - Test failed (see details)
- **⚠ WARN** - Warning or validation finding (not a failure)

## Important Notes

### Execution Generation Limitations

**Critical:** Manual trigger workflows cannot be executed via REST API (n8n v1.82.3 limitation).

The test suite will:
1. Create test workflows
2. Use existing executions in your n8n instance for testing
3. Recommend executing workflows manually if no executions exist

**Recommendation:** Before running tests, execute some workflows manually through the n8n web interface to ensure adequate test data.

### Cursor-Based Pagination

Unlike offset-based pagination, cursor-based pagination:
- Uses opaque cursor strings (not numeric offsets)
- Cursors obtained from `nextCursor` in previous response
- More efficient for large datasets
- Cursors may expire over time

### Data Size Considerations

When `includeData=true`:
- Response payloads can be very large (>1MB for complex workflows)
- Use judiciously in production
- Default behavior (`includeData=false`) returns minimal metadata only

## Troubleshooting

### Issue: "No executions found"

**Symptom:**
```
[WARN] No executions found. Some tests may be limited.
[WARN] Please execute some workflows manually through n8n interface for complete testing.
```

**Solution:**
1. Open your n8n web interface
2. Execute some workflows manually
3. Wait a few seconds for executions to complete
4. Re-run the validation tests

### Issue: "Connection refused"

**Symptom:**
```
[ERROR] MCP request failed: tools/call
Error: connect ECONNREFUSED 127.0.0.1:3456
```

**Solution:**
1. Ensure MCP server is running: `npm start`
2. Check if port 3456 is available
3. Set `MCP_PORT` environment variable if needed

### Issue: "401 Unauthorized"

**Symptom:**
```
[ERROR] API error: 401 Unauthorized
```

**Solution:**
1. Verify API key in `.config.json` or `.env`
2. Ensure API key has proper permissions
3. Check n8n instance URL is correct

### Issue: Cursor pagination not working

**Symptom:**
```
[TEST] list_executions - Cursor pagination: ✗ FAIL
```

**Possible Causes:**
1. Not enough executions to paginate (need >limit executions)
2. Cursor may have expired (run tests faster)
3. n8n version may not support cursor pagination

**Solution:**
- Create more workflow executions
- Run tests immediately after execution generation
- Check n8n API documentation for your version

## Test Data Cleanup

By default, tests clean up after themselves:

```javascript
testFlags: {
  runCleanup: true  // Automatically delete test workflows
}
```

**What gets cleaned up:**
- Test workflows created during test execution

**What doesn't get cleaned up:**
- Executions (some may be deleted during delete tests)
- Existing workflows and executions

**To preserve test data:**
```javascript
testFlags: {
  runCleanup: false  // Keep test workflows
}
```

## Integration with CI/CD

### GitHub Actions Example

```yaml
name: Executions API Validation

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  validate-executions-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Create config
        run: |
          echo '{
            "environments": {
              "production": {
                "n8n_host": "${{ secrets.N8N_HOST }}",
                "n8n_api_key": "${{ secrets.N8N_API_KEY }}"
              }
            },
            "defaultEnv": "production"
          }' > .config.json

      - name: Start MCP server
        run: npm start &

      - name: Wait for server
        run: sleep 5

      - name: Run executions validation tests
        run: node test-executions-validation.js
```

## Advanced Usage

### Debug Mode

Enable detailed logging:

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

Shows:
- MCP request/response details
- Internal test state
- Detailed error information

### Custom Port

```bash
MCP_PORT=8080 npm start &
```

Then update test configuration:
```javascript
const config = {
  mcpServerUrl: 'http://localhost:8080/mcp',
  healthCheckUrl: 'http://localhost:8080/health'
};
```

### Testing Specific Categories

Disable test categories:

```javascript
testFlags: {
  runListTests: true,   // Only run list tests
  runGetTests: false,   // Skip get tests
  runDeleteTests: false // Skip delete tests
}
```

## Expected Test Coverage

Based on Story 2.2 acceptance criteria:

- ✅ **AC 1:** All 3 Executions API methods validated
- ✅ **AC 2:** Automated test suite created
- ✅ **AC 3:** Request/response formats verified
- ✅ **AC 4:** Multi-instance routing tested
- ✅ **AC 5:** Filtering and pagination validated
- ✅ **AC 6:** Execution data structure verified
- ✅ **AC 7:** Error handling validated
- ✅ **AC 8:** Validation report created
- ✅ **AC 9:** Integration with test infrastructure
- ✅ **AC 10:** Edge cases tested

## Documentation References

- **API Documentation:** `docs/n8n-api-docs/20-EXECUTIONS-API.md`
- **Pagination Guide:** `docs/n8n-api-docs/03-PAGINATION.md`
- **Implementation:** `src/services/n8nApiWrapper.ts`
- **MCP Tool Definitions:** `src/index.ts` (lines 479-541)

## Support

For issues or questions:
- Check `docs/bugs/` directory for known issues
- Review Story 2.2 in `docs/stories/2.2.validate-executions-api.md`
- Consult `CLAUDE.md` for implementation details