@onlineapps/conn-orch-validator 2.0.0

package/src/helpers/createPreValidationTests.js

@@ -0,0 +1,321 @@
+/**
+ * Create Pre-Validation (Tier 1) Process Tests
+ *
+ * Generic test suite that validates Tier 1 pre-validation process.
+ * Works for ALL business services - no service-specific code needed.
+ *
+ * @module helpers/createPreValidationTests
+ *
+ * Purpose:
+ * - Validates cookbook tests execution
+ * - Validates ValidationProof generation
+ * - Validates proof integrity
+ * - Tests with MOCKED infrastructure (offline)
+ *
+ * Part of Two-Tier Validation System (Tier 1: Pre-Validation)
+ * See: /docs/architecture/validator.md
+ *
+ * Usage:
+ *   const { createPreValidationTests } = require('@onlineapps/conn-orch-validator');
+ *   createPreValidationTests(__dirname);  // Pass tests/integration directory
+ *
+ * Related:
+ * - /docs/architecture/validator.md - Two-tier validation system
+ * - /docs/standards/TESTING.md - Testing standards
+ * - /tests/TESTING.md - SPOT principles
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { ValidationProofCodec } = require('@onlineapps/service-validator-core');
+const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
+
+/**
+ * Create pre-validation (Tier 1) test suite
+ *
+ * @param {string} testsDir - Path to tests/integration directory (use __dirname)
+ * @param {Object} [options] - Optional configuration
+ * @param {number} [options.timeout=60000] - Test timeout in ms
+ *
+ * @example
+ * // In services/my-service/tests/integration/pre-validation-process.test.js
+ * const { createPreValidationTests } = require('@onlineapps/conn-orch-validator');
+ *
+ * createPreValidationTests(__dirname);
+ */
+function createPreValidationTests(testsDir, options = {}) {
+  // Calculate service root (2 levels up from tests/integration/)
+  const serviceRoot = path.resolve(testsDir, '../..');
+
+  const {
+    timeout = 60000
+  } = options;
+
+  // Validate service structure FIRST
+  console.log('\n🔍 Validating service structure for pre-validation...\n');
+  const structureValidator = new ServiceStructureValidator(serviceRoot);
+  const structureResult = structureValidator.validate();
+
+  // Log validation result
+  console.log(ServiceStructureValidator.formatResult(structureResult));
+
+  // FAIL FAST if structure is invalid
+  if (!structureResult.valid) {
+    throw new Error(
+      `Service structure validation failed. Fix errors above before running pre-validation tests.`
+    );
+  }
+
+  // Load configuration
+  const configPath = path.join(serviceRoot, 'conn-config/config.json');
+  const operationsPath = path.join(serviceRoot, 'conn-config/operations.json');
+  const proofPath = path.join(serviceRoot, '.validation-proof.json');
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
+
+  const serviceName = config.service.name;
+
+  // Create test suite
+  describe(`${serviceName} Pre-Validation (Tier 1) Process @integration`, () => {
+    afterEach(() => {
+      // Cleanup validation proof after each test
+      if (fs.existsSync(proofPath)) {
+        fs.unlinkSync(proofPath);
+      }
+    });
+
+    describe('1. Pre-requisites Check', () => {
+      test('service has tests/cookbooks directory', () => {
+        const cookbooksDir = path.join(serviceRoot, 'tests/cookbooks');
+        expect(fs.existsSync(cookbooksDir)).toBe(true);
+
+        const cookbookFiles = fs.readdirSync(cookbooksDir).filter(f => f.endsWith('.json'));
+        expect(cookbookFiles.length).toBeGreaterThan(0);
+
+        console.log(`\n✓ Found ${cookbookFiles.length} cookbook test(s)\n`);
+      });
+
+      test('service has operations.json', () => {
+        expect(fs.existsSync(operationsPath)).toBe(true);
+
+        expect(operations.operations).toBeDefined();
+        expect(Object.keys(operations.operations).length).toBeGreaterThan(0);
+
+        console.log(`\n✓ Found ${Object.keys(operations.operations).length} operation(s)\n`);
+      });
+
+      test('service has pre-validation script', () => {
+        const packageJson = JSON.parse(
+          fs.readFileSync(path.join(serviceRoot, 'package.json'), 'utf-8')
+        );
+
+        const hasScript = packageJson.scripts['test:cookbooks'] ||
+                         fs.existsSync(path.join(serviceRoot, 'scripts/run-pre-validation.js'));
+
+        expect(hasScript).toBeTruthy();
+
+        console.log('\n✓ Pre-validation script configured\n');
+      });
+    });
+
+    describe('2. Cookbook Test Execution', () => {
+      test('runs cookbook tests successfully', () => {
+        console.log('\n🧪 Running cookbook tests...\n');
+
+        try {
+          const output = execSync('npm run test:cookbooks', {
+            cwd: serviceRoot,
+            encoding: 'utf-8',
+            stdio: 'pipe'
+          });
+
+          console.log(output);
+
+          expect(output).toContain('Pre-Validation Started');
+          expect(output).toContain('Passed:');
+          expect(output).not.toContain('Failed: 1');
+
+          console.log('\n✅ Cookbook tests PASSED\n');
+        } catch (error) {
+          console.error('\n❌ Cookbook tests FAILED:\n');
+          console.error(error.stdout || error.message);
+          throw error;
+        }
+      }, timeout);
+
+      test('mocks infrastructure during tests', () => {
+        const runPreValidationPath = path.join(serviceRoot, 'scripts/run-pre-validation.js');
+
+        if (fs.existsSync(runPreValidationPath)) {
+          const scriptContent = fs.readFileSync(runPreValidationPath, 'utf-8');
+          expect(scriptContent).toContain('mockInfrastructure: true');
+
+          console.log('\n✓ Infrastructure mocking confirmed\n');
+        } else {
+          console.log('\n⚠ No run-pre-validation.js script found (using npm script)\n');
+        }
+      });
+    });
+
+    describe('3. ValidationProof Generation', () => {
+      beforeEach(() => {
+        // Run pre-validation to generate proof
+        console.log('\n🔐 Generating validation proof...\n');
+        execSync('npm run test:cookbooks', {
+          cwd: serviceRoot,
+          stdio: 'pipe'
+        });
+      });
+
+      test('creates .validation-proof.json file', () => {
+        expect(fs.existsSync(proofPath)).toBe(true);
+        console.log('\n✓ Validation proof file created\n');
+      });
+
+      test('proof has correct structure', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        // Required fields
+        expect(proof.validationProof).toBeDefined();
+        expect(proof.validationData).toBeDefined();
+
+        // ValidationData structure
+        const { validationData } = proof;
+        expect(validationData.serviceName).toBe(serviceName);
+        expect(validationData.version).toBeDefined();
+        expect(validationData.validator).toBe('@onlineapps/conn-orch-validator');
+        expect(validationData.validatorVersion).toBeDefined();
+        expect(validationData.validatedAt).toBeDefined();
+        expect(validationData.durationMs).toBeGreaterThan(0);
+        expect(validationData.testsRun).toBeGreaterThan(0);
+        expect(validationData.testsPassed).toBe(validationData.testsRun);
+        expect(validationData.testsFailed).toBe(0);
+
+        console.log('\n📋 Validation Proof Details:');
+        console.log(`   Service: ${validationData.serviceName} v${validationData.version}`);
+        console.log(`   Validator: ${validationData.validator} v${validationData.validatorVersion}`);
+        console.log(`   Tests: ${validationData.testsPassed}/${validationData.testsRun} passed`);
+        console.log(`   Duration: ${validationData.durationMs}ms`);
+        console.log(`   Validated: ${validationData.validatedAt}`);
+        console.log('');
+      });
+
+      test('proof hash is valid SHA256', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        // SHA256 = 64 hex characters
+        expect(proof.validationProof).toMatch(/^[a-f0-9]{64}$/);
+
+        console.log(`\n✓ Valid SHA256 hash: ${proof.validationProof.substring(0, 16)}...\n`);
+      });
+
+      test('all tests passed', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        expect(proof.validationData.testsFailed).toBe(0);
+        expect(proof.validationData.testsPassed).toBeGreaterThan(0);
+        expect(proof.validationData.testsPassed).toBe(proof.validationData.testsRun);
+
+        console.log(`\n✅ All ${proof.validationData.testsPassed} tests PASSED\n`);
+      });
+    });
+
+    describe('4. Proof Integrity Verification', () => {
+      beforeEach(() => {
+        // Generate proof
+        execSync('npm run test:cookbooks', {
+          cwd: serviceRoot,
+          stdio: 'pipe'
+        });
+      });
+
+      test('ValidationProofCodec can decode proof', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        const result = ValidationProofCodec.decode(proof);
+
+        expect(result.valid).toBe(true);
+        expect(result.reason).toBe('VALID');
+        expect(result.details.serviceName).toBe(serviceName);
+
+        console.log('\n✓ Proof successfully decoded and verified\n');
+      });
+
+      test('proof hash matches data', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        // Re-encode to verify hash
+        const reEncoded = ValidationProofCodec.encode(proof.validationData);
+
+        expect(reEncoded.validationProof).toBe(proof.validationProof);
+
+        console.log('\n✓ Proof hash integrity verified\n');
+      });
+
+      test('proof age is recent (< 7 days)', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        const validatedAt = new Date(proof.validationData.validatedAt);
+        const now = new Date();
+        const ageMs = now - validatedAt;
+        const ageDays = ageMs / (24 * 60 * 60 * 1000);
+
+        expect(ageDays).toBeLessThan(7);
+
+        console.log(`\n✓ Proof age: ${Math.round(ageMs / 1000)}s (recent)\n`);
+      });
+
+      test('tampered proof fails verification', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        // Tamper with data
+        proof.validationData.testsPassed = 999;
+
+        const result = ValidationProofCodec.decode(proof);
+
+        expect(result.valid).toBe(false);
+        expect(result.reason).toBe('HASH_MISMATCH');
+
+        console.log('\n✓ Tamper detection working correctly\n');
+      });
+    });
+
+    describe('5. Dependencies Tracking', () => {
+      beforeEach(() => {
+        execSync('npm run test:cookbooks', {
+          cwd: serviceRoot,
+          stdio: 'pipe'
+        });
+      });
+
+      test('proof includes service dependencies', () => {
+        const proof = JSON.parse(fs.readFileSync(proofPath, 'utf-8'));
+
+        expect(proof.validationData.dependencies).toBeDefined();
+        expect(typeof proof.validationData.dependencies).toBe('object');
+
+        // Should include key connectors
+        const deps = proof.validationData.dependencies;
+        const hasConnector = deps['@onlineapps/service-wrapper'] ||
+                            deps['@onlineapps/conn-orch-registry'] ||
+                            deps['@onlineapps/conn-orch-validator'];
+
+        expect(hasConnector).toBeDefined();
+
+        console.log('\n📦 Tracked Dependencies:');
+        for (const [name, version] of Object.entries(deps)) {
+          if (name.startsWith('@onlineapps/')) {
+            console.log(`   ${name}: ${version}`);
+          }
+        }
+        console.log('');
+      });
+    });
+  });
+}
+
+module.exports = { createPreValidationTests };

package/src/helpers/createServiceReadinessTests.js

@@ -0,0 +1,245 @@
+/**
+ * Create Service Readiness Integration Tests
+ *
+ * Generic test suite that validates service HTTP API readiness.
+ * Works for ALL business services - no service-specific code needed.
+ *
+ * @module helpers/createServiceReadinessTests
+ *
+ * Usage:
+ *   const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
+ *   createServiceReadinessTests(__dirname);  // Pass tests/integration directory
+ *
+ * Related:
+ * - /docs/standards/TESTING.md - Testing standards
+ * - /tests/TESTING.md - SPOT principles
+ * - /shared/connector/conn-orch-validator/README.md - Package documentation
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const ServiceReadinessValidator = require('../ServiceReadinessValidator');
+const MockRegistry = require('../mocks/MockRegistry');
+const { ServiceStructureValidator } = require('../validators/ServiceStructureValidator');
+
+/**
+ * Create service readiness integration test suite
+ *
+ * @param {string} testsDir - Path to tests/integration directory (use __dirname)
+ * @param {Object} [options] - Optional configuration
+ * @param {number} [options.testPort=5556] - Port for test server
+ * @param {boolean} [options.includeOptionalChecks=true] - Include cookbook & registry checks
+ * @param {number} [options.timeout=15000] - Test timeout in ms
+ *
+ * @example
+ * // In services/my-service/tests/integration/service-readiness.test.js
+ * const { createServiceReadinessTests } = require('@onlineapps/conn-orch-validator');
+ *
+ * createServiceReadinessTests(__dirname);
+ */
+function createServiceReadinessTests(testsDir, options = {}) {
+  // Calculate service root (2 levels up from tests/integration/)
+  const serviceRoot = path.resolve(testsDir, '../..');
+
+  const {
+    testPort = 5556,
+    includeOptionalChecks = true,
+    timeout = 15000
+  } = options;
+
+  // Validate service structure FIRST
+  console.log('\n🔍 Validating service structure...\n');
+  const structureValidator = new ServiceStructureValidator(serviceRoot);
+  const structureResult = structureValidator.validate();
+
+  // Log validation result
+  console.log(ServiceStructureValidator.formatResult(structureResult));
+
+  // FAIL FAST if structure is invalid
+  if (!structureResult.valid) {
+    throw new Error(
+      `Service structure validation failed. Fix errors above before running tests.`
+    );
+  }
+
+  // Load configuration files (validated above)
+  const configPath = path.join(serviceRoot, 'conn-config/config.json');
+  const operationsPath = path.join(serviceRoot, 'conn-config/operations.json');
+  const appPath = path.join(serviceRoot, 'src/app.js');
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  const operations = JSON.parse(fs.readFileSync(operationsPath, 'utf-8'));
+  const app = require(appPath);
+
+  // Extract metadata from config
+  const serviceName = config.service.name;
+  const serviceVersion = config.service.version;
+  const healthEndpoint = config.wrapper?.health?.endpoint || '/health';
+
+  // Create test suite
+  describe(`${serviceName} Service Readiness @integration`, () => {
+    let server;
+    let baseUrl;
+
+    beforeAll(async () => {
+      // Start service for testing
+      server = await new Promise((resolve) => {
+        const srv = app.listen(testPort, () => {
+          baseUrl = `http://localhost:${testPort}`;
+          console.log(`\n✓ Test server started: ${baseUrl}\n`);
+          resolve(srv);
+        });
+      });
+    });
+
+    afterAll(async () => {
+      // Stop service
+      if (server) {
+        await new Promise((resolve) => {
+          server.close(() => {
+            console.log('\n✓ Test server stopped\n');
+            resolve();
+          });
+        });
+      }
+    });
+
+    test('service passes readiness validation', async () => {
+      // Validator expects flat operations object
+      const operationsFlat = operations.operations || operations;
+
+      // Prepare optional checks
+      let mockRegistry = null;
+      let testCookbook = null;
+
+      if (includeOptionalChecks) {
+        // Create MockRegistry for registry compatibility check (+5 points)
+        mockRegistry = new MockRegistry();
+
+        // Auto-generate test cookbook from operations (+15 points)
+        testCookbook = {
+          version: '1.0.0',
+          steps: Object.entries(operationsFlat).map(([name, op]) => ({
+            id: `test-${name}`,
+            type: 'task',
+            service: serviceName,
+            operation: name,
+            input: generateMockInput(op.input),
+            output: {}
+          }))
+        };
+      }
+
+      // Run readiness validation
+      const validator = new ServiceReadinessValidator();
+      const result = await validator.validateReadiness({
+        name: serviceName,
+        version: serviceVersion,
+        url: baseUrl,
+        operations: operationsFlat,
+        healthEndpoint: healthEndpoint,
+        testCookbook: testCookbook,
+        registry: mockRegistry
+      });
+
+      // Log detailed results
+      console.log('\n📊 Readiness Validation Results:');
+      console.log(`   Score: ${result.score}/100`);
+      console.log(`   Ready: ${result.ready ? '✅' : '❌'}`);
+      console.log('\n   Checks:');
+      for (const [checkName, checkResult] of Object.entries(result.checks || {})) {
+        const icon = checkResult.passed ? '✓' : '✗';
+        const points = checkResult.score || 0;
+        console.log(`   ${icon} ${checkName}: ${points} points`);
+      }
+      if (result.errors && result.errors.length > 0) {
+        console.log('\n   Errors:');
+        for (const error of result.errors) {
+          console.log(`   ✗ ${error}`);
+        }
+      }
+      console.log('');
+
+      // Assertions
+      expect(result).toHaveProperty('ready');
+      expect(result).toHaveProperty('score');
+      expect(result).toHaveProperty('checks');
+      expect(result).toHaveProperty('errors');
+
+      expect(result.ready).toBe(true);
+
+      if (includeOptionalChecks) {
+        expect(result.score).toBe(100);
+        expect(result.checks.health?.passed).toBe(true);
+        expect(result.checks.operations?.passed).toBe(true);
+        expect(result.checks.endpoints?.passed).toBe(true);
+        expect(result.checks.cookbook?.passed).toBe(true);
+        expect(result.checks.registry?.passed).toBe(true);
+      } else {
+        expect(result.score).toBeGreaterThanOrEqual(80);
+        expect(result.checks.health?.passed).toBe(true);
+        expect(result.checks.operations?.passed).toBe(true);
+        expect(result.checks.endpoints?.passed).toBe(true);
+      }
+    }, timeout);
+
+    test('health endpoint responds correctly', async () => {
+      const response = await fetch(`${baseUrl}${healthEndpoint}`);
+      const data = await response.json();
+
+      expect(response.status).toBe(200);
+      expect(data).toHaveProperty('status');
+      expect(data.status).toBe('healthy');
+    });
+
+    test('service has valid operations specification', () => {
+      expect(operations).toBeDefined();
+      expect(operations.operations || operations).toBeDefined();
+
+      const operationsFlat = operations.operations || operations;
+      expect(typeof operationsFlat).toBe('object');
+      expect(Object.keys(operationsFlat).length).toBeGreaterThan(0);
+
+      // Verify operations structure
+      for (const [operationName, operationSpec] of Object.entries(operationsFlat)) {
+        expect(operationSpec).toHaveProperty('endpoint');
+        expect(operationSpec).toHaveProperty('method');
+        expect(operationSpec.endpoint).toMatch(/^\//);
+        expect(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).toContain(operationSpec.method);
+      }
+    });
+  });
+}
+
+/**
+ * Generate mock input data from operation input schema
+ *
+ * @param {Object} inputSchema - Input schema from operations.json
+ * @returns {Object} Mock input data
+ * @private
+ */
+function generateMockInput(inputSchema) {
+  const mockData = {};
+  for (const [fieldName, fieldSpec] of Object.entries(inputSchema || {})) {
+    if (fieldSpec.required) {
+      switch (fieldSpec.type) {
+        case 'string':
+          mockData[fieldName] = 'Test';
+          break;
+        case 'number':
+          mockData[fieldName] = 0;
+          break;
+        case 'boolean':
+          mockData[fieldName] = false;
+          break;
+        default:
+          mockData[fieldName] = null;
+      }
+    }
+  }
+  return mockData;
+}
+
+module.exports = { createServiceReadinessTests };

package/src/index.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Mock infrastructure components (load first - no dependencies)
+const MockMQClient = require('./mocks/MockMQClient');
+const MockRegistry = require('./mocks/MockRegistry');
+const MockStorage = require('./mocks/MockStorage');
+
+// Base test utilities (no circular dependencies)
+const ServiceValidator = require('./ServiceValidator');
+const CookbookTestUtils = require('./CookbookTestUtils');
+const { ServiceStructureValidator } = require('./validators/ServiceStructureValidator');
+const ValidationProofGenerator = require('./validators/ValidationProofGenerator');
+
+// Test runners (depend on mocks)
+let CookbookTestRunner;
+try {
+  CookbookTestRunner = require('./CookbookTestRunner');
+} catch (error) {
+  console.error('[conn-orch-validator] WARNING: Failed to load CookbookTestRunner:', error.message);
+}
+const WorkflowTestRunner = require('./WorkflowTestRunner');
+
+// Orchestrators (depend on validators and runners)
+const ServiceReadinessValidator = require('./ServiceReadinessValidator');
+const TestOrchestrator = require('./TestOrchestrator');
+const ServiceTestHarness = require('./ServiceTestHarness');
+const ValidationOrchestrator = require('./ValidationOrchestrator');
+
+// Test helpers (generic test suite creators)
+const { createServiceReadinessTests } = require('./helpers/createServiceReadinessTests');
+const { createPreValidationTests } = require('./helpers/createPreValidationTests');
+
+// Export all components with getters to avoid circular dependency issues
+module.exports = {
+  // Mocks
+  get MockMQClient() { return MockMQClient; },
+  get MockRegistry() { return MockRegistry; },
+  get MockStorage() { return MockStorage; },
+
+  // Test utilities
+  get ServiceTestHarness() { return ServiceTestHarness; },
+  get ServiceValidator() { return ServiceValidator; },
+  get WorkflowTestRunner() { return WorkflowTestRunner; },
+  get CookbookTestUtils() { return CookbookTestUtils; },
+  get ServiceReadinessValidator() { return ServiceReadinessValidator; },
+  get TestOrchestrator() { return TestOrchestrator; },
+  get CookbookTestRunner() { return CookbookTestRunner; },
+  get ValidationProofGenerator() { return ValidationProofGenerator; },
+  get ServiceStructureValidator() { return ServiceStructureValidator; },
+  get ValidationOrchestrator() { return ValidationOrchestrator; },
+
+  // Test helpers (NEW - generic test suite creators)
+  get createServiceReadinessTests() { return createServiceReadinessTests; },
+  get createPreValidationTests() { return createPreValidationTests; },
+
+  // Convenience factory functions
+  createTestHarness: (options) => new ServiceTestHarness(options),
+  createValidator: (options) => new ServiceValidator(options),
+  createMockMQ: () => new MockMQClient(),
+  createMockRegistry: () => new MockRegistry(),
+  createMockStorage: () => new MockStorage()
+};