Mocha Common Test Report Format (CTRF) JSON Reporter

Common errors

• Error: Cannot find module 'mocha-ctrf-json-reporter'

  cause The reporter package has not been installed or is not accessible in the current execution environment.
  fix Run `npm install --save-dev mocha-ctrf-json-reporter` to install the package as a development dependency.

• Report file 'ctrf-report.json' not found in 'ctrf/' directory.

  cause Mocha tests might not have executed successfully, the reporter encountered an error, or the `outputDir` and `outputFile` configuration was incorrect, leading the report to be generated elsewhere or not at all.
  fix Verify that your Mocha tests are running and passing. Double-check the `reporterOptions` in your `.mocharc.js` or command-line arguments for correct `outputDir` and `outputFile` settings. Also, ensure the specified output directory exists or can be created by the reporter.

• Mocha exited with error code 1 without generating a report.

  cause This typically indicates that tests failed, or Mocha itself encountered a critical error before the reporter could finalize and write the report. The reporter will only write a report if the test run completes, even with failures.
  fix Examine Mocha's console output for specific test failures or critical errors. Address any failing tests or configuration issues. Ensure Mocha is configured to run at least one test; an empty test run might not produce a report.

Warnings

• gotcha Reporter options are typically defined in `.mocharc.js`, `.mocharc.json`, or via CLI arguments. Programmatic configuration of Mocha reporters with specific `reporterOptions` can sometimes be less intuitive or require direct instantiation of the reporter class, which is not the primary use case for this package.
  Fix: Prefer using `.mocharc.js` or `.mocharc.json` for reporter configuration. For dynamic options, leverage environment variables within `.mocharc.js` and use nullish coalescing (e.g., `process.env.VAR ?? 'default'`) for robustness.
• gotcha The default output file location is `ctrf/ctrf-report.json`. If not explicitly configured, multiple test runs or CI/CD pipelines might overwrite previous reports. Furthermore, ensure the output directory is accessible for writing.
  Fix: Always specify `outputDir` and `outputFile` in `reporterOptions` to control where reports are saved. Consider using dynamic filenames (e.g., with timestamps or build numbers) to prevent overwrites, potentially utilizing the `[hash]` token if supported by the underlying Mocha version and reporter configuration.
• gotcha The Common Test Report Format (CTRF) is an evolving open standard. While this reporter aims for compliance with the latest specification, users consuming CTRF reports in other tools should ensure all components (reporter, consuming tools) are compatible with the specific CTRF version being generated to avoid parsing errors or data interpretation mismatches.
  Fix: Monitor the CTRF specification repository (github.com/ctrf-io/ctrf) for updates and ensure your entire test reporting toolchain is updated accordingly. Review generated reports against the latest CTRF schema if inconsistencies are observed.

Install

• npm install mocha-ctrf-json-reporter npm
• yarn add mocha-ctrf-json-reporter yarn
• pnpm add mocha-ctrf-json-reporter pnpm

Imports

• CTRFReporter
  wrong:

  import { CTRFReporter } from 'mocha-ctrf-json-reporter';

  correct:

  import CTRFReporter from 'mocha-ctrf-json-reporter';

  The reporter class is a default export, though direct import is rare as it's typically configured via a string in Mocha's runner.
• ReporterOptions
  wrong:

  import { ReporterOptions } from 'mocha-ctrf-json-reporter';

  correct:

  import type { ReporterOptions } from 'mocha-ctrf-json-reporter';

  This type is not explicitly exported by the package but would be ideal for type-checking the `reporterOptions` object in user configurations. It's listed here as a conceptual import for comprehensive type usage.
• CTRFReport
  wrong:

  import { CTRFReport } from 'mocha-ctrf-json-reporter';

  correct:

  import type { CTRFReport } from 'mocha-ctrf-json-reporter';

  This type, representing the structure of the generated CTRF JSON report, is not exported by this package. Users typically rely on the external CTRF specification for validation. Listed as a conceptual import for type safety if it were available.

Quickstart

Demonstrates installation, configuration via `.mocharc.js` with custom options including environment variables, and running example Mocha tests to generate a CTRF-compliant JSON report.

npm install --save-dev mocha mocha-ctrf-json-reporter

// .mocharc.js
module.exports = {
  reporter: 'mocha-ctrf-json-reporter',
  reporterOptions: {
    outputFile: 'my-custom-ctrf-report.json',
    outputDir: './test-reports',
    appName: 'MyAwesomeApp',
    appVersion: '1.0.0',
    buildName: 'CI Build',
    buildNumber: process.env.CI_BUILD_NUMBER ?? 'local-run',
    testEnvironment: process.env.NODE_ENV ?? 'development'
  }
};

// test/example.test.js
const assert = require('assert');

describe('Application Feature', function() {
  it('should handle basic arithmetic correctly', function() {
    assert.strictEqual(2 + 2, 4);
  });

  it('should skip this test as an example', function() {
    this.skip();
    assert.fail('This test should not be executed');
  });

  it('should correctly identify string length', function() {
    assert.strictEqual('hello'.length, 5);
  });
});

// To run the tests, add to package.json scripts:
// "scripts": {
//   "test": "mocha"
// }
// Then run: npm test
// The report will be found at ./test-reports/my-custom-ctrf-report.json