Skip to main content

Welcome to CVT

Contract Validator Toolkit (CVT) is a consumer- and producer-based contract validation platform for OpenAPI v2/v3 specifications.

It helps teams ensure their API consumers and producers communicate correctly by validating HTTP interactions against published contracts.

What is Contract Testing?​

Contract testing validates API interactions against a published contract (OpenAPI specification). Unlike integration tests that require real services, contract tests verify that:

  • Consumers send valid requests and handle responses correctly
  • Producers return responses that match their published specification

Key Features​

FeatureDescription
Schema ValidationRegister OpenAPI v2/v3 schemas and validate request/response pairs
Consumer TestingValidate your HTTP calls against upstream API contracts
Producer TestingEnsure your API implementation matches your specification
Breaking Change DetectionCompare schema versions to detect incompatible changes
Safe DeploymentsUse CanIDeploy to verify changes won't break consumers
Multi-language SDKsNative support for Node.js, Python, Go, and Java

Quick Start​

1. Start the CVT Server​

# Using the published Docker image (recommended)
docker run -d -p 9550:9550 -p 9551:9551 ghcr.io/sahina/cvt:latest

# Or using Docker Compose (if you've cloned the repository)
make up

# Or build and run locally
make run-server

2. Install an SDK​

# Node.js
npm install @sahina/cvt-sdk

# Python
pip install cvt-sdk

# Go
go get github.com/sahina/cvt/sdks/go

For Java (Maven), add to pom.xml:

<dependency>
    <groupId>io.github.sahina</groupId>
    <artifactId>cvt-sdk</artifactId>
    <version>0.1.3</version> <!-- Replace with latest from Maven Central -->
</dependency>

See Installation for detailed instructions.

3. Validate an Interaction​

Save the Petstore OpenAPI schema as ./openapi.json, then:

import { ContractValidator } from "@sahina/cvt-sdk";

const validator = new ContractValidator("localhost:9550");

// Register your schema from file
await validator.registerSchema("petstore", "./openapi.json");
// Or register from URL:
// await validator.registerSchema("petstore", "https://petstore3.swagger.io/api/v3/openapi.json");

// Validate an interaction
const result = await validator.validate(
  { method: "GET", path: "/pet/123" },
  {
    statusCode: 200,
    body: {
      id: 123,
      name: "doggie",
      photoUrls: ["https://example.com/photo.jpg"],
      status: "available",
    },
  },
);

console.log(result.valid); // true or false
validator.close();

Architecture​

CVT runs as a gRPC service that can be deployed via Docker or run locally:

┌─────────────────┐     gRPC      ┌─────────────────┐
│   Your Tests    │ ────────────► │   CVT Server    │
│  (SDK Client)   │               │   (Port 9550)   │
└─────────────────┘               └─────────────────┘
                                          │
                                          ▼
                                  ┌─────────────────┐
                                  │ Schema Registry │
                                  │  + Validation   │
                                  └─────────────────┘
Architecture Deep Dive

For detailed system architecture, component design, validation engine, and storage layer documentation, see the Architecture Documentation.

Documentation Structure​

Getting Started​

Guides​

Reference​

Operations​

Development​

Next Steps​

Choose your path based on your role:

API Consumer? Start with the Consumer Testing Guide to learn how to validate your API integrations.

API Producer? Check out the Producer Testing Guide to ensure your API matches its specification.

Setting up CVT? Follow the Installation Guide for server setup and configuration.