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

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.32-experimental",
   "description": "A modular Jest-based unit testing framework",
   "main": "./build/index.js",
   "exports": {