@onlineapps/conn-orch-validator 2.0.0

package/src/WorkflowTestRunner.js

@@ -0,0 +1,396 @@
+'use strict';
+
+const EventEmitter = require('events');
+
+/**
+ * WorkflowTestRunner - Executes and tests cookbook workflows
+ */
+class WorkflowTestRunner extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.mqClient = options.mqClient;
+    this.registry = options.registry;
+    this.storage = options.storage;
+    this.timeout = options.timeout || 30000;
+    this.debug = options.debug || false;
+    this.runningWorkflows = new Map();
+  }
+
+  /**
+   * Run workflow test
+   */
+  async runWorkflow(cookbook, initialContext = {}) {
+    const workflowId = `test-workflow-${Date.now()}`;
+    
+    const workflow = {
+      id: workflowId,
+      cookbook,
+      context: {
+        api_input: initialContext,
+        steps: {}
+      },
+      status: 'running',
+      startedAt: Date.now(),
+      currentStep: 0,
+      results: [],
+      errors: []
+    };
+
+    this.runningWorkflows.set(workflowId, workflow);
+    this.emit('workflow:started', { workflowId, cookbook });
+
+    try {
+      // Execute steps sequentially
+      for (let i = 0; i < cookbook.steps.length; i++) {
+        const step = cookbook.steps[i];
+        workflow.currentStep = i;
+        
+        const stepResult = await this.executeStep(step, workflow);
+        workflow.results.push(stepResult);
+        
+        if (!stepResult.success) {
+          workflow.status = 'failed';
+          workflow.errors.push(stepResult.error);
+          this.emit('workflow:failed', { workflowId, error: stepResult.error });
+          break;
+        }
+        
+        // Update context with step result
+        workflow.context.steps[step.id] = stepResult.data;
+      }
+
+      if (workflow.status !== 'failed') {
+        workflow.status = 'completed';
+        workflow.completedAt = Date.now();
+        this.emit('workflow:completed', { workflowId, results: workflow.results });
+      }
+
+    } catch (error) {
+      workflow.status = 'error';
+      workflow.errors.push(error.message);
+      this.emit('workflow:error', { workflowId, error: error.message });
+    }
+
+    return workflow;
+  }
+
+  /**
+   * Execute individual step
+   */
+  async executeStep(step, workflow) {
+    const startTime = Date.now();
+    
+    this.emit('step:started', { 
+      workflowId: workflow.id, 
+      stepId: step.id, 
+      type: step.type 
+    });
+
+    const result = {
+      stepId: step.id,
+      type: step.type,
+      success: false,
+      data: null,
+      error: null,
+      duration: 0
+    };
+
+    try {
+      switch (step.type) {
+        case 'task':
+          result.data = await this.executeTaskStep(step, workflow);
+          break;
+        
+        case 'foreach':
+          result.data = await this.executeForeachStep(step, workflow);
+          break;
+        
+        case 'switch':
+          result.data = await this.executeSwitchStep(step, workflow);
+          break;
+        
+        case 'fork_join':
+          result.data = await this.executeForkJoinStep(step, workflow);
+          break;
+        
+        default:
+          throw new Error(`Unknown step type: ${step.type}`);
+      }
+      
+      result.success = true;
+      result.duration = Date.now() - startTime;
+      
+      this.emit('step:completed', { 
+        workflowId: workflow.id, 
+        stepId: step.id, 
+        result 
+      });
+
+    } catch (error) {
+      result.error = error.message;
+      result.duration = Date.now() - startTime;
+      
+      this.emit('step:failed', { 
+        workflowId: workflow.id, 
+        stepId: step.id, 
+        error: error.message 
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute task step
+   */
+  async executeTaskStep(step, workflow) {
+    const { service, operation, input } = step;
+    
+    // Resolve input using JSONPath
+    const resolvedInput = this.resolveInput(input, workflow.context);
+    
+    if (this.debug) {
+      console.log(`Executing task: ${service}.${operation}`, resolvedInput);
+    }
+
+    // Get service from registry
+    const serviceInfo = await this.registry.getService(service);
+    if (!serviceInfo) {
+      throw new Error(`Service not found: ${service}`);
+    }
+
+    // Simulate API call or send to queue
+    if (this.mqClient) {
+      // Send to service queue
+      const queueName = `service.${service}.request`;
+      await this.mqClient.publish(queueName, {
+        workflow_id: workflow.id,
+        step_id: step.id,
+        operation,
+        input: resolvedInput
+      });
+
+      // Wait for response (with timeout)
+      const response = await this.waitForResponse(
+        workflow.id, 
+        step.id, 
+        this.timeout
+      );
+      
+      return response;
+    } else {
+      // Simulate response
+      return {
+        processed: true,
+        operation,
+        input: resolvedInput,
+        output: { simulated: true }
+      };
+    }
+  }
+
+  /**
+   * Execute foreach step
+   */
+  async executeForeachStep(step, workflow) {
+    const { items, body } = step;
+    
+    // Resolve items array
+    const itemsArray = this.resolveInput(items, workflow.context);
+    if (!Array.isArray(itemsArray)) {
+      throw new Error('Foreach items must resolve to an array');
+    }
+
+    const results = [];
+    for (const item of itemsArray) {
+      // Create context with current item
+      const itemContext = {
+        ...workflow.context,
+        current_item: item
+      };
+      
+      // Execute body step for each item
+      const itemWorkflow = { ...workflow, context: itemContext };
+      const result = await this.executeStep(body, itemWorkflow);
+      results.push(result);
+    }
+
+    return { items: itemsArray.length, results };
+  }
+
+  /**
+   * Execute switch step
+   */
+  async executeSwitchStep(step, workflow) {
+    const { condition, cases, default: defaultCase } = step;
+    
+    // Resolve condition value
+    const conditionValue = this.resolveInput(condition, workflow.context);
+    
+    // Find matching case
+    const matchingCase = cases.find(c => c.value === conditionValue);
+    const stepToExecute = matchingCase ? matchingCase.step : defaultCase;
+    
+    if (!stepToExecute) {
+      throw new Error(`No matching case for condition value: ${conditionValue}`);
+    }
+
+    // Execute the selected step
+    const result = await this.executeStep(stepToExecute, workflow);
+    
+    return {
+      condition: conditionValue,
+      executed: stepToExecute.id,
+      result
+    };
+  }
+
+  /**
+   * Execute fork-join step
+   */
+  async executeForkJoinStep(step, workflow) {
+    const { branches, join } = step;
+    
+    // Execute all branches in parallel
+    const branchPromises = branches.map(branch => 
+      this.executeStep(branch, workflow)
+    );
+    
+    const results = await Promise.all(branchPromises);
+    
+    // Apply join strategy
+    let joinedResult;
+    switch (join.strategy) {
+      case 'merge':
+        joinedResult = this.mergeResults(results);
+        break;
+      case 'first':
+        joinedResult = results[0];
+        break;
+      case 'all':
+        joinedResult = results;
+        break;
+      default:
+        joinedResult = results;
+    }
+    
+    return {
+      branches: branches.length,
+      strategy: join.strategy,
+      result: joinedResult
+    };
+  }
+
+  /**
+   * Resolve input using JSONPath or direct value
+   */
+  resolveInput(input, context) {
+    if (!input) return null;
+    
+    if (typeof input === 'string' && input.startsWith('$')) {
+      // JSONPath resolution
+      return this.resolveJsonPath(input, context);
+    }
+    
+    if (typeof input === 'object' && input !== null) {
+      // Recursively resolve object properties
+      const resolved = {};
+      for (const [key, value] of Object.entries(input)) {
+        resolved[key] = this.resolveInput(value, context);
+      }
+      return resolved;
+    }
+    
+    return input;
+  }
+
+  /**
+   * Simple JSONPath resolution
+   */
+  resolveJsonPath(path, context) {
+    // Remove leading $
+    const pathParts = path.substring(1).split('.');
+    
+    let current = context;
+    for (const part of pathParts) {
+      if (current === null || current === undefined) {
+        return null;
+      }
+      current = current[part];
+    }
+    
+    return current;
+  }
+
+  /**
+   * Wait for step response from queue
+   */
+  async waitForResponse(workflowId, stepId, timeout) {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Timeout waiting for response: ${stepId}`));
+      }, timeout);
+
+      // Listen for response on response queue
+      const responseQueue = `workflow.${workflowId}.response`;
+      
+      this.mqClient.consume(responseQueue, (msg) => {
+        const message = JSON.parse(msg.content.toString());
+        
+        if (message.step_id === stepId) {
+          clearTimeout(timeoutId);
+          this.mqClient.ack(msg);
+          resolve(message.result);
+        }
+      });
+    });
+  }
+
+  /**
+   * Merge results from parallel branches
+   */
+  mergeResults(results) {
+    const merged = {};
+    
+    results.forEach((result, index) => {
+      if (result.data && typeof result.data === 'object') {
+        Object.assign(merged, result.data);
+      } else {
+        merged[`branch_${index}`] = result.data;
+      }
+    });
+    
+    return merged;
+  }
+
+  /**
+   * Get workflow status
+   */
+  getWorkflowStatus(workflowId) {
+    return this.runningWorkflows.get(workflowId);
+  }
+
+  /**
+   * Stop workflow
+   */
+  stopWorkflow(workflowId) {
+    const workflow = this.runningWorkflows.get(workflowId);
+    if (workflow && workflow.status === 'running') {
+      workflow.status = 'stopped';
+      this.emit('workflow:stopped', { workflowId });
+    }
+  }
+
+  /**
+   * Clear completed workflows
+   */
+  clearCompleted() {
+    for (const [id, workflow] of this.runningWorkflows.entries()) {
+      if (workflow.status === 'completed' || workflow.status === 'failed') {
+        this.runningWorkflows.delete(id);
+      }
+    }
+  }
+}
+
+module.exports = WorkflowTestRunner;

package/src/helpers/README.md

@@ -0,0 +1,235 @@
+# Test Helpers - Generic Test Suite Creators
+
+This directory contains **generic test helpers** that create complete test suites for business services.
+
+## Philosophy
+
+Instead of **copying test code** between services, we provide **reusable test helpers** that:
+- ✅ Work for **ALL business services** without modification
+- ✅ Automatically validate service structure
+- ✅ Provide clear error messages when something is wrong
+- ✅ Follow SPOT (Single Point Of Truth) principles
+- ✅ Stay up-to-date with latest testing standards
+
+## Available Helpers
+
+### 1. createServiceReadinessTests
+
+**Purpose:** Integration test for service HTTP API readiness
+
+**File:** `createServiceReadinessTests.js`
+
+**What it does:**
+- Validates service structure (conn-config/, src/app.js, package.json)
+- Validates configuration files (config.json, operations.json)
+- Tests all operations endpoints
+- Validates health endpoint
+- Auto-generates cookbook tests (with mocks)
+- Tests registry compatibility (with mocks)
+- Scores 100/100 with all checks
+
+**Usage:**
+```javascript
+// services/my-service/tests/integration/service-readiness.test.js
+const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
+
+createServiceReadinessTests(__dirname);
+```
+
+**Options:**
+```javascript
+createServiceReadinessTests(__dirname, {
+  testPort: 5556,              // Test server port (default: 5556)
+  includeOptionalChecks: true, // Cookbook & registry checks (default: true)
+  timeout: 15000               // Test timeout in ms (default: 15000)
+});
+```
+
+**Score Breakdown:**
+- operations: 30 points (required)
+- endpoints: 30 points (required)
+- health: 20 points (required)
+- cookbook: 15 points (optional, with mocks)
+- registry: 5 points (optional, with mocks)
+- **Total: 100/100**
+
+---
+
+### 2. createPreValidationTests
+
+**Purpose:** Tier 1 pre-validation process tests
+
+**File:** `createPreValidationTests.js`
+
+**What it does:**
+- Validates pre-requisites (cookbooks/, operations.json, scripts)
+- Runs cookbook tests with mocked infrastructure
+- Validates ValidationProof generation
+- Tests proof structure and integrity
+- Verifies SHA256 hash correctness
+- Tests tamper detection
+- Validates dependencies tracking
+
+**Usage:**
+```javascript
+// services/my-service/tests/integration/pre-validation-process.test.js
+const { createPreValidationTests } = require('@onlineapps/conn-orch-validator');
+
+createPreValidationTests(__dirname);
+```
+
+**Options:**
+```javascript
+createPreValidationTests(__dirname, {
+  timeout: 60000  // Test timeout in ms (default: 60000)
+});
+```
+
+**Test Structure:**
+1. Pre-requisites Check
+   - cookbooks/ directory exists
+   - operations.json exists
+   - Pre-validation script configured
+2. Cookbook Test Execution
+   - Runs npm run test:cookbooks
+   - Verifies infrastructure mocking
+3. ValidationProof Generation
+   - Creates .validation-proof.json
+   - Validates proof structure
+   - Checks SHA256 hash
+4. Proof Integrity Verification
+   - ValidationProofCodec decode
+   - Hash matching
+   - Age verification
+   - Tamper detection
+5. Dependencies Tracking
+   - Proof includes @onlineapps/* versions
+
+---
+
+## How It Works
+
+### Automatic Structure Validation
+
+Both helpers use `ServiceStructureValidator` to validate service structure BEFORE running tests:
+
+```
+🔍 Validating service structure...
+
+═══════════════════════════════════════════════════════════════
+  SERVICE STRUCTURE VALIDATION
+═══════════════════════════════════════════════════════════════
+
+✅ ALL CHECKS PASSED
+
+   ✓ Found Configuration directory: conn-config
+   ✓ Found Source code directory: src
+   ✓ Found Tests directory: tests
+   ✓ Found valid config.json
+   ✓ Found valid operations.json
+   ✓ Found src/app.js
+   ✓ Found 3 cookbook test(s)
+
+═══════════════════════════════════════════════════════════════
+```
+
+If validation fails, clear error messages are shown:
+
+```
+❌ ERRORS (2):
+
+   ✗ Required directory missing: conn-config
+     Type: MISSING_DIRECTORY
+     File: conn-config
+     Fix: Create directory: mkdir -p conn-config
+
+   ✗ Service configuration missing: conn-config/config.json
+     Type: MISSING_CONFIG
+     File: conn-config/config.json
+     Fix: Create config.json with service metadata. See: /docs/standards/SERVICE_TEMPLATE.md
+
+⚠️  WARNINGS (1):
+
+   ⚠ Recommended npm script missing: test:cookbooks
+     Suggestion: Add to package.json scripts: "test:cookbooks": "..."
+```
+
+### Zero Configuration
+
+Helpers automatically detect and load:
+
+```javascript
+// Service root (2 levels up from tests/integration/)
+const serviceRoot = path.resolve(__dirname, '../..');
+
+// Standard file locations
+const config = require(path.join(serviceRoot, 'conn-config/config.json'));
+const operations = require(path.join(serviceRoot, 'conn-config/operations.json'));
+const app = require(path.join(serviceRoot, 'src/app.js'));
+
+// Extract metadata
+const serviceName = config.service.name;
+const serviceVersion = config.service.version;
+const healthEndpoint = config.wrapper?.health?.endpoint || '/health';
+```
+
+No service-specific code needed!
+
+---
+
+## Adding New Helpers
+
+When creating new generic test helpers:
+
+1. **Follow naming convention:** `create[Purpose]Tests.js`
+2. **Accept testsDir as first parameter:** `function create...(testsDir, options)`
+3. **Calculate service root:** `const serviceRoot = path.resolve(testsDir, '../..');`
+4. **Validate structure first:** Use `ServiceStructureValidator`
+5. **Load standard files:** config.json, operations.json, app.js
+6. **Provide clear output:** Log validation results, test progress
+7. **Export single function:** `module.exports = { create...Tests };`
+8. **Update index.js:** Add to exports
+9. **Document in README.md:** Add to "Available Helpers" section
+
+**Example skeleton:**
+```javascript
+const path = require('path');
+const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
+
+function createMyTests(testsDir, options = {}) {
+  const serviceRoot = path.resolve(testsDir, '../..');
+
+  // 1. Validate structure
+  const validator = new ServiceStructureValidator(serviceRoot);
+  const result = validator.validate();
+  console.log(ServiceStructureValidator.formatResult(result));
+
+  if (!result.valid) {
+    throw new Error('Structure validation failed');
+  }
+
+  // 2. Load config
+  const config = require(path.join(serviceRoot, 'conn-config/config.json'));
+
+  // 3. Create test suite
+  describe('My Test Suite @integration', () => {
+    // tests...
+  });
+}
+
+module.exports = { createMyTests };
+```
+
+---
+
+## Related Documentation
+
+- [/docs/standards/TESTING.md](/docs/standards/TESTING.md) - Testing standards
+- [/tests/TESTING.md](/tests/TESTING.md) - SPOT principles
+- [/shared/connector/conn-orch-validator/README.md](/shared/connector/conn-orch-validator/README.md) - Package documentation
+- [/shared/connector/conn-orch-validator/docs/DESIGN.md](/shared/connector/conn-orch-validator/docs/DESIGN.md) - Design principles
+
+---
+
+*Last updated: 2025-10-21*
+*Maintained by: OA Drive Core Team*