{"id":14711,"library":"mocha-ctrf-json-reporter","title":"Mocha Common Test Report Format (CTRF) JSON Reporter","description":"This package provides a Mocha test reporter that generates test results in the Common Test Report Format (CTRF) as a JSON file. CTRF is an open, community-driven standard for normalizing test reports across different programming languages and test frameworks, enabling consistent validation, merging, comparison, and analysis of test results. The current stable version is `0.0.11`. Releases appear to be ad-hoc, primarily driven by dependency updates or feature additions, without a strict cadence. Its key differentiator is its adherence to the CTRF specification, providing a standardized output that integrates into a broader ecosystem of tools designed to consume CTRF data, abstracting away framework-specific report parsing. This allows for unified reporting in CI/CD pipelines.","status":"active","version":"0.0.11","language":"javascript","source_language":"en","source_url":"https://github.com/ctrf-io/mocha-ctrf-json-reporter","tags":["javascript","ctrf","common-test-report-format","test-reporting","test-results","testing","json","ci","mocha","typescript"],"install":[{"cmd":"npm install mocha-ctrf-json-reporter","lang":"bash","label":"npm"},{"cmd":"yarn add mocha-ctrf-json-reporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add mocha-ctrf-json-reporter","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The reporter class is a default export, though direct import is rare as it's typically configured via a string in Mocha's runner.","wrong":"import { CTRFReporter } from 'mocha-ctrf-json-reporter';","symbol":"CTRFReporter","correct":"import CTRFReporter from 'mocha-ctrf-json-reporter';"},{"note":"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.","wrong":"import { ReporterOptions } from 'mocha-ctrf-json-reporter';","symbol":"ReporterOptions","correct":"import type { ReporterOptions } from 'mocha-ctrf-json-reporter';"},{"note":"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.","wrong":"import { CTRFReport } from 'mocha-ctrf-json-reporter';","symbol":"CTRFReport","correct":"import type { CTRFReport } from 'mocha-ctrf-json-reporter';"}],"quickstart":{"code":"npm install --save-dev mocha mocha-ctrf-json-reporter\n\n// .mocharc.js\nmodule.exports = {\n  reporter: 'mocha-ctrf-json-reporter',\n  reporterOptions: {\n    outputFile: 'my-custom-ctrf-report.json',\n    outputDir: './test-reports',\n    appName: 'MyAwesomeApp',\n    appVersion: '1.0.0',\n    buildName: 'CI Build',\n    buildNumber: process.env.CI_BUILD_NUMBER ?? 'local-run',\n    testEnvironment: process.env.NODE_ENV ?? 'development'\n  }\n};\n\n// test/example.test.js\nconst assert = require('assert');\n\ndescribe('Application Feature', function() {\n  it('should handle basic arithmetic correctly', function() {\n    assert.strictEqual(2 + 2, 4);\n  });\n\n  it('should skip this test as an example', function() {\n    this.skip();\n    assert.fail('This test should not be executed');\n  });\n\n  it('should correctly identify string length', function() {\n    assert.strictEqual('hello'.length, 5);\n  });\n});\n\n// To run the tests, add to package.json scripts:\n// \"scripts\": {\n//   \"test\": \"mocha\"\n// }\n// Then run: npm test\n// The report will be found at ./test-reports/my-custom-ctrf-report.json","lang":"typescript","description":"Demonstrates installation, configuration via `.mocharc.js` with custom options including environment variables, and running example Mocha tests to generate a CTRF-compliant JSON report."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.10"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev mocha-ctrf-json-reporter` to install the package as a development dependency.","cause":"The reporter package has not been installed or is not accessible in the current execution environment.","error":"Error: Cannot find module 'mocha-ctrf-json-reporter'"},{"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.","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.","error":"Report file 'ctrf-report.json' not found in 'ctrf/' directory."},{"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.","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.","error":"Mocha exited with error code 1 without generating a report."}],"ecosystem":"npm"}