Snow-White

Snow-White connects your OpenAPI specifications with runtime telemetry data to answer a simple question: which parts of your API are actually being tested?

It correlates OpenTelemetry (OTel) traces emitted by your application with the endpoints declared in your API specifications - then validates coverage against configurable quality gates.

Snow-White works with black-box test suites (system tests, integration tests) as well as **live production traffic **.

It currently provides insights into:

• Coverage - which endpoints were exercised and which were not
• API Performance - response time analysis across operations

A Guardrail for Agentic Development

AI coding agents can now write both the implementation and the tests that verify it - which means a green test suite no longer proves much: it may just prove the agent's tests agree with the agent's code, not that either matches the API contract you actually promised. Snow-White sits outside that loop. It checks real OpenTelemetry traces emitted by the running application against the OpenAPI spec on file, so coverage and quality-gate results stay an honest, ground-truth signal regardless of who - or what - wrote the code or the tests.

That makes it a natural fit for agentic workflows specifically: run snow-white calculate --agentic and get back a single line of JSON naming exactly which paths, methods, response codes, and parameters are still undercovered - a concrete, machine-readable backlog an agent can work from without a human translating a report first. Snow-White also ships a Claude Code skill that already knows how to turn that into prioritized test fixes.

Documentation

Full documentation is available at bbortt.github.io/snow-white.

Section	Description
Deployment	Install Snow-White with Helm and configure your environment
Onboarding	Step-by-step guide to integrating your service
Architecture	Component overview and event-driven design
Workflows	CI/CD pipeline patterns and quality gate workflows
CLI Reference	Full CLI command reference
Claude Code Skill	Turn failing quality gates into fixes from inside an agentic session
Requirements	System and dependency requirements
License	Licensing details and commercial use

Installation (for providers)

Snow-White can be installed easily using Helm. Detailed instructions and available options are described in "Deployment".

Individual images could also be used for a custom installation. The Docker compose file dev/docker-compose.yaml may be used as a starting point.

Onboarding (for users)

See "Onboarding" for a step-by-step guide to integrating your service with Snow-White.

General Concept

Here's a high-level overview of Snow-White. For a detailed component and data-flow breakdown, see the Architecture docs.

1. Synchronize API Specs - Snow-White imports OpenAPI specifications from your central interface repository.
2. Ingest Telemetry - It listens to OpenTelemetry tracing data emitted by your applications.
3. Correlate & Analyze - Traces are matched with API operations using service, API name, and version metadata.
4. Evaluate Quality Gates - Results are validated against your configured thresholds.
5. Visualize or Export Results - Coverage and performance insights can be viewed in reports or integrated into CI pipelines.

Annotating APIs

The core idea behind Snow-White is that it can only interpret runtime telemetry (e.g. traces) if it knows which API the data belongs to. This is achieved by a common annotation model applied both to the specifications and to the telemetry data.

Every API must declare a few key identifiers:

• Service Name: Identifies the logical unit or application that exposes the API.
  • Required, because different applications may have identically named endpoints (e.g. /health).
• API Name: Identifies the API within the service.
• Version: Specifies the API version.

With OpenAPI, this is expressed using vendor extensions:

openapi: 3.1.2
info:
  title: Ping-Pong API
  description: A simple API for ping-pong interactions to demonstrate OpenAPI coverage calculation
  version: 1.0.0
  x-api-name: ping-pong
  x-service-name: example-application

These annotations are the linking key between specifications and runtime telemetry.

Making Specifications Available

Snow-White needs access to the API specifications. This is typically done by publishing them to a central HTTP-based service interface repository, where Snow-White can fetch and synchronize them.

👉 For details, see the api-sync-job documentation (handles synchronization and version management).

Connecting Runtime Data

Next, the running service must provide OpenTelemetry (OTel) tracing data.

At the moment, only tracing is relevant (metrics and logs are not used yet). The traces must be enhanced with the same annotation information used in the specifications:

• Service Name: service.name attribute
• API Name: api.name attribute
• API Version: api.version attribute

This enrichment ensures that Snow-White can correlate a runtime span to the correct API specification.

To simplify this, the project provides:

• OpenAPI Generator Plugin - Generates code that automatically attaches the right annotations.
• Spring Web Autoconfiguration - Automatically enriches spans with API metadata in Spring-based services.
• Spring Kafka Autoconfiguration - Does the same for records consumed by a @KafkaListener, using the AsyncAPI attributes.

Coverage Calculation

Once both inputs are in place (specifications + traces), you can trigger a coverage calculation. This can be done via the CLI.

The CLI allows you to synchronize APIs, trigger coverage analysis, and validate results against quality gates directly from your local environment or CI pipeline.

Coverage results are validated against Quality-Gate Configurations. These configurations define the rules and thresholds that your API data must satisfy. Snow-White comes with predefined quality gates to get started quickly, and you can customize them later.

Development & Contributing

We welcome contributions! Whether you're fixing a bug, adding a feature, or improving the documentation - thank you 🙌

To get started:

1. Read our DEVELOPMENT.md for a step-by-step guide on setting up your local environment.
2. Open a Pull Request or file an issue if you’ve found something worth improving.
3. Make sure to follow the coding style and commit conventions described in DEVELOPMENT.md.

Local Setup (Quick Start)

Prerequisites: Java 25, Node.js 22, Docker or Podman (with Compose).

git clone https://github.com/bbortt/snow-white.git
cd snow-white

# Build all modules (including the CLI and generated sources)
./mvnw -Pnode package

# Start the development environment
docker compose -f dev/docker-compose.yaml up -d

A manual InfluxDB token setup step is required before traces can flow. See DEVELOPMENT.md for the full walkthrough.

Contributing Guidelines

• Keep commits small and focused. Follow Conventional Commits (feat:, fix:, chore:, etc.).
• All new features should include tests.
• Run the full build before opening a PR: ./mvnw -Pnode verify
• Open an issue first for larger changes so we can align on direction before you invest time coding.

Please be respectful and constructive in all interactions.

License

This project is licensed under the Polyform Small Business License 1.0.0.

This means you can freely use, modify, and distribute the software if your company generates less than $1 million USD in annual revenue and meets other conditions in the license.

If your company exceeds this threshold or you intend to use Snow-White commercially, please reach out for licensing options: [[email protected]].

See the LICENSE file for full details.