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

package/README.md

@@ -17,6 +17,10 @@ unit-testing-framework/
 │   ├── runner/
 │   │   ├── jest-runner.js              # createJestRunner() – main orchestrator
 │   │   └── runner-base.js              # buildArgv() & executeJest() via @jest/core
+│   ├── cli/
+│   │   ├── bin.js                      # zd-unit-test executable (shebang)
+│   │   ├── run.js                      # runUnitTestCli() – parse argv + run
+│   │   └── parse-args.js              # parseUnitTestArgs() – Jest argv parsing
 │   ├── config/
 │   │   └── default-config.js           # getDefaultConfig() – framework defaults
 │   ├── environment/
@@ -39,6 +43,26 @@ npm install @zohodesk/unit-testing-framework
 
 All Jest dependencies (`@jest/core`, `jest-environment-jsdom`, `babel-jest`) are bundled — consumers don't need to install Jest separately.
 
+Installing the package also provides the `zd-unit-test` CLI command.
+
+---
+
+## CLI
+
+```bash
+# Full suite
+npx zd-unit-test
+
+# A file, a directory, or related tests — plus any Jest flag
+npx zd-unit-test src/foo/Bar.test.js -u
+npx zd-unit-test src/foo/__tests__ --coverage
+npx zd-unit-test --findRelatedTests src/foo/Bar.js
+```
+
+CLI references:
+- [docs/UNIT_TEST_CLI.md](./docs/UNIT_TEST_CLI.md) — standalone `zd-unit-test` command (commands, flags, exit codes, output files).
+- [docs/UNIT_TEST_VIA_TESTING_FRAMEWORK.md](./docs/UNIT_TEST_VIA_TESTING_FRAMEWORK.md) — running unit tests through `ZDTestingFramework test-ut`.
+
 ---
 
 ## Quick Start
@@ -66,6 +90,12 @@ Enable watch mode:
 await createJestRunner({ watch: true });
 ```
 
+Update snapshots (Jest `-u` / `--updateSnapshot`):
+
+```js
+await createJestRunner({ updateSnapshot: true });
+```
+
 ---
 
 ## API
@@ -77,9 +107,16 @@ await createJestRunner({ watch: true });
 | `projectRoot` | `string` | `process.cwd()` | Consumer project root directory |
 | `testPathPattern` | `string` | — | Filter tests by file path pattern |
 | `watch` | `boolean` | `false` | Enable Jest watch mode |
+| ...any Jest CLI option | — | — | All remaining options are forwarded to Jest's `runCLI` as camelCase CLI options, e.g. `updateSnapshot`, `coverage`, `bail`, `testNamePattern`, `runInBand`, `ci`, `verbose`, `maxWorkers` |
+
+> Note: `config` cannot be overridden via pass-through — it is managed by the framework (use `configPath` / `ut.config.*` instead).
+
+> Fail fast: if `testFiles`/`testPathPattern` resolves to no existing files, the runner throws `No test files matched pattern: <pattern>` (surfaced as `JEST_EXECUTION_ERROR` in the summary) instead of silently running the full suite.
 
 Returns: `Promise<AggregatedResult>` — Jest's aggregated results object.
 
+See [docs/UNIT_TEST_CLI.md](./docs/UNIT_TEST_CLI.md) for the `ZDTestingFramework unit-test` CLI commands and usage.
+
 ---
 
 ## Default Configuration

package/build/index.js

@@ -9,5 +9,19 @@ Object.defineProperty(exports, "createJestRunner", {
     return _jestRunner.default;
   }
 });
+Object.defineProperty(exports, "parseUnitTestArgs", {
+  enumerable: true,
+  get: function () {
+    return _parseArgs.parseUnitTestArgs;
+  }
+});
+Object.defineProperty(exports, "runUnitTestCli", {
+  enumerable: true,
+  get: function () {
+    return _run.runUnitTestCli;
+  }
+});
 var _jestRunner = _interopRequireDefault(require("./src/runner/jest-runner.js"));
+var _run = require("./src/cli/run.js");
+var _parseArgs = require("./src/cli/parse-args.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/build/src/cli/__tests__/parse-args.test.js

@@ -0,0 +1,45 @@
+"use strict";
+
+var _parseArgs = require("../parse-args.js");
+describe('parseUnitTestArgs', () => {
+  test('returns empty options for no args (full suite)', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)([]);
+    expect(options.testPathPattern).toBeUndefined();
+    expect(options.configPath).toBeUndefined();
+  });
+  test('expands -u alias to updateSnapshot and drops the short alias', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['-u']);
+    expect(options.updateSnapshot).toBe(true);
+    expect(options.u).toBeUndefined();
+  });
+  test('treats a single positional as testPathPattern', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['src/foo/Bar.test.js']);
+    expect(options.testPathPattern).toBe('src/foo/Bar.test.js');
+  });
+  test('joins multiple positionals with commas', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['src/a.test.js', 'src/b.test.js']);
+    expect(options.testPathPattern).toBe('src/a.test.js,src/b.test.js');
+  });
+  test('maps --config to configPath (not config)', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['--config', './ut.config.js']);
+    expect(options.configPath).toBe('./ut.config.js');
+    expect(options.config).toBeUndefined();
+  });
+  test('drops a leading unit-test subcommand token', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['unit-test', 'src/a.test.js', '-u']);
+    expect(options.testPathPattern).toBe('src/a.test.js');
+    expect(options.updateSnapshot).toBe(true);
+  });
+  test('forwards arbitrary Jest flags as camelCase options', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['--coverage', '-t', 'login', '--runInBand']);
+    expect(options.coverage).toBe(true);
+    expect(options.testNamePattern).toBe('login');
+    expect(options.runInBand).toBe(true);
+  });
+  test('combines paths and flags', async () => {
+    const options = await (0, _parseArgs.parseUnitTestArgs)(['src/foo/Bar.test.js', '-u', '-t', 'edge cases']);
+    expect(options.testPathPattern).toBe('src/foo/Bar.test.js');
+    expect(options.updateSnapshot).toBe(true);
+    expect(options.testNamePattern).toBe('edge cases');
+  });
+});

package/build/src/cli/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+"use strict";
+
+var _run = require("./run.js");
+(0, _run.runUnitTestCli)(process.argv.slice(2)).then(result => {
+  process.exitCode = result && result.success ? 0 : 1;
+}).catch(error => {
+  const message = error && error.stack ? error.stack : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+});

package/build/src/cli/parse-args.js

@@ -0,0 +1,56 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parseUnitTestArgs = parseUnitTestArgs;
+var _jestCli = require("jest-cli");
+// Short alias names from Jest's own option table (e.g. 'u', 't', 'c').
+// buildArgv emits both the alias and the canonical camelCase name; we keep
+// only the canonical one so the options object forwarded to the runner is clean.
+const SHORT_ALIASES = new Set();
+for (const def of Object.values(_jestCli.yargsOptions)) {
+  const alias = def && def.alias;
+  if (!alias) continue;
+  (Array.isArray(alias) ? alias : [alias]).forEach(name => SHORT_ALIASES.add(name));
+}
+
+/**
+ * Parse raw CLI argv into options for `createJestRunner`.
+ *
+ * Uses Jest's own argv parser (`jest-cli`), so every Jest flag is supported
+ * with full fidelity and the parsing stays in sync when Jest is upgraded —
+ * there is no hand-maintained flag list.
+ *
+ * - A leading `unit-test` subcommand token is dropped if present.
+ * - Positional args (files / directories) become `testPathPattern`.
+ * - `--config <file>` maps to the runner's own `configPath` param.
+ * - All other flags pass through as camelCase Jest CLI options.
+ *
+ * @param {string[]} rawArgv - argv after `node <script>` (e.g. process.argv.slice(2)).
+ * @returns {Promise<Object>} options object for createJestRunner.
+ */
+async function parseUnitTestArgs(rawArgv = []) {
+  const args = rawArgv[0] === 'unit-test' ? rawArgv.slice(1) : rawArgv;
+  const argv = await (0, _jestCli.buildArgv)(args);
+  const {
+    _: positionals = [],
+    $0,
+    config,
+    ...rest
+  } = argv;
+  const options = {};
+  for (const [key, value] of Object.entries(rest)) {
+    if (value === undefined) continue; // unset flags
+    if (SHORT_ALIASES.has(key)) continue; // drop short-alias duplicates
+    options[key] = value;
+  }
+  if (config) {
+    // Jest `--config <file>` is a config file path → runner's configPath.
+    options.configPath = config;
+  }
+  if (positionals.length) {
+    options.testPathPattern = positionals.join(',');
+  }
+  return options;
+}

package/build/src/cli/run.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runUnitTestCli = runUnitTestCli;
+var _jestRunner = _interopRequireDefault(require("../runner/jest-runner.js"));
+var _parseArgs = require("./parse-args.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Run the unit-test CLI: parse argv, then delegate to createJestRunner.
+ *
+ * @param {string[]} rawArgv - argv after `node <script>` (e.g. process.argv.slice(2)).
+ * @returns {Promise<{ testResults, summary, success }>} runner result.
+ */
+async function runUnitTestCli(rawArgv = []) {
+  const options = await (0, _parseArgs.parseUnitTestArgs)(rawArgv);
+  return (0, _jestRunner.default)(options);
+}

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

@@ -4,10 +4,10 @@ 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__');
+// Tests are transpiled to CommonJS (babel `modules: "commonjs"`), so
+// __dirname is available directly; import.meta would be a syntax error.
+const TEST_OUTPUT_DIR = _path.default.join(__dirname, '../../__temp__');
 describe('createJestRunner with Pipeline Summary', () => {
   let tempDir;
   beforeEach(() => {
@@ -83,6 +83,21 @@ describe('createJestRunner with Pipeline Summary', () => {
     const content = JSON.parse(_fs.default.readFileSync(summaryPath, 'utf-8'));
     expect(content.status).toBe('FAILURE');
   });
+  test('should fail fast when pattern matches no files (not run full suite)', async () => {
+    const summaryPath = _path.default.join(tempDir, 'no-match-summary.json');
+    const result = await (0, _jestRunner.default)({
+      projectRoot: process.cwd(),
+      summaryPath,
+      testFiles: 'totally-bogus-path.test.js'
+    });
+
+    // Must not fall through to running the full suite.
+    expect(result.success).toBe(false);
+    expect(result.testResults).toBeNull();
+    expect(result.summary.status).toBe('FAILURE');
+    expect(result.summary.error.code).toBe('JEST_EXECUTION_ERROR');
+    expect(result.summary.error.message).toContain('No test files matched pattern: totally-bogus-path.test.js');
+  });
   test('should use default summary path if not provided', async () => {
     const result = await (0, _jestRunner.default)({
       projectRoot: process.cwd(),

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

@@ -0,0 +1,53 @@
+"use strict";
+
+var _runnerBase = require("../runner-base.js");
+describe('buildArgv', () => {
+  const config = {
+    testEnvironment: 'jsdom'
+  };
+  test('should include serialized config and watch flag', () => {
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      watch: true
+    });
+    expect(argv.config).toBe(JSON.stringify(config));
+    expect(argv.watch).toBe(true);
+  });
+  test('should append test paths to positional args', () => {
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      testPathPattern: ['/abs/path/a.test.js', '/abs/path/b.test.js']
+    });
+    expect(argv._).toEqual(['/abs/path/a.test.js', '/abs/path/b.test.js']);
+  });
+  test('should forward updateSnapshot to Jest argv', () => {
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      jestOptions: {
+        updateSnapshot: true
+      }
+    });
+    expect(argv.updateSnapshot).toBe(true);
+  });
+  test('should forward arbitrary Jest CLI options', () => {
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      jestOptions: {
+        coverage: true,
+        bail: 1,
+        testNamePattern: 'login',
+        runInBand: true,
+        ci: true
+      }
+    });
+    expect(argv.coverage).toBe(true);
+    expect(argv.bail).toBe(1);
+    expect(argv.testNamePattern).toBe('login');
+    expect(argv.runInBand).toBe(true);
+    expect(argv.ci).toBe(true);
+  });
+  test('should not allow jestOptions to override framework-managed config', () => {
+    const argv = (0, _runnerBase.buildArgv)(config, {
+      jestOptions: {
+        config: 'malicious.json'
+      }
+    });
+    expect(argv.config).toBe(JSON.stringify(config));
+  });
+});

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

@@ -35,7 +35,10 @@ async function createJestRunner(options = {}) {
     configPath,
     watch = false,
     summaryPath = _path.default.join(projectRoot, 'test-slices', 'unit-test', 'unit_reports', 'ut-test-summary.json'),
-    webUrl = process.env.CI_BUILD_URL || ''
+    webUrl = process.env.CI_BUILD_URL || '',
+    // Any remaining options are forwarded to Jest as CLI options
+    // (e.g. updateSnapshot, coverage, bail, testNamePattern, runInBand).
+    ...jestOptions
   } = options;
 
   // ── 0. Setup pipeline summary (mandatory) ──────────────────────
@@ -54,14 +57,31 @@ async function createJestRunner(options = {}) {
     if (rawPattern) {
       // Normalize: split on comma, resolve each to absolute, keep only files that exist.
       resolvedPaths = resolveTestFiles(rawPattern, projectRoot);
+      if (!resolvedPaths) {
+        // Fail fast: a pattern that matches nothing must not silently
+        // fall through to running the full suite. The throw surfaces
+        // through the catch below as JEST_EXECUTION_ERROR in the summary.
+        throw new Error(`No test files matched pattern: ${rawPattern}`);
+      }
     }
 
+    // ── Workaround: force HTML report output path ────────────────
+    // Overrides any reporters from resolved config so the pipeline
+    // always finds the report at a fixed location.
+    config.reporters = ['default', ['jest-html-reporter', {
+      outputPath: _path.default.join(projectRoot, 'test-slices', 'unit-test', 'unit_reports', 'ut-test-report.html'),
+      pageTitle: 'Unit Test Report',
+      includeFailureMsg: true,
+      includeSuiteFailure: true,
+      theme: 'darkTheme'
+    }]];
+
     // ── 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
+      jestOptions
     });
     const testResults = await (0, _runnerBase.executeJest)(argv, projectRoot);
 

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

@@ -8,9 +8,12 @@ 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, {
   testPathPattern,
-  watch = false
+  watch = false,
+  jestOptions = {}
 }) {
   const argv = {
+    // Pass through any Jest CLI option (updateSnapshot, coverage, bail, testNamePattern, ...).
+    ...jestOptions,
     config: JSON.stringify(config),
     watch
   };

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

@@ -2,11 +2,9 @@
 
 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');
+const TEST_ROOT = _path.default.join(__dirname, '../../__temp__/dir-tests');
 describe('Pipeline Summary - Directory Creation Edge Cases', () => {
   afterEach(() => {
     // Cleanup

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

@@ -2,11 +2,11 @@
 
 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__');
+// Own isolated subdir — suites run in parallel and each cleans up its own
+// directory; never the shared __temp__ root, or it races with sibling suites.
+const TEST_OUTPUT_DIR = _path.default.join(__dirname, '../../__temp__/pipeline-summary');
 describe('PipelineSummaryGenerator', () => {
   let summary;
   beforeEach(() => {

package/build/src/utils/logger.js

@@ -8,6 +8,7 @@ const COLORS = {
   success: '\x1b[36m',
   failure: '\x1b[31m',
   info: '\x1b[33m',
+  warn: '\x1b[33m',
   reset: '\x1b[0m'
 };
 
@@ -24,6 +25,9 @@ const Logger = exports.Logger = {
   info(message) {
     consoleLogger.log(`${COLORS.info}${message}${COLORS.reset}`);
   },
+  warn(message) {
+    consoleLogger.warn(`${COLORS.warn}${message}${COLORS.reset}`);
+  },
   success(message) {
     consoleLogger.log(`${COLORS.success}${message}${COLORS.reset}`);
   }

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

@@ -71,8 +71,10 @@ class PipelineSummaryGenerator {
       errors = [],
       result = []
     } = params;
-    if (!this._isValidErrorCategory(errorCategory)) {
-      _logger.Logger.warn(`Invalid error category: ${errorCategory}. Using 'tool' as default.`);
+    let category = errorCategory;
+    if (!this._isValidErrorCategory(category)) {
+      _logger.Logger.warn(`Invalid error category: ${category}. Using 'tool' as default.`);
+      category = ERROR_CATEGORIES.TOOL;
     }
     const response = {
       status: 'FAILURE',
@@ -80,7 +82,7 @@ class PipelineSummaryGenerator {
       web_url: this.webUrl || '',
       error: {
         code: errorCode,
-        category: errorCategory,
+        category,
         message: errorMessage,
         errors: Array.isArray(errors) ? errors : [errors]
       }
@@ -155,7 +157,14 @@ class PipelineSummaryGenerator {
       error,
       exitCode
     } = params;
-    const errorMessage = error instanceof Error ? error.message : String(error);
+    let errorMessage;
+    if (error instanceof Error) {
+      errorMessage = error.message;
+    } else if (error === undefined || error === null) {
+      errorMessage = '';
+    } else {
+      errorMessage = String(error);
+    }
     const errorStack = error instanceof Error ? error.stack : null;
     const errors = [{
       tool: toolName,

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@zohodesk/unit-testing-framework",
-  "version": "0.0.32-experimental",
+  "version": "0.0.35-experimental",
   "description": "A modular Jest-based unit testing framework",
   "main": "./build/index.js",
   "exports": {
     ".": "./build/index.js"
   },
+  "bin": {
+    "zd-unit-test": "./build/src/cli/bin.js"
+  },
   "files": [
     "build/"
   ],
@@ -23,13 +26,26 @@
     "@babel/preset-env": "7.29.0",
     "@jest/core": "30.2.0",
     "@jest/types": "30.2.0",
+    "@testing-library/react": "12.1.5",
+    "@types/jest": "29.5.12",
+    "@types/react": "16.14.70",
+    "@types/react-dom": "16.9.25",
     "babel-jest": "30.2.0",
+    "identity-obj-proxy": "3.0.0",
     "jest-environment-jsdom": "30.2.0",
+    "jest-transform-stub": "2.0.0",
     "jest-html-reporter": "4.3.0",
+    "jest-cli": "30.2.0",
     "jest": "30.2.0"
   },
   "devDependencies": {
     "@babel/cli": "7.28.6",
     "@babel/plugin-transform-modules-commonjs": "7.28.6"
+  },
+  "jest": {
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "/build/"
+    ]
   }
 }