Skip to content

Getting Started with TraceCov

Track your API test coverage in 5 minutes

TraceCov maps your real API tests against your OpenAPI specification to reveal untested endpoints, parameters, keywords, and responses. This guide will help you set up TraceCov and generate your first coverage report in under 5 minutes.

Prerequisites

Before you begin, you'll need:

  • An OpenAPI specification (v2.0, v3.0, or v3.1) for your API
  • A way to make requests to your API (test suite, curl, Postman collection, etc.)
  • Your API must be accessible from your local environment (or where TraceCov runs)

For this guide, we'll use the Swagger Petstore API as an example.

Installation

Depending on your platform there are different methods to install TraceCov

# Download the TraceCov binary
curl -sL https://cli.tracecov.sh/install/ | sh

# Verify installation
tracecov --version

# Install using pip
pip install tracecov[community]

# Verify installation
python -c "import tracecov; print(tracecov.__version__)"

Note

You can find TraceCov CLI releases on the GitHub releases page. There executables for Linux, OS X, and Windows.

Connect to Your API

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

# Start TraceCov as a proxy with the Petstore API specification
# The proxy will run until you stop it with Ctrl+C
tracecov proxy https://petstore3.swagger.io/api/v3/openapi.json

# In a new terminal, make API requests through the proxy
curl --insecure -x http://localhost:8080 \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": 123456, "name": "fluffy", "status": "available"}' \
  https://petstore3.swagger.io/api/v3/pet

curl --insecure -x http://localhost:8080 \
  https://petstore3.swagger.io/api/v3/pet/123456

# Stop the proxy with Ctrl+C when you're done
# This will generate the coverage report automatically

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")

The Proxy Advantage

TraceCov's proxy works with any tool that supports HTTP proxies (Postman, JMeter, custom frameworks) without modifying your existing code. Simply point your tools to localhost:8080 to instantly analyze coverage in any test suite.

View the Coverage Report

After running the example, you'll have a coverage.html file in your current directory. Open it in your web browser to see your API coverage:

API Coverage Report
Petstore API Coverage Report

The coverage report provides an immediate visual breakdown of your API's test coverage:

  • Endpoints: Shows which API paths and methods have been exercised
  • Parameters: Tracks which request parameters have been used in tests
  • Response Codes: Identifies which status codes your tests have verified
  • Schema Properties: Highlights which parts of your request/response payloads have been tested

Color coding makes it easy to spot gaps: green for tested elements, red for untested, and yellow for partially tested. This clear visualization helps you prioritize where to focus your next testing efforts.

What's Next?

Now that you've seen how TraceCov works, you can: