Python Integration

This guide shows how to integrate TraceCov into your Python test suite. We'll cover tracking API calls against your OpenAPI schema, recording individual requests, generating coverage reports, and analyzing traffic from third-party formats like Postman Collections and HAR files.

Installation

TraceCov is available as a Python package that you can install using pip:

$ pip install tracecov[community]

Basic Usage

The core workflow with TraceCov involves three steps: creating a coverage map, tracking API calls, and generating a report.

Step 1: Create a CoverageMap Instance

First, create a coverage map by providing your OpenAPI schema:

import tracecov

coverage = tracecov.CoverageMap.from_dict({
    "openapi": "3.0.0",
    "info": {"title": "Example API", "version": "1.0.0"},
    "paths": {
        # Your API paths here
    }
})

# Alternatively, load from a file
# coverage = tracecov.CoverageMap.from_file("openapi.json")

Step 2: Track API calls

TraceCov offers multiple ways to track API calls, depending on your testing approach and existing code structure:

import requests

# Option A: Create and configure a session
session = coverage.requests.track_session(requests.Session())
session.headers.update({"Authorization": "Bearer token"})

# Use the session as normal - all requests will be tracked
response = session.get("https://api.example.com/users/1")
response = session.post("https://api.example.com/users", json={"name": "Alice"})

# Option B: Record individual requests manually
response = requests.get("https://api.example.com/users/1")
coverage.requests.record(request=response.request, response=response)

# Option C: Pass a response hook to each call
hook = coverage.requests.response_hook()
response = requests.get(
    "https://api.example.com/users/1", hooks={"response": [hook]}
)

Step 3: Generate a Coverage Report

Once you've tracked your API interactions, generate an HTML report to visualize your coverage:

# Store an HTML report to a file
# Default filename is schema-coverage.html if not specified
coverage.save_report(output_file="my-api-coverage.html")
# Or get it as a string
html = coverage.generate_report()

Using with other HTTP clients

If you prefer alternative HTTP libraries like httpx instead of requests, TraceCov provides similar integration capabilities:

import httpx

client = coverage.httpx.track_client(httpx.Client())
# Use the client as normal - all requests will be tracked
# Async client works too!
client = coverage.httpx.track_client(httpx.AsyncClient())

Using with pytest

Using the following snippet you can automatically track coverage across multiple tests:

import pytest
import requests
import tracecov


@pytest.fixture(scope="session")
def coverage():
    coverage = tracecov.CoverageMap.from_dict({"openapi": "3.1.0"})
    yield coverage
    coverage.save_report()


@pytest.fixture(scope="session")
def api_client(coverage):
    return coverage.requests.track_session(requests.Session())


def test_get_user(api_client):
    response = api_client.get("https://api.example.com/users/1")
    assert response.status_code == 200

Using with Schemathesis

Schemathesis is a powerful property-based testing tool for APIs. TraceCov can automatically track all API calls made during Schemathesis test runs:

Step 1: Create a Python file (e.g. hooks.py)

import tracecov

tracecov.schemathesis.install()

Step 2: Set the SCHEMATHESIS_HOOKS environment variable

$ export SCHEMATHESIS_HOOKS=hooks

Step 3: Run Schemathesis

$ schemathesis run https://example.schemathesis.io/openapi.json \
    --coverage-format=html

...
Schema Coverage report: ./schema-coverage.html

Note

TraceCov supports Schemathesis v4.0.0-alpha.8 and above.

Third-Party Format Integrations

TraceCov can analyze test traffic from common API testing tools without requiring direct integration.

Low-Level API

For advanced use cases or integration with custom HTTP clients, TraceCov provides a low-level API that accepts generic request and response objects:

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

Third-Party Format Integrations

TraceCov can analyze test traffic from common API testing tools without requiring direct integration.

Postman Collections

If you use Postman for API testing, TraceCov can analyze your collections to measure coverage:

import json

# Load and analyze a Postman Collection from a file
coverage.postman.record_from_path("path/to/collection.json")

# Analyze a collection from a dictionary
with open("path/to/collection.json") as fd:
  collection = json.load(fd)
coverage.postman.record_from_dict(collection)

Note

TraceCov supports Postman Collection formats v1.0, v2.0, and v2.1.

HTTP Archive (HAR) Files

TraceCov can analyze HAR files exported from browser dev tools or API tools:

import json

# Load and analyze a HAR file
coverage.har.record_from_path("path/to/traffic.har")

# Analyze HAR data from a dictionary
with open("path/to/traffic.har") as fd:
  har = json.load(fd)
coverage.har.record_from_dict(har)

Note

TraceCov supports HAR formats v1.2 and v1.3 from Chrome, Firefox, Edge, Postman, and other tools that export standard HAR format.