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

package/README.md

@@ -2,6 +2,8 @@
 
 A modular, Jest-based unit testing framework designed to plug into existing CLI pipelines. Runs Jest **programmatically** via `@jest/core` (no shell execution), ships with sensible defaults, HTML report generation via `jest-html-reporter`, and automatic Jest globals injection.
 
+For a command-first onboarding guide (npm commands, flags, and config options), see [UNIT_TEST_TOOL_TRYOUT.md](UNIT_TEST_TOOL_TRYOUT.md).
+
 ---
 
 ## Folder Structure

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,10 +8,11 @@ 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) {
-  const files = testFiles.split(',').map(f => f.trim()).filter(Boolean);
+function resolveTestFiles(rawPattern, projectRoot) {
+  const files = rawPattern.split(',').map(f => f.trim()).filter(Boolean);
   const resolved = [];
   for (const file of files) {
     const abs = _path.default.resolve(projectRoot, file);
@@ -32,21 +33,140 @@ 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;
+    let resolvedPaths = null;
+    if (rawPattern) {
+      // Normalize: split on comma, resolve each to absolute, keep only files that exist.
+      resolvedPaths = resolveTestFiles(rawPattern, projectRoot);
+    }
 
-  // ── 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, {
+      // Pass explicit files to Jest positional args to avoid testMatch glob filtering.
+      testPathPattern: resolvedPaths,
+      watch,
+      projectRoot
+    });
+    const testResults = await (0, _runnerBase.executeJest)(argv, projectRoot);
 
-  // ── 3. Build argv & run Jest ──────────────────────────────────
-  const argv = (0, _runnerBase.buildArgv)(config, {
-    testMatch: pattern,
-    watch,
-    projectRoot
-  });
-  return (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/runner/runner-base.js

@@ -7,15 +7,15 @@ exports.buildArgv = buildArgv;
 exports.executeJest = executeJest;
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function buildArgv(config, {
-  testMatch,
+  testPathPattern,
   watch = false
 }) {
   const argv = {
     config: JSON.stringify(config),
     watch
   };
-  if (testMatch) {
-    argv.testMatch = testMatch;
+  if (testPathPattern && testPathPattern.length) {
+    argv._ = (argv._ || []).concat(testPathPattern);
   }
   return argv;
 }

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');
+    });
+  });
+});