Conformance Suites

Conformance suites are test harnesses generated from contracts. They translate your contract’s invariants, required semantics, and forbidden semantics into Rust test functions that you fill in with real assertions.

The core idea: make conformance suites reusable. Lexicon guides you toward reusable structure, not scattered ad hoc tests. Multiple implementations can be tested against the same contract, and the harness logic is shared.

The generated approach supports:

• shared harness logic — common setup and assertions
• implementation adapters — each implementation provides a factory or trait impl
• fixture reuse — test data and setup shared across implementations
• table-driven cases — where appropriate for systematic coverage
• extension points — for implementation-specific behavior beyond the contract
• separation between required contract tests and optional implementation tests

Harness Patterns

Lexicon supports two conformance styles, configured in the manifest preferences:

Trait-Based (Default)

The trait-based pattern generates a trait that your implementation must satisfy:

//! Conformance harness for contract: Key-Value Store
//! Contract ID: key-value-store
//!
//! This file is generated by lexicon. Do not edit the trait definition.
//! Implement the trait for your type and run the conformance tests.

pub trait KeyValueStoreConformance {
    type Instance;

    fn create_instance() -> Self::Instance;
}

#[cfg(test)]
mod key_value_store_conformance {
    use super::*;

    /// Invariant: A key set with a value must return that value on get
    #[test]
    fn inv_get_after_set() {
        // TODO: Implement test for invariant
        // let instance = T::create_instance();
    }

    /// Required: get(key) returns None for missing keys
    #[test]
    fn req_missing_key() {
        // TODO: Implement test for required semantic
    }

    /// Forbidden: Must not panic on missing key lookup
    #[test]
    fn forbid_panic_on_missing() {
        // TODO: Verify forbidden behavior does not occur
    }
}

The trait defines a create_instance() method. You implement the trait for your type and fill in the test bodies.

Factory-Based

The factory-based pattern uses a standalone factory function instead of a trait:

//! Factory-based conformance harness for contract: Key-Value Store
//! Contract ID: key-value-store
//!
//! This file is generated by lexicon. Implement `create_instance()`.

/// Create an instance of the implementation under test.
///
/// Replace the return type and body with your actual implementation.
fn create_instance() -> () {
    // TODO: Return your implementation instance
    ()
}

#[cfg(test)]
mod key_value_store_conformance {
    use super::*;

    /// Invariant: A key set with a value must return that value on get
    #[test]
    fn inv_get_after_set() {
        let _instance = create_instance();
        // TODO: Verify invariant
    }

    /// Required: get(key) returns None for missing keys
    #[test]
    fn req_missing_key() {
        let _instance = create_instance();
        // TODO: Verify required semantic
    }

    /// Forbidden: Must not panic on missing key lookup
    #[test]
    fn forbid_panic_on_missing() {
        let _instance = create_instance();
        // TODO: Verify does NOT occur
    }
}

How Generation Works

The generator reads a Contract and produces test code:

1. Invariants become test functions prefixed with the invariant ID (kebab-case converted to snake_case)
2. Required semantics become test functions that verify the behavior exists
3. Forbidden semantics become test functions that verify the behavior does NOT occur
4. Test tags on semantics link back to contract IDs for traceability

Conformance and the Verification Pipeline

Conformance coverage feeds directly into the scoring and verification systems. Each contract clause can reference tests or test tags, and lexicon verify checks how many contract clauses are exercised by tests. Missing coverage is surfaced in the score breakdown and via the COVERAGE_REPORT action in chat.

This means the system can tell you not just whether tests pass, but whether your tests actually cover what the contract requires.

Configuring Conformance Style

Set the style in .lexicon/manifest.toml under preferences:

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

Adding Conformance Suites

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

1. Inspect the contract artifacts
2. Infer trait/factory/test harness structure from your code
3. Propose reusable conformance scaffolding
4. Let you refine it conversationally
5. Optionally improve harness completeness
6. Preserve the distinction between stable conformance obligations, generated starter tests, and optional/advisory tests

The generated harness code is placed at tests/conformance/<contract-id>.rs.