Skip to content

Quick Start

Generate a coverage report using the Swagger Petstore API.

Installation

curl -sL https://cli.tracecov.sh/install/ | sh

uv pip install tracecov

npm install @tracecov/core

Connect to Your API

Now let's set up TraceCov to track requests to the Petstore API:

First, save your API traffic as JSON. Create a file traffic.json:

{
  "interactions": [
    {
      "request": {
        "method": "POST",
        "url": "https://petstore3.swagger.io/api/v3/pet",
        "headers": {"Content-Type": "application/json"},
        "body": "{\"id\": 123456, \"name\": \"fluffy\", \"status\": \"available\"}"
      },
      "response": {"status_code": 200}
    },
    {
      "request": {
        "method": "GET",
        "url": "https://petstore3.swagger.io/api/v3/pet/123456",
        "headers": {}
      },
      "response": {"status_code": 200}
    }
  ]
}

Then generate the coverage report:

tracecov report https://petstore3.swagger.io/api/v3/openapi.json traffic.json

import tracecov
import requests

# Download the OpenAPI specification
response = requests.get("https://petstore3.swagger.io/api/v3/openapi.json")
schema = response.json()

# Create a coverage tracker
coverage = tracecov.CoverageMap.from_dict(schema, base_path="/api/v3")

# Set up a tracked session
session = coverage.requests.track_session(requests.Session())

# Make API requests
fluffy = {
    "id": 123456,
    "name": "fluffy",
    "photoUrls": [],
    "tags": [{"id": 1, "name": "cute"}],
    "status": "available"
}
session.post("https://petstore3.swagger.io/api/v3/pet", json=fluffy)
session.get("https://petstore3.swagger.io/api/v3/pet/123456")

# Generate a coverage report
coverage.save_report(output_file="coverage.html")

Load the spec, make requests, and record each one:

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

const coverage = await CoverageMap.fromUrl(
  'https://petstore3.swagger.io/api/v3/openapi.json',
  { basePath: '/api/v3' },
);

const url = 'https://petstore3.swagger.io/api/v3/pet';
const start = Date.now();
const res = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 123456, name: 'fluffy', photoUrls: [], status: 'available' }),
});
coverage.record(
  { method: 'POST', url, headers: { 'Content-Type': 'application/json' } },
  { statusCode: res.status, elapsed: (Date.now() - start) / 1000 },
);

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

Prefer automatic capture? @tracecov/axios (instrumentAxios(client, coverage)) and @tracecov/fetch (instrumentFetch(coverage)) record every call for you — no per-request record(). See the integration guide.

View the Report

Open coverage.html in your browser:

API Coverage Report
Petstore API Coverage Report

The report shows coverage at multiple levels:

Color Meaning
🟢 Green Fully covered
🟡 Yellow Partially covered (e.g., valid inputs tested, but not invalid)
🔴 Red Not covered

Expand any operation to see which parameters and JSON Schema keywords have been tested.

Next Steps