Cypress CTRF JSON Reporter

0.0.14 · active · verified Tue Apr 21

cypress-ctrf-json-reporter is a Cypress test reporter designed to generate JSON reports conforming to the Common Test Report Format (CTRF) open standard. Currently at version `0.0.14`, this package is in its early development stages, with releases primarily focused on dependency updates and repository hygiene, indicating a maintenance-oriented cadence rather than active feature development. Its primary differentiator is the strict adherence to CTRF, a community-driven specification that ensures uniform, framework-agnostic test reports. This standardization allows for consistent validation, merging, comparison, and analysis of test results across diverse programming languages and testing frameworks, thereby improving CI/CD pipeline integration and analytics. It seamlessly integrates into Cypress configurations, outputting a `ctrf-report.json` file by default.

Common errors

```
Only one listener can be registered for 'after:run' event. Multiple plugins are conflicting.
```
cause Cypress's plugin system allows only one listener per event. If multiple reporters or plugins try to register for the same lifecycle event (e.g., `after:run`), the last one registered overrides previous ones.

fix Refer to the 'Handling Multiple Plugins in Cypress' section in the reporter's README for guidance on how to manage and merge multiple event listeners, ensuring all plugins work together without conflict. This often involves a custom `setupNodeEvents` helper.
```
TypeError: GenerateCtrfReport is not a constructor or function.
```
cause This usually indicates that the `GenerateCtrfReport` symbol was not correctly imported or required, or that the `new` keyword was omitted when instantiating the class.

fix Ensure `const { GenerateCtrfReport } = require('cypress-ctrf-json-reporter')` (for CJS) or `import { GenerateCtrfReport } from 'cypress-ctrf-json-reporter'` (for ESM/TS) is used, and always instantiate it with `new GenerateCtrfReport({...})`.

Warnings

gotcha The package is still in early development (v0.0.x), which typically means API stability is not guaranteed, and breaking changes might occur in minor releases.
Fix: Always review release notes carefully when upgrading. Consider pinning to exact versions for production environments.
breaking Cypress versions below v10 require a different installation approach, placing the reporter initialization in `cypress/plugins/index.js` instead of `cypress.config.js`'s `setupNodeEvents` function.
Fix: For Cypress < v10, initialize the reporter within `cypress/plugins/index.js` as shown in the package's documentation, passing the `on` object directly.

Install

npm install cypress-ctrf-json-reporter npm
yarn add cypress-ctrf-json-reporter yarn
pnpm add cypress-ctrf-json-reporter pnpm

Imports

GenerateCtrfReport

wrong:

import { GenerateCtrfReport } from 'cypress-ctrf-json-reporter'

correct:

const { GenerateCtrfReport } = require('cypress-ctrf-json-reporter')

For CommonJS (`.js`) files like `cypress.config.js` or `plugins/index.js`.

GenerateCtrfReport

wrong:

import GenerateCtrfReport from 'cypress-ctrf-json-reporter'

correct:

import { GenerateCtrfReport } from 'cypress-ctrf-json-reporter'

For ES Modules (`.ts`, `.mjs`) files. `GenerateCtrfReport` is a named export.

GenerateCtrfReportOptions
```
import type { GenerateCtrfReportOptions } from 'cypress-ctrf-json-reporter'
```
For TypeScript users to explicitly type the options object passed to the reporter constructor.

Quickstart

Demonstrates how to install and configure the reporter within Cypress's `cypress.config.js` to generate a CTRF-compliant JSON report.

const { defineConfig } = require('cypress');
const { GenerateCtrfReport } = require('cypress-ctrf-json-reporter');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Implement node event listeners here
      new GenerateCtrfReport({
        on,
        outputFile: 'my-custom-report.json',
        appName: 'My Cypress App',
        buildNumber: process.env.CI_BUILD_NUMBER ?? 'local'
      });
    },
  },
});

// To run:
// npx cypress run

view raw JSON →