Skip to content

Python API Reference

This reference documents all classes and methods available in the TraceCov Python API.

CoverageMap

The main class for tracking API coverage against an OpenAPI specification.

CoverageMap.from_dict

Create a CoverageMap instance from a dictionary containing an OpenAPI schema.

Parameters:

  • schema (dict): OpenAPI schema as a Python dictionary
  • base_path (str, optional): Base path prefix for all API endpoints
  • location (str, optional): Base URI for resolving relative references in the schema

Returns: CoverageMap instance

Usage:

# Basic usage
coverage = tracecov.CoverageMap.from_dict({
    "openapi": "3.0.0",
    "paths": {
        "/users": {
            "get": {
                # GET /users definition
            }
        }
    }
})

# With base path specified (for APIs hosted under a path)
coverage = tracecov.CoverageMap.from_dict(
    {
        "openapi": "3.0.0",
        "paths": {
            "/users": {
                "get": {
                    # GET /users definition
                }
            }
        }
    },
    base_path="/api/v1"
)

CoverageMap.from_path

Create a CoverageMap instance from a path to an OpenAPI schema.

Parameters:

  • path (str | pathlib.Path): Path to an OpenAPI schema file (JSON or YAML)
  • base_path (str, optional): Base path prefix for all API endpoints

Returns: CoverageMap instance

Usage:

# Basic usage
coverage = tracecov.CoverageMap.from_path("openapi.json")

# With base path specified
coverage = tracecov.CoverageMap.from_path("openapi.json", base_path="/api/v1")

# Using a pathlib.Path object
from pathlib import Path
schema_path = Path("openapi.json")
coverage = tracecov.CoverageMap.from_path(schema_path)

CoverageMap.record

Record a request/response pair directly using the low-level API.

Parameters:

  • request (HttpRequest): Request object
  • response (HttpResponse, optional): Response object

Returns: None

Usage:

from tracecov import HttpRequest, HttpResponse

coverage.record(
    request=HttpRequest(
        method="GET",
        url="https://api.example.com/users/1",
        body=None,
        headers={},
    ),
    response=HttpResponse(status_code=200, elapsed=1.3),
)

CoverageMap.generate_report

Generate an HTML report string.

Parameters:

  • title (str, optional): Custom title for the report

Returns: HTML report as a string

Usage:

html_content = coverage.generate_report(title="My API Coverage Report")

CoverageMap.save_report

Generate and save an HTML report to a file.

Parameters:

  • output_file (str, optional): Output file path. Defaults to "schema-coverage.html"
  • title (str, optional): Custom title for the report

Returns: None

Usage:

coverage.save_report(output_file="my-api-coverage.html", title="My API Coverage Report")

CoverageMap.requests

Access the requests integration features.

Returns: RequestsPlugin instance

Usage:

requests_plugin = coverage.requests

CoverageMap.httpx

Access the httpx integration features.

Returns: HttpxPlugin instance

Usage:

httpx_plugin = coverage.httpx

CoverageMap.postman

Access the Postman Collection integration features.

Returns: PostmanPlugin instance

Usage:

postman_plugin = coverage.postman

CoverageMap.har

Access the HAR (HTTP Archive) integration features.

Returns: HarPlugin instance

Usage:

har_plugin = coverage.har

RequestsPlugin

Plugin for integrating with the requests library.

RequestsPlugin.track_session

Wrap a requests.Session to track all API calls.

Parameters:

  • session (requests.Session): Session to track

Returns: A session object with installed response hook that tracks all API calls

Usage:

import requests

session = coverage.requests.track_session(requests.Session())
response = session.get("https://api.example.com/users")

RequestsPlugin.record

Record a request/response pair from the requests library.

Parameters:

  • request (requests.Request): Request object from requests
  • response (requests.Response): Response object from requests

Returns: None

Usage:

import requests

response = requests.get("https://api.example.com/users")
coverage.requests.record(request=response.request, response=response)

RequestsPlugin.response_hook

Create a response hook for use with requests.

Returns: A function that can be used in requests hooks parameter

Usage:

import requests

hook = coverage.requests.response_hook()
response = requests.get(
    "https://api.example.com/users", 
    hooks={"response": [hook]}
)

HttpxPlugin

Plugin for integrating with the httpx library.

HttpxPlugin.track_client

Track an httpx.Client or httpx.AsyncClient to record all API calls.

Parameters:

  • client (httpx.Client | httpx.AsyncClient): Client to track

Returns: Client instance with event hook installed to track all API calls

Usage:

import httpx

# Synchronous client
client = coverage.httpx.track_client(httpx.Client())
response = client.get("https://api.example.com/users")

# Asynchronous client
client = coverage.httpx.track_client(httpx.AsyncClient())
# response = await client.get("https://api.example.com/users")

HttpxPlugin.record

Record a request/response pair from httpx.

Parameters:

  • request (httpx.Request): Request object from httpx
  • response (httpx.Response, optional): Response object from httpx

Returns: None

Usage:

import httpx

response = httpx.get("https://api.example.com/users")
coverage.httpx.record(request=response.request, response=response)

HttpxPlugin.response_hook

Create a response hook for use with httpx.Client.

Returns: A function that can be used in httpx event hooks

Usage:

import httpx

hook = coverage.httpx.response_hook()
client = httpx.Client()
client.event_hooks["response"] = [hook]
response = client.get("https://api.example.com/users")

HttpxPlugin.async_response_hook

Create an async response hook for use with httpx.AsyncClient.

Returns: An async function that can be used in httpx event hooks

Usage:

import httpx

hook = coverage.httpx.async_response_hook()
client = httpx.AsyncClient()
client.event_hooks["response"] = [hook]
# response = await client.get("https://api.example.com/users")

PostmanPlugin

Plugin for analyzing Postman Collections.

PostmanPlugin.record_from_path

Load and analyze a Postman Collection from a file.

Parameters:

  • path (str | pathlib.Path): Path to a Postman Collection JSON file

Returns: None

Usage:

coverage.postman.record_from_path("path/to/collection.json")

PostmanPlugin.record_from_dict

Analyze a Postman Collection from a dictionary.

Parameters:

  • data (dict): Postman Collection as a Python dictionary

Returns: None

Usage:

import json

with open("path/to/collection.json") as f:
    collection = json.load(f)

coverage.postman.record_from_dict(collection)

Supported Formats: Postman Collection v1.0, v2.0, and v2.1

HarPlugin

Plugin for analyzing HAR (HTTP Archive) files.

HarPlugin.record_from_path

Load and analyze a HAR file.

Parameters:

  • path (str | pathlib.Path): Path to a HAR file

Returns: None

Usage:

coverage.har.record_from_path("path/to/traffic.har")

HarPlugin.record_from_dict

Analyze HAR data from a dictionary.

Parameters:

  • archive (dict): HAR data as a Python dictionary

Returns: None

Usage:

import json

with open("path/to/traffic.har") as f:
    har = json.load(f)

coverage.har.record_from_dict(har)

Supported Formats: HAR v1.2 and v1.3 from Chrome, Firefox, Edge, Postman, and other tools that export standard HAR format.

Low-Level API

HttpRequest

Generic representation of an HTTP request.

Parameters:

  • method (str): HTTP method (GET, POST, etc.)
  • url (str): Full URL including query parameters
  • body (bytes, optional): Request body
  • headers (dict, optional): Request headers

Usage:

from tracecov import HttpRequest

request = HttpRequest(
    method="GET",
    url="https://api.example.com/users/1",
    body=None,
    headers={"Authorization": "Bearer token"}
)

HttpResponse

Generic representation of an HTTP response.

Parameters:

  • status_code (int): HTTP status code
  • elapsed (float): Time taken for the request in seconds

Usage:

from tracecov import HttpResponse

response = HttpResponse(status_code=200, elapsed=1.2)