@zohodesk/unit-testing-framework 0.0.30-experimental → 0.0.31-experimental

package/build/src/runner/__tests__/jest-runner.test.js

@@ -0,0 +1,115 @@
+"use strict";
+
+var _jestRunner = _interopRequireDefault(require("../jest-runner.js"));
+var _pipelineSummary = require("../../utils/pipeline-summary.js");
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _url = require("url");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const _dirname = _path.default.dirname((0, _url.fileURLToPath)(import.meta.url));
+const TEST_OUTPUT_DIR = _path.default.join(_dirname, '../../__temp__');
+describe('createJestRunner with Pipeline Summary', () => {
+  let tempDir;
+  beforeEach(() => {
+    tempDir = _path.default.join(TEST_OUTPUT_DIR, 'jest-runner-test');
+    if (!_fs.default.existsSync(tempDir)) {
+      _fs.default.mkdirSync(tempDir, {
+        recursive: true
+      });
+    }
+  });
+  afterEach(() => {
+    if (_fs.default.existsSync(tempDir)) {
+      _fs.default.rmSync(tempDir, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  test('should return object with testResults, summary, and success flag', async () => {
+    const summaryPath = _path.default.join(tempDir, 'summary.json');
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'src/utils/__tests__/pipeline-summary.test.js'
+    });
+    expect(result).toHaveProperty('testResults');
+    expect(result).toHaveProperty('summary');
+    expect(result).toHaveProperty('success');
+    expect(typeof result.success).toBe('boolean');
+  });
+  test('should create summary file at specified path', async () => {
+    const summaryPath = _path.default.join(tempDir, 'test-summary.json');
+    await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'src/utils/__tests__/pipeline-summary.test.js'
+    });
+    expect(_fs.default.existsSync(summaryPath)).toBe(true);
+    const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+    expect(content.status).toMatch(/^(SUCCESS|FAILURE)$/);
+  });
+  test('should generate SUCCESS summary when tests pass', async () => {
+    const summaryPath = _path.default.join(tempDir, 'success-summary.json');
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'src/utils/__tests__/pipeline-summary.test.js'
+    });
+    if (result.success) {
+      expect(result.summary.status).toBe('SUCCESS');
+      expect(result.summary.message).toContain('passed');
+    }
+  });
+  test('should include web_url in summary when provided', async () => {
+    const summaryPath = _path.default.join(tempDir, 'url-summary.json');
+    const webUrl = 'https://ci.example.com/build/123';
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      webUrl,
+      testFiles: 'src/utils/__tests__/pipeline-summary.test.js'
+    });
+    expect(result.summary.web_url).toBe(webUrl);
+  });
+  test('should handle missing test files gracefully', async () => {
+    const summaryPath = _path.default.join(tempDir, 'error-summary.json');
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'nonexistent-file.test.js'
+    });
+    expect(_fs.default.existsSync(summaryPath)).toBe(true);
+    const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+    expect(content.status).toBe('FAILURE');
+  });
+  test('should use default summary path if not provided', async () => {
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      testFiles: 'src/utils/__tests__/pipeline-summary.test.js'
+    });
+
+    // Should create reports directory and test-summary.json
+    expect(result.summary).toBeDefined();
+    expect(result.summary.status).toMatch(/^(SUCCESS|FAILURE)$/);
+  });
+  test('summary should have valid error structure on failure', async () => {
+    const summaryPath = _path.default.join(tempDir, 'error-check-summary.json');
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'nonexistent.test.js'
+    });
+    if (!result.success) {
+      const {
+        summary
+      } = result;
+      expect(summary.status).toBe('FAILURE');
+      expect(summary.error).toBeDefined();
+      expect(summary.error.code).toBeDefined();
+      expect(summary.error.category).toMatch(/^(code|environment|flaky|tool)$/);
+      expect(summary.error.message).toBeDefined();
+      expect(Array.isArray(summary.error.errors)).toBe(true);
+    }
+  });
+});

package/build/src/runner/jest-runner.js

@@ -8,6 +8,7 @@ var _fs = _interopRequireDefault(require("fs"));
 var _path = _interopRequireDefault(require("path"));
 var _runnerBase = require("./runner-base.js");
 var _configLoader = require("../config/config-loader.js");
+var _pipelineSummary = require("../utils/pipeline-summary.js");
 var _logger = require("../utils/logger.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function resolveTestFiles(testFiles, projectRoot) {
@@ -32,21 +33,135 @@ async function createJestRunner(options = {}) {
     testFiles,
     testPathPattern,
     configPath,
-    watch = false
+    watch = false,
+    summaryPath = _path.default.join(projectRoot, 'test-slices', 'unit-test', 'unit_reports', 'ut-test-summary.json'),
+    webUrl = process.env.CI_BUILD_URL || ''
   } = options;
 
-  // ── 1. Resolve config (auto-discover / configPath / default) ──
-  const config = await (0, _configLoader.resolveConfig)(projectRoot, configPath);
+  // ── 0. Setup pipeline summary (mandatory) ──────────────────────
+  _logger.Logger.info(`Summary path: ${summaryPath}`);
+  const summary = (0, _pipelineSummary.createPipelineSummary)('JestRunner', {
+    outputPath: summaryPath,
+    webUrl
+  });
+  try {
+    // ── 1. Resolve config (auto-discover / configPath / default) ──
+    const config = await (0, _configLoader.resolveConfig)(projectRoot, configPath);
 
-  // ── 2. Resolve test file pattern ──────────────────────────────
-  const rawPattern = testFiles || testPathPattern;
-  const pattern = rawPattern && rawPattern.includes(',') ? resolveTestFiles(rawPattern, projectRoot) : rawPattern;
+    // ── 2. Resolve test file pattern ──────────────────────────────
+    const rawPattern = testFiles || testPathPattern;
+    const pattern = rawPattern && rawPattern.includes(',') ? resolveTestFiles(rawPattern, projectRoot) : rawPattern;
 
-  // ── 3. Build argv & run Jest ──────────────────────────────────
-  const argv = (0, _runnerBase.buildArgv)(config, {
-    testMatch: pattern,
-    watch,
-    projectRoot
-  });
-  return (0, _runnerBase.executeJest)(argv, projectRoot);
+    // ── 3. Build argv & run Jest ──────────────────────────────────
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      testMatch: pattern,
+      watch,
+      projectRoot
+    });
+    const testResults = await (0, _runnerBase.executeJest)(argv, projectRoot);
+
+    // ── 4. Process results and generate summary ───────────────────
+    if (!testResults) {
+      const response = summary.toolError({
+        toolName: 'jest',
+        error: 'No test results returned',
+        exitCode: 1
+      });
+      const saved = summary.saveToFile(response);
+      if (!saved) {
+        _logger.Logger.warn('⚠ Warning: Error summary file could not be saved');
+      }
+      return {
+        testResults: null,
+        summary: response,
+        success: false
+      };
+    }
+    if (testResults.numFailedTests > 0) {
+      const response = summary.testFailure({
+        testResults
+      });
+      summary.saveToFile(response);
+      return {
+        testResults,
+        summary: response,
+        success: false
+      };
+    }
+    if (testResults.numTotalTests === 0) {
+      const response = summary.failure({
+        message: 'No tests found',
+        errorCode: 'NO_TESTS_FOUND',
+        errorCategory: 'code',
+        errorMessage: 'No test files matched the pattern'
+      });
+      summary.saveToFile(response);
+      return {
+        testResults,
+        summary: response,
+        success: false
+      };
+    }
+
+    // All tests passed
+    const response = summary.success({
+      message: `All ${testResults.numTotalTests} tests passed (${testResults.numPassedTests} passed, ${testResults.numSkippedTests} skipped)`
+    });
+    const saved = summary.saveToFile(response);
+    if (!saved) {
+      _logger.Logger.warn('⚠ Warning: Summary file could not be saved');
+    } else {
+      _logger.Logger.success(`✓ Test Summary saved to: ${summaryPath}`);
+    }
+    return {
+      testResults,
+      summary: response,
+      success: true
+    };
+  } catch (error) {
+    // ── 5. Error handling ────────────────────────────────────────
+    _logger.Logger.error(`✗ Jest execution error: ${error.message}`);
+    let response;
+    if (error.message.includes('heap') || error.message.includes('memory') || error.message.includes('ENOMEM')) {
+      response = summary.environmentError({
+        issue: 'Out of memory during test execution',
+        requirement: 'Sufficient heap memory',
+        suggestion: 'Increase Node.js heap size: NODE_OPTIONS=--max-old-space-size=4096'
+      });
+    } else if (error.message.includes('MODULE_NOT_FOUND') || error.message.includes('Cannot find')) {
+      response = summary.environmentError({
+        issue: 'Missing dependency',
+        suggestion: 'Run: npm install'
+      });
+    } else if (error.code === 'ENOENT') {
+      response = summary.failure({
+        message: 'Test file or configuration not found',
+        errorCode: 'FILE_NOT_FOUND',
+        errorCategory: 'environment',
+        errorMessage: `${error.path || 'Unknown file'} not found`
+      });
+    } else if (error.message.includes('ECONNREFUSED')) {
+      response = summary.environmentError({
+        issue: 'Connection refused to external service',
+        suggestion: 'Check if required services (database, cache) are running'
+      });
+    } else {
+      response = summary.toolError({
+        toolName: 'jest',
+        error,
+        exitCode: error.code || 1
+      });
+    }
+    const saved = summary.saveToFile(response);
+    if (saved) {
+      _logger.Logger.error(`✓ Error Summary saved to: ${summaryPath}`);
+    } else {
+      _logger.Logger.warn('⚠ Warning: Error summary file could not be saved');
+    }
+    return {
+      testResults: null,
+      summary: response,
+      success: false
+    };
+  }
 }

package/build/src/utils/__tests__/pipeline-summary-directory.test.js

@@ -0,0 +1,248 @@
+"use strict";
+
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _url = require("url");
+var _pipelineSummary = require("../pipeline-summary.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const _dirname = _path.default.dirname((0, _url.fileURLToPath)(import.meta.url));
+const TEST_ROOT = _path.default.join(_dirname, '../../__temp__/dir-tests');
+describe('Pipeline Summary - Directory Creation Edge Cases', () => {
+  afterEach(() => {
+    // Cleanup
+    if (_fs.default.existsSync(TEST_ROOT)) {
+      _fs.default.rmSync(TEST_ROOT, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+  describe('Single level directory creation', () => {
+    test('should create single-level directory', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'reports', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success({
+        message: 'Test passed'
+      });
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summaryPath)).toBe(true);
+      const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+      expect(content.status).toBe('SUCCESS');
+    });
+  });
+  describe('Multi-level directory creation', () => {
+    test('should create deeply nested directories', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'a', 'b', 'c', 'd', 'e', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.failure({
+        message: 'Test failed',
+        errorCode: 'TEST_ERROR',
+        errorCategory: 'code',
+        errorMessage: 'Assertion failed'
+      });
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summaryPath)).toBe(true);
+
+      // Verify all parent directories were created
+      const allDirs = [_path.default.join(TEST_ROOT, 'a'), _path.default.join(TEST_ROOT, 'a', 'b'), _path.default.join(TEST_ROOT, 'a', 'b', 'c'), _path.default.join(TEST_ROOT, 'a', 'b', 'c', 'd'), _path.default.join(TEST_ROOT, 'a', 'b', 'c', 'd', 'e')];
+      allDirs.forEach(dir => {
+        expect(_fs.default.existsSync(dir)).toBe(true);
+      });
+    });
+  });
+  describe('Directory already exists', () => {
+    test('should handle when directory already exists', () => {
+      const dir = _path.default.join(TEST_ROOT, 'existing');
+      _fs.default.mkdirSync(dir, {
+        recursive: true
+      });
+      const summaryPath = _path.default.join(dir, 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summaryPath)).toBe(true);
+    });
+  });
+  describe('File overwrite', () => {
+    test('should overwrite existing summary file', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'reports', 'summary.json');
+      _fs.default.mkdirSync(_path.default.dirname(summaryPath), {
+        recursive: true
+      });
+
+      // Write first response
+      _fs.default.writeFileSync(summaryPath, JSON.stringify({
+        version: 1
+      }), 'utf-8');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success({
+        message: 'New summary'
+      });
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+      expect(content.status).toBe('SUCCESS');
+      expect(content.message).toBe('New summary');
+      expect(content.version).toBeUndefined();
+    });
+  });
+  describe('Invalid path handling', () => {
+    test('should handle null output path', () => {
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: null
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(false);
+    });
+    test('should handle empty output path', () => {
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: ''
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(false);
+    });
+    test('should handle override path', () => {
+      const primaryPath = _path.default.join(TEST_ROOT, 'primary.json');
+      const overridePath = _path.default.join(TEST_ROOT, 'custom', 'override.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: primaryPath
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response, overridePath);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(overridePath)).toBe(true);
+      expect(_fs.default.existsSync(primaryPath)).toBe(false);
+    });
+  });
+  describe('Complex paths with special characters', () => {
+    test('should handle paths with hyphens and underscores', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'test-reports_v2', 'unit-tests_final', 'summary-result.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summaryPath)).toBe(true);
+    });
+    test('should handle paths with dots and numbers', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'v2.1.0', 'reports-2024.01.15', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summaryPath)).toBe(true);
+    });
+  });
+  describe('File content verification', () => {
+    test('should write valid JSON with proper formatting', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'reports', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.success({
+        message: 'All tests passed'
+      });
+      summary.saveToFile(response);
+      const content = _fs.default.readFileSync(summaryPath, 'utf-8');
+
+      // Verify it's valid JSON
+      expect(() => JSON.parse(content)).not.toThrow();
+
+      // Verify formatting (should have indentation)
+      expect(content).toContain('\n  ');
+
+      // Verify content
+      const parsed = JSON.parse(content);
+      expect(parsed.status).toBe('SUCCESS');
+      expect(parsed.message).toBe('All tests passed');
+    });
+    test('should handle complex response objects', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'reports', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+      const response = summary.testFailure({
+        testResults: {
+          numTotalTests: 100,
+          numFailedTests: 5,
+          numPassedTests: 95,
+          numSkippedTests: 0,
+          testResults: [{
+            name: 'test.js',
+            numFailingTests: 1,
+            assertionResults: [{
+              title: 'should work',
+              fullName: 'Suite › should work',
+              status: 'failed',
+              failureMessages: ['Expected true to be false']
+            }]
+          }]
+        }
+      });
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+      expect(content.error.errors).toHaveLength(1);
+      expect(content.result[0].failedTests).toBe(5);
+    });
+  });
+  describe('Concurrent operations', () => {
+    test('should handle sequential saves to different files', () => {
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: _path.default.join(TEST_ROOT, 'file1.json')
+      });
+      const response1 = summary.success({
+        message: 'First'
+      });
+      const response2 = summary.failure({
+        message: 'Second'
+      });
+      const saved1 = summary.saveToFile(response1);
+      const saved2 = summary.saveToFile(response2, _path.default.join(TEST_ROOT, 'file2.json'));
+      expect(saved1).toBe(true);
+      expect(saved2).toBe(true);
+      expect(_fs.default.existsSync(_path.default.join(TEST_ROOT, 'file1.json'))).toBe(true);
+      expect(_fs.default.existsSync(_path.default.join(TEST_ROOT, 'file2.json'))).toBe(true);
+    });
+    test('should handle multiple saves to same location', () => {
+      const summaryPath = _path.default.join(TEST_ROOT, 'reports', 'summary.json');
+      const summary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: summaryPath
+      });
+
+      // First save
+      const response1 = summary.success({
+        message: 'First attempt'
+      });
+      const saved1 = summary.saveToFile(response1);
+      expect(saved1).toBe(true);
+
+      // Second save (overwrite)
+      const response2 = summary.success({
+        message: 'Second attempt'
+      });
+      const saved2 = summary.saveToFile(response2);
+      expect(saved2).toBe(true);
+
+      // Verify only latest content exists
+      const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
+      expect(content.message).toBe('Second attempt');
+    });
+  });
+});

package/build/src/utils/__tests__/pipeline-summary.test.js

@@ -0,0 +1,473 @@
+"use strict";
+
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _url = require("url");
+var _pipelineSummary = require("../pipeline-summary.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const _dirname = _path.default.dirname((0, _url.fileURLToPath)(import.meta.url));
+const TEST_OUTPUT_DIR = _path.default.join(_dirname, '../../__temp__');
+describe('PipelineSummaryGenerator', () => {
+  let summary;
+  beforeEach(() => {
+    summary = (0, _pipelineSummary.createPipelineSummary)('TestStage', {
+      outputPath: _path.default.join(TEST_OUTPUT_DIR, 'test-summary.json'),
+      webUrl: 'https://example.com/report'
+    });
+
+    // Create temp directory
+    if (!_fs.default.existsSync(TEST_OUTPUT_DIR)) {
+      _fs.default.mkdirSync(TEST_OUTPUT_DIR, {
+        recursive: true
+      });
+    }
+  });
+  afterEach(() => {
+    // Clean up
+    if (_fs.default.existsSync(TEST_OUTPUT_DIR)) {
+      _fs.default.rmSync(TEST_OUTPUT_DIR, {
+        recursive: true,
+        force: true
+      });
+    }
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // SUCCESS RESPONSE TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('success()', () => {
+    test('should create success response with defaults', () => {
+      const response = summary.success();
+      expect(response.status).toBe('SUCCESS');
+      expect(response.message).toBe('TestStage completed successfully');
+      expect(response.web_url).toBe('https://example.com/report');
+    });
+    test('should create success response with custom message', () => {
+      const response = summary.success({
+        message: 'All tests passed'
+      });
+      expect(response.status).toBe('SUCCESS');
+      expect(response.message).toBe('All tests passed');
+    });
+    test('should create success response with custom web_url', () => {
+      const response = summary.success({
+        webUrl: 'https://example.com/custom-report'
+      });
+      expect(response.web_url).toBe('https://example.com/custom-report');
+    });
+    test('should not contain error field in success response', () => {
+      const response = summary.success();
+      expect(response).not.toHaveProperty('error');
+      expect(response).not.toHaveProperty('result');
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // FAILURE RESPONSE TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('failure()', () => {
+    test('should create failure response with defaults', () => {
+      const response = summary.failure();
+      expect(response.status).toBe('FAILURE');
+      expect(response.message).toBe('TestStage failed');
+      expect(response.error.code).toBe('UNKNOWN_ERROR');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.TOOL);
+      expect(Array.isArray(response.error.errors)).toBe(true);
+    });
+    test('should create failure response with custom error details', () => {
+      const response = summary.failure({
+        message: 'Database connection failed',
+        errorCode: 'DB_CONN_ERROR',
+        errorCategory: _pipelineSummary.ERROR_CATEGORIES.ENVIRONMENT,
+        errorMessage: 'Cannot connect to database',
+        errors: ['Connection timeout', 'Host unreachable']
+      });
+      expect(response.status).toBe('FAILURE');
+      expect(response.message).toBe('Database connection failed');
+      expect(response.error.code).toBe('DB_CONN_ERROR');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.ENVIRONMENT);
+      expect(response.error.message).toBe('Cannot connect to database');
+      expect(response.error.errors).toHaveLength(2);
+    });
+    test('should accept single error and convert to array', () => {
+      const response = summary.failure({
+        errors: 'Single error message'
+      });
+      expect(Array.isArray(response.error.errors)).toBe(true);
+      expect(response.error.errors[0]).toBe('Single error message');
+    });
+    test('should include result field if provided', () => {
+      const response = summary.failure({
+        result: [{
+          key: 'value'
+        }]
+      });
+      expect(response.result).toEqual([{
+        key: 'value'
+      }]);
+    });
+    test('should not include empty result field', () => {
+      const response = summary.failure({
+        result: []
+      });
+      expect(response).not.toHaveProperty('result');
+    });
+    test('should validate and warn for invalid error category', () => {
+      const response = summary.failure({
+        errorCategory: 'invalid_category'
+      });
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.TOOL);
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // TEST FAILURE TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('testFailure()', () => {
+    test('should handle test failure without results object', () => {
+      const response = summary.testFailure({
+        message: 'Tests failed'
+      });
+      expect(response.status).toBe('FAILURE');
+      expect(response.error.code).toBe('TEST_FAILURE');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.CODE);
+    });
+    test('should extract failed test information from jest results', () => {
+      const testResults = {
+        numTotalTests: 10,
+        numFailedTests: 2,
+        numPassedTests: 8,
+        numSkippedTests: 0,
+        testResults: [{
+          name: 'test-file-1.js',
+          numFailingTests: 1,
+          assertionResults: [{
+            title: 'Test 1',
+            fullName: 'Suite › Test 1',
+            status: 'failed',
+            failureMessages: ['Expected true to be false']
+          }]
+        }, {
+          name: 'test-file-2.js',
+          numFailingTests: 1,
+          assertionResults: [{
+            title: 'Test 2',
+            fullName: 'Suite › Test 2',
+            status: 'failed',
+            failureMessages: ['Timeout after 5000ms']
+          }]
+        }]
+      };
+      const response = summary.testFailure({
+        testResults
+      });
+      expect(response.error.errors).toHaveLength(2);
+      expect(response.error.errors[0].test).toBe('Suite › Test 1');
+      expect(response.error.errors[0].file).toBe('test-file-1.js');
+      expect(response.result[0].failedTests).toBe(2);
+    });
+    test('should include test statistics in result', () => {
+      const testResults = {
+        numTotalTests: 50,
+        numFailedTests: 5,
+        numPassedTests: 45,
+        numSkippedTests: 0,
+        testResults: []
+      };
+      const response = summary.testFailure({
+        testResults
+      });
+      expect(response.result[0]).toEqual({
+        totalTests: 50,
+        failedTests: 5,
+        passedTests: 45,
+        skippedTests: 0
+      });
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // TOOL ERROR TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('toolError()', () => {
+    test('should handle error object', () => {
+      const error = new Error('Module not found');
+      error.stack = 'Error: Module not found\n    at line 10';
+      const response = summary.toolError({
+        toolName: 'jest',
+        error,
+        exitCode: 1
+      });
+      expect(response.status).toBe('FAILURE');
+      expect(response.error.code).toBe('JEST_EXECUTION_ERROR');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.TOOL);
+      expect(response.error.errors[0].tool).toBe('jest');
+      expect(response.error.errors[0].stack).toBeDefined();
+    });
+    test('should handle string error message', () => {
+      const response = summary.toolError({
+        toolName: 'npm',
+        error: 'npm ERR! code ERESOLVE',
+        exitCode: 1
+      });
+      expect(response.error.errors[0].message).toBe('npm ERR! code ERESOLVE');
+    });
+    test('should handle missing error', () => {
+      const response = summary.toolError({
+        toolName: 'webpack',
+        exitCode: 127
+      });
+      expect(response.error.errors[0].message).toBeFalsy();
+      expect(response.error.errors[0].tool).toBe('webpack');
+    });
+    test('should format tool name in error code', () => {
+      const response = summary.toolError({
+        toolName: 'eslint',
+        error: 'Linting failed'
+      });
+      expect(response.error.code).toBe('ESLINT_EXECUTION_ERROR');
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // ENVIRONMENT ERROR TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('environmentError()', () => {
+    test('should create environment error response', () => {
+      const response = summary.environmentError({
+        issue: 'Node.js version too old',
+        requirement: 'Node.js >= 16',
+        suggestion: 'Update Node.js'
+      });
+      expect(response.status).toBe('FAILURE');
+      expect(response.error.code).toBe('ENV_SETUP_ERROR');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.ENVIRONMENT);
+      expect(response.error.errors[0].issue).toBe('Node.js version too old');
+      expect(response.error.errors[0].requirement).toBe('Node.js >= 16');
+      expect(response.error.errors[0].suggestion).toBe('Update Node.js');
+    });
+    test('should handle partial environment error details', () => {
+      const response = summary.environmentError({
+        issue: 'Missing DATABASE_URL'
+      });
+      expect(response.error.errors[0]).toEqual({
+        issue: 'Missing DATABASE_URL'
+      });
+    });
+    test('should use default issue message', () => {
+      const response = summary.environmentError();
+      expect(response.error.errors[0].issue).toBe('Environment configuration issue');
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // FLAKY TEST TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('flakyTestFailure()', () => {
+    test('should create flaky test failure response', () => {
+      const response = summary.flakyTestFailure({
+        testNames: ['Test A', 'Test B'],
+        attemptNumber: 1,
+        maxAttempts: 3
+      });
+      expect(response.status).toBe('FAILURE');
+      expect(response.error.code).toBe('FLAKY_TEST_FAILURE');
+      expect(response.error.category).toBe(_pipelineSummary.ERROR_CATEGORIES.FLAKY);
+      expect(response.error.errors).toHaveLength(2);
+      expect(response.result[0].attemptNumber).toBe(1);
+      expect(response.result[0].maxAttempts).toBe(3);
+    });
+    test('should include attempt information in message', () => {
+      const response = summary.flakyTestFailure({
+        testNames: ['Flaky Test'],
+        attemptNumber: 2,
+        maxAttempts: 3
+      });
+      expect(response.message).toContain('attempt 2/3');
+    });
+    test('should handle custom message override', () => {
+      const response = summary.flakyTestFailure({
+        testNames: ['Test'],
+        message: 'Custom flaky message'
+      });
+      expect(response.message).toBe('Custom flaky message');
+    });
+    test('should use default attempt values', () => {
+      const response = summary.flakyTestFailure({
+        testNames: ['Test']
+      });
+      expect(response.result[0].attemptNumber).toBe(1);
+      expect(response.result[0].maxAttempts).toBe(3);
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // FILE SAVE TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('saveToFile()', () => {
+    test('should save response to file', () => {
+      const response = summary.success();
+      const saved = summary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summary.outputPath)).toBe(true);
+      const content = _fs.default.readFileSync(summary.outputPath, 'utf-8');
+      const parsed = JSON.parse(content);
+      expect(parsed.status).toBe('SUCCESS');
+    });
+    test('should create parent directories if not exist', () => {
+      const customPath = _path.default.join(TEST_OUTPUT_DIR, 'nested/deep/summary.json');
+      const customSummary = (0, _pipelineSummary.createPipelineSummary)('Test', {
+        outputPath: customPath
+      });
+      const response = customSummary.success();
+      const saved = customSummary.saveToFile(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(customPath)).toBe(true);
+    });
+    test('should handle missing output path', () => {
+      const noPathSummary = (0, _pipelineSummary.createPipelineSummary)('Test');
+      const response = noPathSummary.success();
+      const saved = noPathSummary.saveToFile(response);
+      expect(saved).toBe(false);
+    });
+    test('should format JSON with indentation', () => {
+      const response = summary.success();
+      summary.saveToFile(response);
+      const content = _fs.default.readFileSync(summary.outputPath, 'utf-8');
+      expect(content).toContain('\n');
+      expect(content).toContain('  ');
+    });
+    test('should override output path', () => {
+      const customPath = _path.default.join(TEST_OUTPUT_DIR, 'custom.json');
+      const response = summary.success();
+      summary.saveToFile(response, customPath);
+      expect(_fs.default.existsSync(customPath)).toBe(true);
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // SAVE AND RETURN TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('saveAndReturn()', () => {
+    test('should return response and save status', () => {
+      const response = summary.success();
+      const {
+        response: retResponse,
+        saved
+      } = summary.saveAndReturn(response);
+      expect(retResponse).toEqual(response);
+      expect(saved).toBe(true);
+      expect(_fs.default.existsSync(summary.outputPath)).toBe(true);
+    });
+    test('should indicate save failure', () => {
+      const noPathSummary = (0, _pipelineSummary.createPipelineSummary)('Test');
+      const response = noPathSummary.success();
+      const {
+        saved
+      } = noPathSummary.saveAndReturn(response);
+      expect(saved).toBe(false);
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // EDGE CASES
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('edge cases', () => {
+    test('should handle very long error messages', () => {
+      const longMessage = 'x'.repeat(10000);
+      const response = summary.failure({
+        errorMessage: longMessage
+      });
+      expect(response.error.message).toBe(longMessage);
+    });
+    test('should handle special characters in messages', () => {
+      const response = summary.failure({
+        message: 'Failed: "test" & <script>alert(1)</script>'
+      });
+      expect(response.message).toContain('<script>');
+    });
+    test('should handle null/undefined in optional fields', () => {
+      const response = summary.failure({
+        errorMessage: null,
+        errors: null
+      });
+      expect(response.error.message).toBeNull();
+      expect(Array.isArray(response.error.errors)).toBe(true);
+    });
+    test('should handle errors with circular references', () => {
+      const circularObj = {
+        name: 'test'
+      };
+      circularObj.self = circularObj;
+
+      // Should not throw
+      const response = summary.failure({
+        errors: [circularObj]
+      });
+      expect(response.error.errors).toBeDefined();
+    });
+    test('should handle unicode characters', () => {
+      const response = summary.failure({
+        errorMessage: '测试失败 🔥 エラーが発生しました'
+      });
+      expect(response.error.message).toContain('测试失败');
+      expect(response.error.message).toContain('🔥');
+    });
+    test('should handle multiple consecutive saves', () => {
+      const response1 = summary.success({
+        message: 'First'
+      });
+      const response2 = summary.failure({
+        message: 'Second'
+      });
+      summary.saveToFile(response1);
+      summary.saveToFile(response2);
+      const content = _fs.default.readFileSync(summary.outputPath, 'utf-8');
+      const parsed = JSON.parse(content);
+      expect(parsed.message).toBe('Second');
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // ERROR CATEGORIES EXPORT
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('ERROR_CATEGORIES', () => {
+    test('should export valid error categories', () => {
+      expect(_pipelineSummary.ERROR_CATEGORIES.CODE).toBe('code');
+      expect(_pipelineSummary.ERROR_CATEGORIES.ENVIRONMENT).toBe('environment');
+      expect(_pipelineSummary.ERROR_CATEGORIES.FLAKY).toBe('flaky');
+      expect(_pipelineSummary.ERROR_CATEGORIES.TOOL).toBe('tool');
+    });
+  });
+
+  // ──────────────────────────────────────────────────────────────────────
+  // FACTORY FUNCTION TESTS
+  // ──────────────────────────────────────────────────────────────────────
+
+  describe('createPipelineSummary()', () => {
+    test('should create instance with stage name', () => {
+      const instance = (0, _pipelineSummary.createPipelineSummary)('MyStage');
+      expect(instance).toBeInstanceOf(_pipelineSummary.PipelineSummaryGenerator);
+      const response = instance.success();
+      expect(response.message).toContain('MyStage');
+    });
+    test('should merge options correctly', () => {
+      const instance = (0, _pipelineSummary.createPipelineSummary)('Build', {
+        outputPath: '/path/to/file.json',
+        webUrl: 'https://example.com'
+      });
+      const response = instance.success();
+      expect(response.web_url).toBe('https://example.com');
+    });
+  });
+});

package/build/src/utils/pipeline-summary.js

@@ -0,0 +1,359 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PipelineSummaryGenerator = exports.ERROR_CATEGORIES = void 0;
+exports.createPipelineSummary = createPipelineSummary;
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _logger = require("./logger.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Error Categories
+ * - 'code': Issues in test/application code
+ * - 'environment': Environment setup, dependencies, configuration issues
+ * - 'flaky': Intermittent test failures
+ * - 'tool': Tool execution failures (jest, npm, etc.)
+ */
+const ERROR_CATEGORIES = exports.ERROR_CATEGORIES = {
+  CODE: 'code',
+  ENVIRONMENT: 'environment',
+  FLAKY: 'flaky',
+  TOOL: 'tool'
+};
+
+/**
+ * Pipeline Summary Generator
+ * Creates standardized JSON responses for pipeline stages
+ */
+class PipelineSummaryGenerator {
+  constructor(options = {}) {
+    this.stageName = options.stageName || 'unknown';
+    this.outputPath = options.outputPath || null;
+    this.webUrl = options.webUrl || null;
+  }
+
+  /**
+   * Create a SUCCESS response
+   * @param {Object} params - Response parameters
+   * @param {string} params.message - Custom message
+   * @param {string} params.webUrl - Optional URL override
+   * @returns {Object} Success response object
+   */
+  success(params = {}) {
+    const response = {
+      status: 'SUCCESS',
+      message: params.message || `${this.stageName} completed successfully`,
+      web_url: params.webUrl || this.webUrl || ''
+    };
+    this._logResponse(response);
+    return response;
+  }
+
+  /**
+   * Create a FAILURE response with error details
+   * @param {Object} params - Failure parameters
+   * @param {string} params.message - Custom message for the stage
+   * @param {string} params.errorCode - Custom error code
+   * @param {string} params.errorCategory - One of: 'code', 'environment', 'flaky', 'tool'
+   * @param {string} params.errorMessage - Detailed error message
+   * @param {Array} params.errors - List of detailed errors
+   * @param {Array} params.result - Optional result data
+   * @returns {Object} Failure response object
+   */
+  failure(params = {}) {
+    const {
+      message = `${this.stageName} failed`,
+      errorCode = 'UNKNOWN_ERROR',
+      errorCategory = ERROR_CATEGORIES.TOOL,
+      errorMessage = 'An unexpected error occurred',
+      errors = [],
+      result = []
+    } = params;
+    if (!this._isValidErrorCategory(errorCategory)) {
+      _logger.Logger.warn(`Invalid error category: ${errorCategory}. Using 'tool' as default.`);
+    }
+    const response = {
+      status: 'FAILURE',
+      message,
+      web_url: this.webUrl || '',
+      error: {
+        code: errorCode,
+        category: errorCategory,
+        message: errorMessage,
+        errors: Array.isArray(errors) ? errors : [errors]
+      }
+    };
+    if (Array.isArray(result) && result.length > 0) {
+      response.result = result;
+    }
+    this._logResponse(response);
+    return response;
+  }
+
+  /**
+   * Handle test failures
+   * @param {Object} params - Test failure parameters
+   * @param {Object} params.testResults - Jest test results object
+   * @param {string} params.message - Custom message
+   * @returns {Object} Failure response object
+   */
+  testFailure(params = {}) {
+    const {
+      testResults,
+      message
+    } = params;
+    if (!testResults) {
+      return this.failure({
+        errorCode: 'TEST_FAILURE',
+        errorCategory: ERROR_CATEGORIES.CODE,
+        errorMessage: message || 'Tests failed'
+      });
+    }
+    const errors = [];
+    const failedTests = testResults.testResults || [];
+    for (const testFile of failedTests) {
+      if (testFile.numFailingTests > 0) {
+        for (const assertion of testFile.assertionResults || []) {
+          if (assertion.status === 'failed') {
+            errors.push({
+              test: assertion.fullName || assertion.title,
+              file: testFile.name,
+              message: assertion.failureMessages?.[0] || 'Test assertion failed'
+            });
+          }
+        }
+      }
+    }
+    return this.failure({
+      message: message || `${testResults.numFailedTests} test(s) failed out of ${testResults.numTotalTests}`,
+      errorCode: 'TEST_FAILURE',
+      errorCategory: ERROR_CATEGORIES.CODE,
+      errorMessage: `${testResults.numFailedTests} test assertion(s) failed`,
+      errors: errors.length > 0 ? errors : ['Test failures detected'],
+      result: [{
+        totalTests: testResults.numTotalTests,
+        failedTests: testResults.numFailedTests,
+        passedTests: testResults.numPassedTests,
+        skippedTests: testResults.numSkippedTests
+      }]
+    });
+  }
+
+  /**
+   * Handle tool execution errors
+   * @param {Object} params - Tool error parameters
+   * @param {string} params.toolName - Name of the tool (jest, npm, etc.)
+   * @param {Error|string} params.error - Error object or message
+   * @param {string} params.exitCode - Exit code from tool
+   * @returns {Object} Failure response object
+   */
+  toolError(params = {}) {
+    const {
+      toolName = 'unknown',
+      error,
+      exitCode
+    } = params;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorStack = error instanceof Error ? error.stack : null;
+    const errors = [{
+      tool: toolName,
+      message: errorMessage,
+      exitCode: exitCode || 'unknown'
+    }];
+    if (errorStack) {
+      errors[0].stack = errorStack;
+    }
+    return this.failure({
+      message: `${toolName} execution failed`,
+      errorCode: `${toolName.toUpperCase()}_EXECUTION_ERROR`,
+      errorCategory: ERROR_CATEGORIES.TOOL,
+      errorMessage: `Failed to execute ${toolName}: ${errorMessage}`,
+      errors
+    });
+  }
+
+  /**
+   * Handle environment errors
+   * @param {Object} params - Environment error parameters
+   * @param {string} params.issue - Description of the environment issue
+   * @param {string} params.requirement - What was required
+   * @param {string} params.suggestion - Suggested fix
+   * @returns {Object} Failure response object
+   */
+  environmentError(params = {}) {
+    const {
+      issue = 'Environment configuration issue',
+      requirement = null,
+      suggestion = null
+    } = params;
+    const errors = [{
+      issue,
+      ...(requirement && {
+        requirement
+      }),
+      ...(suggestion && {
+        suggestion
+      })
+    }];
+    return this.failure({
+      message: 'Environment setup failed',
+      errorCode: 'ENV_SETUP_ERROR',
+      errorCategory: ERROR_CATEGORIES.ENVIRONMENT,
+      errorMessage: issue,
+      errors
+    });
+  }
+
+  /**
+   * Handle flaky test failures
+   * @param {Object} params - Flaky test parameters
+   * @param {Array} params.testNames - Names of flaky tests
+   * @param {number} params.attemptNumber - Current attempt number
+   * @param {number} params.maxAttempts - Max retry attempts
+   * @returns {Object} Failure response object
+   */
+  flakyTestFailure(params = {}) {
+    const {
+      testNames = [],
+      attemptNumber = 1,
+      maxAttempts = 3,
+      message
+    } = params;
+    return this.failure({
+      message: message || `Flaky test failure (attempt ${attemptNumber}/${maxAttempts})`,
+      errorCode: 'FLAKY_TEST_FAILURE',
+      errorCategory: ERROR_CATEGORIES.FLAKY,
+      errorMessage: `${testNames.length} test(s) failed intermittently`,
+      errors: testNames.map(name => ({
+        test: name,
+        type: 'flaky',
+        attemptNumber
+      })),
+      result: [{
+        attemptNumber,
+        maxAttempts,
+        flakyTestCount: testNames.length
+      }]
+    });
+  }
+
+  /**
+   * Save response to JSON file
+   * @param {Object} response - Response object to save
+   * @param {string} outputPath - Optional path override
+   * @returns {boolean} Success status
+   */
+  saveToFile(response, outputPath = null) {
+    const filePath = outputPath || this.outputPath;
+    if (!filePath) {
+      _logger.Logger.warn('No output path specified for pipeline summary');
+      return false;
+    }
+    try {
+      const dir = _path.default.dirname(filePath);
+
+      // ── Create directory if it doesn't exist ──────────────────────
+      if (!_fs.default.existsSync(dir)) {
+        try {
+          _fs.default.mkdirSync(dir, {
+            recursive: true
+          });
+          _logger.Logger.info(`Created directory: ${dir}`);
+        } catch (mkdirErr) {
+          if (mkdirErr.code === 'EACCES') {
+            _logger.Logger.error(`Permission denied creating directory: ${dir}. ` + `Check folder permissions.`);
+          } else if (mkdirErr.code === 'EROFS') {
+            _logger.Logger.error(`Read-only file system: ${dir}. ` + `Cannot create directory on read-only filesystem.`);
+          } else {
+            _logger.Logger.error(`Failed to create directory ${dir}: ${mkdirErr.message}`);
+          }
+          return false;
+        }
+      }
+
+      // ── Verify directory is writable ─────────────────────────────
+      try {
+        _fs.default.accessSync(dir, _fs.default.constants.W_OK);
+      } catch (accessErr) {
+        _logger.Logger.error(`Directory not writable: ${dir}. ` + `Check folder permissions.`);
+        return false;
+      }
+
+      // ── Write the summary file ───────────────────────────────────
+      const jsonContent = JSON.stringify(response, null, 2);
+      _fs.default.writeFileSync(filePath, jsonContent, 'utf-8');
+
+      // ── Verify file was written ──────────────────────────────────
+      if (!_fs.default.existsSync(filePath)) {
+        _logger.Logger.error(`File was not created: ${filePath}. ` + `Unknown file system error.`);
+        return false;
+      }
+      _logger.Logger.info(`✓ Pipeline summary saved to: ${filePath}`);
+      return true;
+    } catch (err) {
+      // ── Handle unexpected errors ─────────────────────────────────
+      if (err.code === 'ENOSPC') {
+        _logger.Logger.error(`No space left on device. ` + `Cannot save pipeline summary to: ${outputPath || this.outputPath}`);
+      } else if (err.code === 'ENOTDIR') {
+        _logger.Logger.error(`Invalid path: ${outputPath || this.outputPath}. ` + `A parent component is not a directory.`);
+      } else {
+        _logger.Logger.error(`Failed to save pipeline summary: ${err.message}. ` + `Path: ${outputPath || this.outputPath}`);
+      }
+      return false;
+    }
+  }
+
+  /**
+   * Save response and return both
+   * @param {Object} response - Response object
+   * @param {string} outputPath - Optional path override
+   * @returns {Object} { response, saved: boolean }
+   */
+  saveAndReturn(response, outputPath = null) {
+    const saved = this.saveToFile(response, outputPath);
+    return {
+      response,
+      saved
+    };
+  }
+
+  /**
+   * Validate error category
+   * @private
+   */
+  _isValidErrorCategory(category) {
+    return Object.values(ERROR_CATEGORIES).includes(category);
+  }
+
+  /**
+   * Log response for debugging
+   * @private
+   */
+  _logResponse(response) {
+    if (response.status === 'SUCCESS') {
+      _logger.Logger.info(`✓ Stage '${this.stageName}' completed: ${response.message}`);
+    } else {
+      _logger.Logger.error(`✗ Stage '${this.stageName}' failed: ${response.error.category} - ${response.error.code}`);
+    }
+  }
+}
+
+/**
+ * Factory function for quick usage
+ * @param {string} stageName - Name of the pipeline stage
+ * @param {Object} options - Additional options
+ * @returns {PipelineSummaryGenerator}
+ */
+exports.PipelineSummaryGenerator = PipelineSummaryGenerator;
+function createPipelineSummary(stageName, options = {}) {
+  return new PipelineSummaryGenerator({
+    stageName,
+    ...options
+  });
+}
+
+/**
+ * Export error categories for external use
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zohodesk/unit-testing-framework",
-  "version": "0.0.30-experimental",
+  "version": "0.0.31-experimental",
   "description": "A modular Jest-based unit testing framework",
   "main": "./build/index.js",
   "exports": {