Jasmine CTRF JSON Reporter

Common errors

• ReferenceError: CtrfReporter is not defined

  cause The `CtrfReporter` class was not imported or required correctly, or the module path is incorrect.
  fix Ensure you have `npm install --save-dev jasmine-ctrf-json-reporter` and use `const CtrfReporter = require('jasmine-ctrf-json-reporter');` for CommonJS or `import CtrfReporter from 'jasmine-ctrf-json-reporter';` for ESM.

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

  cause The package has not been installed or is not accessible in the current environment.
  fix Run `npm install --save-dev jasmine-ctrf-json-reporter` to add the package to your project.

• TypeError: jasmine.getEnv(...).addReporter is not a function

  cause This error typically occurs if you're trying to add the reporter outside of a context where `jasmine.getEnv()` is available, or if Jasmine itself isn't properly set up.
  fix Ensure your reporter setup code is run within a Jasmine test environment, typically in a helper file loaded by Jasmine before test execution.

• File 'ctrf/ctrf-report.json' not found after tests complete.

  cause The reporter did not execute, or the output directory/file name was customized and not found at the expected location.
  fix Verify the reporter is correctly added to `jasmine.getEnv().addReporter()` and check the `outputDir` and `outputFile` options. Ensure the test run completes without errors that might prevent the report from being written.

Warnings

• gotcha This package is still in early development (v0.0.x). While efforts are made for stability, the API may undergo breaking changes in minor versions. Always review the changelog when updating.
  Fix: Pin to exact versions in `package.json` for production environments (`"jasmine-ctrf-json-reporter": "0.0.x"`) and manually review releases, or use a tilde `~` to allow patch updates only.
• gotcha The reporter is configured by adding it directly to the Jasmine environment (`jasmine.getEnv().addReporter()`), not through `jasmine.json` or other configuration files. Ensure this line is present in your `spec/support/jasmine.js` or similar setup file.
  Fix: Place `jasmine.getEnv().addReporter(new CtrfReporter(...));` in your main Jasmine configuration or helper file that is loaded before tests run.
• gotcha The `outputFile` and `outputDir` options have default values (`ctrf-report.json` and `ctrf/`). If these are not specified, the output will be generated in the default location. Ensure your CI/CD pipelines are aware of these defaults or configure custom paths explicitly.
  Fix: Explicitly set `outputFile` and `outputDir` in the reporter options if you require a specific path, e.g., `{ outputFile: 'test-results.json', outputDir: 'artifacts' }`.

Install

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

Imports

• CtrfReporter
  wrong:

  const CtrfReporter = require('jasmine-ctrf-json-reporter');

  correct:

  import CtrfReporter from 'jasmine-ctrf-json-reporter';

  Used to instantiate the reporter. The CJS `require` example implies a default export.
• ctrf
  wrong:

  import ctrf from 'jasmine-ctrf-json-reporter';

  correct:

  import { ctrf } from 'jasmine-ctrf-json-reporter';

  Provides the `extra` function for attaching custom metadata to individual test results. This is a named export.
• ReporterOptions
  wrong:

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

  correct:

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

  Type import for configuring reporter options in TypeScript projects. Do not use for runtime import.

Quickstart

Demonstrates how to install the reporter, configure it in Jasmine, and use the `ctrf.extra()` function to add custom metadata to individual test results.

import CtrfReporter, { ctrf } from 'jasmine-ctrf-json-reporter';

// In your Jasmine helper file (e.g., spec/support/jasmine.js or .ts)
// It's recommended to configure the reporter here.
jasmine.getEnv().addReporter(
  new CtrfReporter({
    outputFile: 'my-custom-ctrf-report.json', // Optional: Custom output file name
    outputDir: 'reports/ctrf-output',       // Optional: Custom output directory
    appName: 'MyFeatureApp',                // Optional: Application name
    appVersion: '1.2.3',                    // Optional: Application version
    osPlatform: process.env.OS_PLATFORM ?? 'web', // Dynamically set OS platform
    osRelease: process.env.OS_RELEASE ?? 'latest',
    buildName: 'CI-Pipeline-Build',         // Optional: Build name
    buildNumber: process.env.BUILD_NUMBER ?? 'unknown' // Dynamic build number
  })
);

// Example of usage within a test file (e.g., spec/my-feature.spec.ts)
describe('User Management Module', () => {
  it('should successfully register a new user', () => {
    // Attach custom metadata to this specific test result
    ctrf.extra({ owner: 'user-auth-team', priority: 'high', testId: 'UM-001' });
    // ... actual test logic for user registration ...
    expect(true).toBe(true); // Placeholder for actual test
  });

  it('should validate email format during registration', () => {
    // This test might not need extra metadata
    expect(false).toBe(false); // Another placeholder test
  });
});