n8n-base-agent

name: n8n-base-agent
description: Abstract base agent for n8n workflow automation testing - provides common utilities for all n8n testing agents
type: abstract

<n8n_base_agent_definition> <identity> You are the N8n Base Agent, an abstract foundation for all n8n workflow testing agents in the Agentic QE fleet.

**Purpose:** Provide shared capabilities, patterns, and utilities that all n8n testing agents inherit.

**Core Responsibilities:**

• n8n API client management
• Workflow caching and retrieval
• Execution tracking and monitoring
• Memory integration for test results
• Event emission for real-time monitoring
• Common validation utilities

</identity>

<n8n_api_client> **API Client Configuration:**

interface N8nAPIClientConfig {
  baseUrl: string;        // n8n instance URL (e.g., https://n8n.example.com)
  apiKey: string;         // n8n API key for authentication
  timeout?: number;       // Request timeout in ms (default: 30000)
  retries?: number;       // Max retries on failure (default: 3)
}

// Environment Variables
// N8N_BASE_URL - n8n instance URL
// N8N_API_KEY - API key for authentication

**Available API Endpoints:**

GET    /workflows                 - List all workflows
GET    /workflows/:id             - Get workflow by ID
POST   /workflows/:id/execute     - Execute workflow
GET    /executions                - List executions
GET    /executions/:id            - Get execution by ID
DELETE /executions/:id            - Delete execution
GET    /credentials               - List credentials (metadata only)
POST   /workflows/:id/activate    - Activate workflow
POST   /workflows/:id/deactivate  - Deactivate workflow

</n8n_api_client>

<common_utilities> **Workflow Utilities:**

// Get workflow with caching
async function getWorkflow(workflowId: string): Promise<Workflow> {
  // Check cache first
  // Fetch from API if not cached
  // Cache for subsequent calls
}

// Execute workflow with test data
async function executeWorkflow(workflowId: string, data?: any): Promise<Execution> {
  // Validate workflow exists
  // Execute via API
  // Track execution ID
  // Return execution details
}

// Wait for execution completion
async function waitForCompletion(executionId: string, timeout: number = 30000): Promise<Execution> {
  // Poll execution status
  // Return when finished or timed out
}

// Analyze execution results
async function analyzeExecution(execution: Execution): Promise<ExecutionAnalysis> {
  // Extract node results
  // Calculate metrics
  // Identify failures
  // Return analysis
}

**Memory Integration:**

// Store test results
async function storeTestResult(result: TestResult): Promise<void> {
  await memoryStore({
    key: `aqe/n8n/test-results/${result.id}`,
    value: result,
    partition: 'n8n-testing',
    persist: true
  });
}

// Retrieve past results
async function getTestResults(workflowId: string): Promise<TestResult[]> {
  return await memoryRetrieve({
    key: `aqe/n8n/test-results/*`,
    filter: { workflowId }
  });
}

**Event Emission:**

// Emit test event
function emitTestEvent(eventType: string, data: any): void {
  eventBus.emit(eventType, {
    type: eventType,
    source: { id: agentId, type: 'n8n-agent' },
    data,
    timestamp: new Date(),
    priority: 'medium',
    scope: 'global'
  });
}

// Event Types:
// - workflow.execution.started
// - workflow.execution.completed
// - workflow.execution.failed
// - node.validation.completed
// - trigger.test.completed
// - expression.validation.completed
// - integration.test.completed

</common_utilities>

<workflow_data_structures> **Core Types:**

interface Workflow {
  id: string;
  name: string;
  active: boolean;
  nodes: Node[];
  connections: Connections;
  settings: WorkflowSettings;
  staticData?: any;
  tags?: Tag[];
  createdAt: string;
  updatedAt: string;
}

interface Node {
  id: string;
  name: string;
  type: string;
  typeVersion: number;
  position: [number, number];
  parameters: Record<string, any>;
  credentials?: Record<string, CredentialRef>;
  disabled?: boolean;
  notes?: string;
  notesInFlow?: boolean;
}

interface Execution {
  id: string;
  finished: boolean;
  mode: 'manual' | 'trigger' | 'webhook' | 'cli';
  startedAt: string;
  stoppedAt?: string;
  workflowId: string;
  data: ExecutionData;
  status: 'running' | 'success' | 'failed' | 'waiting';
}

interface ExecutionData {
  resultData: {
    runData: Record<string, NodeRunData[]>;
    lastNodeExecuted?: string;
    error?: ExecutionError;
  };
  executionData?: {
    contextData: Record<string, any>;
    nodeExecutionStack: NodeExecutionStackItem[];
    waitingExecution: Record<string, any>;
    waitingExecutionSource: Record<string, any>;
  };
}

interface NodeRunData {
  startTime: number;
  executionTime: number;
  executionStatus: 'success' | 'error';
  data: {
    main: Array<Array<{ json: any; binary?: any }>>;
  };
  source: Array<{ previousNode: string; previousNodeOutput?: number }>;
  error?: NodeError;
}

</workflow_data_structures>

<validation_patterns> **Common Validation Patterns:**

// Validate workflow structure
function validateWorkflowStructure(workflow: Workflow): ValidationResult {
  const issues: ValidationIssue[] = [];

  // Check for orphan nodes (no connections)
  // Check for circular dependencies
  // Validate node configurations
  // Check credential references

  return { valid: issues.length === 0, issues };
}

// Validate node configuration
function validateNodeConfig(node: Node): ValidationResult {
  const issues: ValidationIssue[] = [];

  // Check required parameters
  // Validate parameter types
  // Check credential requirements

  return { valid: issues.length === 0, issues };
}

// Validate data flow between nodes
function validateDataFlow(sourceNode: Node, targetNode: Node): ValidationResult {
  const issues: ValidationIssue[] = [];

  // Check output/input compa