Skip to content

JavaScript Integration

@tracecov/core is a coverage engine for Node.js: give it your OpenAPI specification and the HTTP interactions your tests make, and it reports which operations, parameters, and JSON Schema keywords you exercised. Feed it interactions with record() from your HTTP client's interceptor or middleware, or import recorded traffic from HAR, Postman, or VCR files.

Installation

npm install @tracecov/core
# or
yarn add @tracecov/core
# or
pnpm add @tracecov/core

Requirements:

  • Node.js ≥ 18
  • ESM project ("type": "module" in package.json) or TypeScript with "moduleResolution": "nodenext" or "bundler" in tsconfig.json
  • CommonJS projects: use const { CoverageMap } = await import('@tracecov/core')

@tracecov/core is a native Node.js addon and does not run in browser bundles.

Recording interactions

Load your spec, then record each request/response pair:

import { CoverageMap } from '@tracecov/core';

const coverage = CoverageMap.fromPath('openapi.json');

const start = Date.now();
const res = await fetch('https://api.example.com/users?limit=10');
coverage.record(
  { method: 'GET', url: 'https://api.example.com/users?limit=10', headers: {} },
  { statusCode: res.status, elapsed: (Date.now() - start) / 1000 },
);

fromPath reads JSON or YAML; fromDict takes a parsed object; fromUrl fetches over HTTP (await it).

Call record() wherever you make requests — most clients let you do it once in an interceptor or middleware. Pass the request body as a Buffer or string in body to also measure request-body keyword coverage. Annotate a network failure with recordError(method, url, message). For Axios, @tracecov/axios wires this up for you.

Automatic capture with Axios

@tracecov/axios attaches interceptors that record every request an Axios client makes — success, 4xx/5xx, and network failures — including request bodies, so you never call record() by hand:

npm install @tracecov/axios

import { CoverageMap } from '@tracecov/core';
import { instrumentAxios } from '@tracecov/axios';
import axios from 'axios';

const coverage = CoverageMap.fromPath('openapi.json');
const client = axios.create({ baseURL: 'https://api.example.com' });
instrumentAxios(client, coverage);

// Every call through `client` is now recorded.
await client.get('/users', { params: { limit: 10 } });

coverage.saveHtmlReport({ outputFile: 'coverage.html' });

instrumentAxios records the URL Axios actually sends plus the request body and its media type. If recording ever throws it warns and continues; pass { onError } to handle it yourself.

Writing a report

coverage.saveHtmlReport({ outputFile: 'coverage.html' });

generateHtmlReport / generateJsonReport / generateMarkdownReport / generateTextReport return a string; saveHtmlReport / saveJsonReport / saveMarkdownReport write a file. See JSON Report Format for the machine-readable schema.

Enforcing thresholds

const violations = coverage.checkThresholds({ operations: 80, keywords: 70 });
for (const v of violations) {
  console.error(`${v.dimension}: ${v.actual.toFixed(1)}% < ${v.minimum}%`);
}

Each violation reports the dimension, its actual percentage, and the minimum required. Exit non-zero when violations is non-empty to fail your CI.

Importing recorded traffic

Professional Edition

HAR and Postman import require TraceCov Professional.

Already have traffic captured? Analyse it without running new tests:

import fs from 'node:fs';
import { CoverageMap } from '@tracecov/core';

const coverage = CoverageMap.fromPath('openapi.json');
coverage.recordFromHar(JSON.parse(fs.readFileSync('traffic.har', 'utf-8')));
coverage.saveHtmlReport({ outputFile: 'coverage.html' });

recordFromPostman and recordFromVcr take a parsed Postman collection (v1.0, v2.0, v2.1) or VCR cassette the same way. HAR v1.2 and v1.3 are supported (Chrome DevTools, Firefox, Postman, and other standard exporters).

Full method-by-method documentation is in the API reference.