Skip to content

CLAUDE.md

Latest commit

 

History

History
112 lines (74 loc) · 4.22 KB

CLAUDE.md

File metadata and controls

112 lines (74 loc) · 4.22 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is the reference implementation of Pact contract testing written in Rust. It provides shared libraries for consumer and provider testing, with FFI bindings for use in other languages. The project supports Pact specification V1–V4.

Note: The mock server crates (pact_mock_server, pact_mock_server_cli) have moved to https://github.com/pact-foundation/pact-core-mock-server and are excluded from this workspace.

Build & Test Commands

All Cargo commands must be run from the rust/ subdirectory (the workspace root):

cd rust

# Build all crates
cargo build

# Run all tests
cargo test

# Run tests for a specific crate
cargo test --package pact_models

# Run a single test by name (exact match)
cargo test --package pact_models -- my_test_name --exact

# Run tests in a specific module
cargo test --package pact_matching headers::tests

# Run tests with log output
RUST_LOG=debug cargo test -- --nocapture

# Lint
cargo clippy

# Check without building (faster)
cargo check

# Release build (strip=true, opt-level="z")
cargo build --release

WASM targets (pact_models and pact_matching only)

cargo build --target wasm32-wasip2

Cross-compilation / MUSL static builds

docker run --rm --user "$(id -u)":"$(id -g)" \
  -v $(pwd):/workspace -w /workspace/rust \
  -t -e TZ=UTC pactfoundation/rust-musl-build \
  ./scripts/ci-musl-build.sh

Crate Architecture

The dependency graph flows upward — each layer depends on those below it:

pact_models          ← Pact data structures, reading/writing pact files
    ↑
pact_matching        ← Request/response matching logic
    ↑           ↖
pact_verifier    pact_consumer   ← Verification library / Consumer DSL
    ↑                ↑
pact_verifier_cli  pact_ffi      ← Standalone CLI / C FFI bindings

Crates

  • pact_models: Core data structures for Pact contracts. Handles JSON serialization of pact files. WASM-compatible (no tokio/reqwest on WASM). Features: datetime, xml, form_urlencoded.

  • pact_matching: Implements all matching rules and interaction matching. Supports plugin-based extensibility via pact-plugin-driver. Features: datetime, xml, plugins, multipart, form_urlencoded.

  • pact_consumer: DSL for writing consumer tests in Rust. Integrates with pact_mock_server (external repo). Features: datetime, xml, plugins, multipart, tls, colour.

  • pact_verifier: Core provider verification logic (library). Compiled as cdylib + rlib. Features: datetime, xml, plugins, multipart.

  • pact_ffi: C-compatible FFI layer exposing consumer and verifier APIs. Compiled as cdylib, staticlib, and rlib. Uses Rust edition 2021 (differs from other crates, which use 2024).

  • pact_verifier_cli: Command-line tool wrapping pact_verifier. Features include junit output format.

Key Conventions

  • Rust edition: 2024 for all crates except pact_ffi (2021).
  • Minimum Rust version: 1.88.0 (required for edition 2024).
  • Async runtime: tokio throughout (except WASM builds).
  • Logging: tracing / tracing-subscriber (not log).
  • Test helpers: rstest, hamcrest2, expectest, pretty_assertions are common dev-dependencies.
  • Workspace patch: pact_models is patched in rust/Cargo.toml to always use the local path (./pact_models), so changes propagate across all crates without a publish.

Commit Messages

Follow Conventional Changelog format:

  • feat: ... for new features
  • fix: ... for bug fixes
  • chore: ... for maintenance
  • refactor: ... for refactoring

Compatibility Suite

BDD-style integration tests covering V1–V4 spec compliance live in /compatibility-suite/. These use the cucumber framework and run separately from the main workspace tests.

Releasing

Each crate has a release.groovy script that guides the release process and updates changelogs. Releases are published to crates.io and tagged on GitHub. CI builds attach platform binaries to each GH release.