@testream/mocha-reporter 1.0.0

package/dist/parallel-buffered.js

@@ -0,0 +1,165 @@
+/**
+ * "Buffered" reporter used internally by a worker process when running in parallel mode.
+ * @module nodejs/reporters/parallel-buffered
+ * @public
+ */
+
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+
+const {
+  EVENT_SUITE_BEGIN,
+  EVENT_SUITE_END,
+  EVENT_TEST_FAIL,
+  EVENT_TEST_PASS,
+  EVENT_TEST_PENDING,
+  EVENT_TEST_BEGIN,
+  EVENT_TEST_END,
+  EVENT_TEST_RETRY,
+  EVENT_DELAY_BEGIN,
+  EVENT_DELAY_END,
+  EVENT_HOOK_BEGIN,
+  EVENT_HOOK_END,
+  EVENT_RUN_END
+} = require('../../runner').constants;
+const {SerializableEvent, SerializableWorkerResult} = require('../serializer');
+const debug = require('debug')('mocha:reporters:buffered');
+const Base = require('../../reporters/base');
+
+/**
+ * List of events to listen to; these will be buffered and sent
+ * when `Mocha#run` is complete (via {@link ParallelBuffered#done}).
+ */
+const EVENT_NAMES = [
+  EVENT_SUITE_BEGIN,
+  EVENT_SUITE_END,
+  EVENT_TEST_BEGIN,
+  EVENT_TEST_PENDING,
+  EVENT_TEST_FAIL,
+  EVENT_TEST_PASS,
+  EVENT_TEST_RETRY,
+  EVENT_TEST_END,
+  EVENT_HOOK_BEGIN,
+  EVENT_HOOK_END
+];
+
+/**
+ * Like {@link EVENT_NAMES}, except we expect these events to only be emitted
+ * by the `Runner` once.
+ */
+const ONCE_EVENT_NAMES = [EVENT_DELAY_BEGIN, EVENT_DELAY_END];
+
+/**
+ * The `ParallelBuffered` reporter is used by each worker process in "parallel"
+ * mode, by default.  Instead of reporting to `STDOUT`, etc., it retains a
+ * list of events it receives and hands these off to the callback passed into
+ * {@link Mocha#run}. That callback will then return the data to the main
+ * process.
+ * @public
+ */
+class ParallelBuffered extends Base {
+  /**
+   * Calls {@link ParallelBuffered#createListeners}
+   * @param {Runner} runner
+   */
+  constructor(runner, opts) {
+    super(runner, opts);
+
+    /**
+     * Retained list of events emitted from the {@link Runner} instance.
+     * @type {BufferedEvent[]}
+     * @public
+     */
+    this.events = [];
+
+    /**
+     * Map of `Runner` event names to listeners (for later teardown)
+     * @public
+     * @type {Map<string,EventListener>}
+     */
+    this.listeners = new Map();
+
+    this.createListeners(runner);
+  }
+
+  /**
+   * Returns a new listener which saves event data in memory to
+   * {@link ParallelBuffered#events}. Listeners are indexed by `eventName` and stored
+   * in {@link ParallelBuffered#listeners}. This is a defensive measure, so that we
+   * don't a) leak memory or b) remove _other_ listeners that may not be
+   * associated with this reporter.
+   *
+   * Subclasses could override this behavior.
+   *
+   * @public
+   * @param {string} eventName - Name of event to create listener for
+   * @returns {EventListener}
+   */
+  createListener(eventName) {
+    const listener = (runnable, err) => {
+      this.events.push(SerializableEvent.create(eventName, runnable, err));
+    };
+    return this.listeners.set(eventName, listener).get(eventName);
+  }
+
+  /**
+   * Creates event listeners (using {@link ParallelBuffered#createListener}) for each
+   * reporter-relevant event emitted by a {@link Runner}. This array is drained when
+   * {@link ParallelBuffered#done} is called by {@link Runner#run}.
+   *
+   * Subclasses could override this behavior.
+   * @public
+   * @param {Runner} runner - Runner instance
+   * @returns {ParallelBuffered}
+   * @chainable
+   */
+  createListeners(runner) {
+    EVENT_NAMES.forEach(evt => {
+      runner.on(evt, this.createListener(evt));
+    });
+    ONCE_EVENT_NAMES.forEach(evt => {
+      runner.once(evt, this.createListener(evt));
+    });
+
+    runner.once(EVENT_RUN_END, () => {
+      debug('received EVENT_RUN_END');
+      this.listeners.forEach((listener, evt) => {
+        runner.removeListener(evt, listener);
+        this.listeners.delete(evt);
+      });
+    });
+
+    return this;
+  }
+
+  /**
+   * Calls the {@link Mocha#run} callback (`callback`) with the test failure
+   * count and the array of {@link BufferedEvent} objects. Resets the array.
+   *
+   * This is called directly by `Runner#run` and should not be called by any other consumer.
+   *
+   * Subclasses could override this.
+   *
+   * @param {number} failures - Number of failed tests
+   * @param {Function} callback - The callback passed to {@link Mocha#run}.
+   * @public
+   */
+  done(failures, callback) {
+    callback(SerializableWorkerResult.create(this.events, failures));
+    this.events = []; // defensive
+  }
+}
+
+/**
+ * Serializable event data from a `Runner`.  Keys of the `data` property
+ * beginning with `__` will be converted into a function which returns the value
+ * upon deserialization.
+ * @typedef {Object} BufferedEvent
+ * @property {string} name - Event name
+ * @property {object} data - Event parameters
+ */
+
+module.exports = ParallelBuffered;

package/dist/reporter.d.ts

@@ -0,0 +1,29 @@
+import * as Mocha from 'mocha';
+/**
+ * Testream Mocha Reporter
+ * Wraps mocha-ctrf-json-reporter to generate CTRF reports and upload them to Testream
+ */
+export declare class TestreamMochaReporter extends Mocha.reporters.Base {
+    private config;
+    private readonly outputDir;
+    private readonly outputFile;
+    constructor(runner: Mocha.Runner, options: Mocha.MochaOptions);
+    /**
+     * Mocha calls done(failures, fn) when a reporter defines it — Mocha will
+     * wait for fn() before exiting, giving us time to finish the async upload.
+     */
+    done(failures: number, fn?: (failures: number) => void): void;
+    /**
+     * Called when entire test run completes (after mocha-ctrf-json-reporter has written its file)
+     */
+    private handleRunEnd;
+    /**
+     * Read CTRF report from file
+     */
+    private readCTRFReport;
+    /**
+     * Upload report to Testream API
+     */
+    private uploadReport;
+}
+export default TestreamMochaReporter;

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Re-export CTRF types from shared-types package
+ */
+export type { CTRFReport, CTRFTest, CTRFSummary, CTRFResults, CTRFAttachment, CTRFStep, } from '@jira-test-manager/shared-types';
+/**
+ * Re-export API types from shared-types package
+ */
+export type { IngestResponse, ApiErrorResponse, UploadResult, CIContext, } from '@jira-test-manager/shared-types';
+/**
+ * Reporter Configuration Options
+ */
+export interface MochaReporterConfig {
+    /**
+     * API key for authentication
+     * @required
+     */
+    apiKey: string;
+    /**
+     * Git branch name (auto-detected from CI environment if not provided)
+     */
+    branch?: string;
+    /**
+     * Git commit SHA (auto-detected from CI environment if not provided)
+     */
+    commitSha?: string;
+    /**
+     * Git repository URL (auto-detected from CI environment if not provided)
+     */
+    repositoryUrl?: string;
+    /**
+     * Enable/disable automatic upload to backend
+     * @default true
+     */
+    uploadEnabled?: boolean;
+    /**
+     * Fail the process if upload fails
+     * @default false
+     */
+    failOnUploadError?: boolean;
+    /**
+     * Test type identifier (e.g., 'unit', 'integration', 'e2e')
+     */
+    testType?: string;
+    /**
+     * Application name under test
+     */
+    appName?: string;
+    /**
+     * Application version under test
+     */
+    appVersion?: string;
+    /**
+     * Build name/identifier
+     */
+    buildName?: string;
+    /**
+     * Build number
+     */
+    buildNumber?: string;
+    /**
+     * Build URL (CI pipeline URL)
+     */
+    buildUrl?: string;
+    /**
+     * Test environment (e.g., 'staging', 'production', 'ci')
+     */
+    testEnvironment?: string;
+}

package/dist/uploader.d.ts

@@ -0,0 +1,6 @@
+import { UploadResult } from './types';
+import { UploadTestRunOptions } from '@jira-test-manager/shared-types';
+/**
+ * Upload CTRF report to Testream API
+ */
+export declare function uploadToApi(options: UploadTestRunOptions): Promise<UploadResult>;

package/dist/worker.js

@@ -0,0 +1,151 @@
+/**
+ * A worker process.  Consumes {@link module:reporters/parallel-buffered} reporter.
+ * @module worker
+ * @private
+ */
+
+'use strict';
+
+const {
+  createInvalidArgumentTypeError,
+  createInvalidArgumentValueError
+} = require('../errors');
+const workerpool = require('workerpool');
+const Mocha = require('../mocha');
+const {handleRequires, validateLegacyPlugin} = require('../cli/run-helpers');
+const d = require('debug');
+const debug = d.debug(`mocha:parallel:worker:${process.pid}`);
+const isDebugEnabled = d.enabled(`mocha:parallel:worker:${process.pid}`);
+const {serialize} = require('./serializer');
+const {setInterval, clearInterval} = global;
+
+let rootHooks;
+
+if (workerpool.isMainThread) {
+  throw new Error(
+    'This script is intended to be run as a worker (by the `workerpool` package).'
+  );
+}
+
+/**
+ * Initializes some stuff on the first call to {@link run}.
+ *
+ * Handles `--require` and `--ui`.  Does _not_ handle `--reporter`,
+ * as only the `Buffered` reporter is used.
+ *
+ * **This function only runs once per worker**; it overwrites itself with a no-op
+ * before returning.
+ *
+ * @param {Options} argv - Command-line options
+ */
+let bootstrap = async argv => {
+  // globalSetup and globalTeardown do not run in workers
+  const plugins = await handleRequires(argv.require, {
+    ignoredPlugins: ['mochaGlobalSetup', 'mochaGlobalTeardown']
+  });
+  validateLegacyPlugin(argv, 'ui', Mocha.interfaces);
+
+  rootHooks = plugins.rootHooks;
+  bootstrap = () => {};
+  debug('bootstrap(): finished with args: %O', argv);
+};
+
+/**
+ * Runs a single test file in a worker thread.
+ * @param {string} filepath - Filepath of test file
+ * @param {string} [serializedOptions] - **Serialized** options. This string will be eval'd!
+ * @see https://npm.im/serialize-javascript
+ * @returns {Promise<{failures: number, events: BufferedEvent[]}>} - Test
+ * failure count and list of events.
+ */
+async function run(filepath, serializedOptions = '{}') {
+  if (!filepath) {
+    throw createInvalidArgumentTypeError(
+      'Expected a non-empty "filepath" argument',
+      'file',
+      'string'
+    );
+  }
+
+  debug('run(): running test file %s', filepath);
+
+  if (typeof serializedOptions !== 'string') {
+    throw createInvalidArgumentTypeError(
+      'run() expects second parameter to be a string which was serialized by the `serialize-javascript` module',
+      'serializedOptions',
+      'string'
+    );
+  }
+  let argv;
+  try {
+    // eslint-disable-next-line no-eval
+    argv = eval('(' + serializedOptions + ')');
+  } catch (err) {
+    throw createInvalidArgumentValueError(
+      'run() was unable to deserialize the options',
+      'serializedOptions',
+      serializedOptions
+    );
+  }
+
+  const opts = Object.assign({ui: 'bdd'}, argv, {
+    // if this was true, it would cause infinite recursion.
+    parallel: false,
+    // this doesn't work in parallel mode
+    forbidOnly: true,
+    // it's useful for a Mocha instance to know if it's running in a worker process.
+    isWorker: true
+  });
+
+  await bootstrap(opts);
+
+  opts.rootHooks = rootHooks;
+
+  const mocha = new Mocha(opts).addFile(filepath);
+
+  try {
+    await mocha.loadFilesAsync();
+  } catch (err) {
+    debug('run(): could not load file %s: %s', filepath, err);
+    throw err;
+  }
+
+  return new Promise((resolve, reject) => {
+    let debugInterval;
+    /* istanbul ignore next */
+    if (isDebugEnabled) {
+      debugInterval = setInterval(() => {
+        debug('run(): still running %s...', filepath);
+      }, 5000).unref();
+    }
+    mocha.run(result => {
+      // Runner adds these; if we don't remove them, we'll get a leak.
+      process.removeAllListeners('uncaughtException');
+      process.removeAllListeners('unhandledRejection');
+
+      try {
+        const serialized = serialize(result);
+        debug(
+          'run(): completed run with %d test failures; returning to main process',
+          typeof result.failures === 'number' ? result.failures : 0
+        );
+        resolve(serialized);
+      } catch (err) {
+        // TODO: figure out exactly what the sad path looks like here.
+        // rejection should only happen if an error is "unrecoverable"
+        debug('run(): serialization failed; rejecting: %O', err);
+        reject(err);
+      } finally {
+        clearInterval(debugInterval);
+      }
+    });
+  });
+}
+
+// this registers the `run` function.
+workerpool.worker({run});
+
+debug('started worker process');
+
+// for testing
+exports.run = run;

package/dist/worker1.js

@@ -0,0 +1,263 @@
+/**
+ * worker must be started as a child process or a web worker.
+ * It listens for RPC messages from the parent process.
+ */
+var Transfer = require('./transfer');
+
+// source of inspiration: https://github.com/sindresorhus/require-fool-webpack
+var requireFoolWebpack = eval(
+    'typeof require !== \'undefined\'' +
+    ' ? require' +
+    ' : function (module) { throw new Error(\'Module " + module + " not found.\') }'
+);
+
+/**
+ * Special message sent by parent which causes the worker to terminate itself.
+ * Not a "message object"; this string is the entire message.
+ */
+var TERMINATE_METHOD_ID = '__workerpool-terminate__';
+
+// var nodeOSPlatform = require('./environment').nodeOSPlatform;
+
+// create a worker API for sending and receiving messages which works both on
+// node.js and in the browser
+var worker = {
+  exit: function() {}
+};
+if (typeof self !== 'undefined' && typeof postMessage === 'function' && typeof addEventListener === 'function') {
+  // worker in the browser
+  worker.on = function (event, callback) {
+    addEventListener(event, function (message) {
+      callback(message.data);
+    })
+  };
+  worker.send = function (message) {
+    postMessage(message);
+  };
+}
+else if (typeof process !== 'undefined') {
+  // node.js
+
+  var WorkerThreads;
+  try {
+    WorkerThreads = requireFoolWebpack('worker_threads');
+  } catch(error) {
+    if (typeof error === 'object' && error !== null && error.code === 'MODULE_NOT_FOUND') {
+      // no worker_threads, fallback to sub-process based workers
+    } else {
+      throw error;
+    }
+  }
+
+  if (WorkerThreads &&
+    /* if there is a parentPort, we are in a WorkerThread */
+    WorkerThreads.parentPort !== null) {
+    var parentPort  = WorkerThreads.parentPort;
+    worker.send = parentPort.postMessage.bind(parentPort);
+    worker.on = parentPort.on.bind(parentPort);
+    worker.exit = process.exit.bind(process);
+  } else {
+    worker.on = process.on.bind(process);
+    // ignore transfer argument since it is not supported by process
+    worker.send = function (message) {
+      process.send(message);
+    };
+    // register disconnect handler only for subprocess worker to exit when parent is killed unexpectedly
+    worker.on('disconnect', function () {
+      process.exit(1);
+    });
+    worker.exit = process.exit.bind(process);
+  }
+}
+else {
+  throw new Error('Script must be executed as a worker');
+}
+
+function convertError(error) {
+  return Object.getOwnPropertyNames(error).reduce(function(product, name) {
+    return Object.defineProperty(product, name, {
+	value: error[name],
+	enumerable: true
+    });
+  }, {});
+}
+
+/**
+ * Test whether a value is a Promise via duck typing.
+ * @param {*} value
+ * @returns {boolean} Returns true when given value is an object
+ *                    having functions `then` and `catch`.
+ */
+function isPromise(value) {
+  return value && (typeof value.then === 'function') && (typeof value.catch === 'function');
+}
+
+// functions available externally
+worker.methods = {};
+
+/**
+ * Execute a function with provided arguments
+ * @param {String} fn     Stringified function
+ * @param {Array} [args]  Function arguments
+ * @returns {*}
+ */
+worker.methods.run = function run(fn, args) {
+  var f = new Function('return (' + fn + ').apply(null, arguments);');
+  return f.apply(f, args);
+};
+
+/**
+ * Get a list with methods available on this worker
+ * @return {String[]} methods
+ */
+worker.methods.methods = function methods() {
+  return Object.keys(worker.methods);
+};
+
+/**
+ * Custom handler for when the worker is terminated.
+ */
+worker.terminationHandler = undefined;
+
+/**
+ * Cleanup and exit the worker.
+ * @param {Number} code 
+ * @returns 
+ */
+worker.cleanupAndExit = function(code) {
+  var _exit = function() {
+    worker.exit(code);
+  }
+
+  if(!worker.terminationHandler) {
+    return _exit();
+  }
+
+  var result = worker.terminationHandler(code);
+  if (isPromise(result)) {
+    result.then(_exit, _exit);
+  } else {
+    _exit();
+  }
+}
+
+var currentRequestId = null;
+
+worker.on('message', function (request) {
+  if (request === TERMINATE_METHOD_ID) {
+    return worker.cleanupAndExit(0);
+  }
+  try {
+    var method = worker.methods[request.method];
+
+    if (method) {
+      currentRequestId = request.id;
+      
+      // execute the function
+      var result = method.apply(method, request.params);
+
+      if (isPromise(result)) {
+        // promise returned, resolve this and then return
+        result
+            .then(function (result) {
+              if (result instanceof Transfer) {
+                worker.send({
+                  id: request.id,
+                  result: result.message,
+                  error: null
+                }, result.transfer);
+              } else {
+                worker.send({
+                  id: request.id,
+                  result: result,
+                  error: null
+                });
+              }
+              currentRequestId = null;
+            })
+            .catch(function (err) {
+              worker.send({
+                id: request.id,
+                result: null,
+                error: convertError(err)
+              });
+              currentRequestId = null;
+            });
+      }
+      else {
+        // immediate result
+        if (result instanceof Transfer) {
+          worker.send({
+            id: request.id,
+            result: result.message,
+            error: null
+          }, result.transfer);
+        } else {
+          worker.send({
+            id: request.id,
+            result: result,
+            error: null
+          });
+        }
+
+        currentRequestId = null;
+      }
+    }
+    else {
+      throw new Error('Unknown method "' + request.method + '"');
+    }
+  }
+  catch (err) {
+    worker.send({
+      id: request.id,
+      result: null,
+      error: convertError(err)
+    });
+  }
+});
+
+/**
+ * Register methods to the worker
+ * @param {Object} [methods]
+ * @param {WorkerRegisterOptions} [options]
+ */
+worker.register = function (methods, options) {
+
+  if (methods) {
+    for (var name in methods) {
+      if (methods.hasOwnProperty(name)) {
+        worker.methods[name] = methods[name];
+      }
+    }
+  }
+
+  if (options) {
+    worker.terminationHandler = options.onTerminate;
+  }
+
+  worker.send('ready');
+};
+
+worker.emit = function (payload) {
+  if (currentRequestId) {
+    if (payload instanceof Transfer) {
+      worker.send({
+        id: currentRequestId,
+        isEvent: true,
+        payload: payload.message
+      }, payload.transfer);
+      return;
+    }
+
+    worker.send({
+      id: currentRequestId,
+      isEvent: true,
+      payload
+    });
+  }
+};
+
+if (typeof exports !== 'undefined') {
+  exports.add = worker.register;
+  exports.emit = worker.emit;
+}