Building Conformance Suites

This guide walks through creating a conformance suite that verifies an implementation against a contract. Conformance suites are reusable — multiple implementations can be tested against the same contract using the same harness.

Prerequisites

You need an initialized lexicon repository with at least one contract. If you haven’t created a contract yet, see the Creating Your First Contract guide.

Generate the Harness

In a lexicon chat session, ask the AI to create conformance tests for your contract. The AI uses the CREATE_CONFORMANCE directive, which:

1. Reads the contract from specs/contracts/key-value-store.toml
2. Infers trait or factory structure from your code
3. Proposes reusable conformance scaffolding
4. Lets you refine the harness conversationally
5. Writes the harness to tests/conformance/key-value-store.rs

Choose a Harness Pattern

Lexicon supports two patterns, configured in .lexicon/manifest.toml:

Trait-Based (Default)

Generates a trait that your implementation must satisfy. Good for testing multiple implementations against the same contract:

pub trait KeyValueStoreConformance {
    type Instance;
    fn create_instance() -> Self::Instance;
}

Factory-Based

Generates a standalone factory function. Simpler when you have a single implementation:

fn create_instance() -> YourType {
    YourType::new()
}

Set the style in your manifest:

[preferences]
conformance_style = "trait_based"  # or "factory_based"

Fill In the Tests

The generated harness contains test stubs for each contract clause:

• Invariants become inv_* test functions
• Required semantics become req_* test functions
• Forbidden semantics become forbid_* test functions

Each test has a comment linking it back to the contract clause. Fill in the assertions:

#[test]
fn inv_get_after_set() {
    let mut store = create_instance();
    store.set("key", "value");
    assert_eq!(store.get("key"), Some("value"));
}

Sync After Contract Changes

When a contract is updated (new invariants, changed semantics), ask the AI in a chat session to regenerate conformance tests. It will add test stubs for new clauses without overwriting your existing test implementations.

Check Coverage

Run lexicon verify to see how many contract clauses are covered by your conformance tests. Missing coverage is surfaced in the score breakdown. Use the COVERAGE_REPORT action in lexicon chat for a detailed view.