Crate chicago_tdd_tools 

Chicago TDD Tools

A comprehensive testing framework for Chicago TDD (Classicist Test-Driven Development) methodology in Rust. Provides fixtures, builders, helpers, and advanced testing capabilities including property-based testing and mutation testing.

Features

• Test Fixtures: Reusable test fixtures with state management and test isolation
• Builders: Fluent builders for test data and workflows
• Assertion Helpers: Comprehensive assertion utilities
• Macros: AAA pattern enforcement and test helpers
• Property-Based Testing: QuickCheck-style random test generation
• Mutation Testing: Test quality validation through mutations
• Coverage Analysis: Test coverage reporting and analysis

Chicago TDD Principles

This framework enforces Chicago TDD principles:

1. State-Based Testing: Tests verify outputs and state, not implementation
2. Real Collaborators: Uses actual dependencies, not mocks
3. Behavior Verification: Tests verify what code does, not how
4. AAA Pattern: All tests follow Arrange-Act-Assert structure

Usage

use chicago_tdd_tools::prelude::*;

    // Arrange: Create fixture
    let fixture = TestFixture::new().unwrap_or_else(|e| panic!("Failed to create fixture: {}", e));

    // Act: Execute test
    let counter = fixture.test_counter();

    // Assert: Verify state
    assert!(counter >= 0);

Module Organization

Modules are organized into capability groups for better discoverability and maintainability:

Core Testing Infrastructure (core)

• fixture: Test fixtures and setup utilities
• async_fixture: Async test fixtures with async traits (requires async feature)
• builders: Fluent builders for test data
• assertions: Assertion helpers and utilities
• macros: Test macros for AAA pattern enforcement and assertions
• state: Type-level AAA enforcement
• poka_yoke: Error prevention through type-level safety (prevents invalid states)
• const_assert: Compile-time assertions
• alert: Alert helpers for visual problem indicators (with optional log crate integration)

Advanced Testing Techniques (testing)

• property: Property-based testing framework
• mutation: Mutation testing framework
• snapshot: Snapshot testing (requires snapshot-testing feature)
• concurrency: Concurrency testing (requires concurrency-testing feature)
• cli: CLI testing (requires cli-testing feature)
• generator: Test code generation

Quality & Validation (validation)

• coverage: Test coverage analysis
• guards: Guard constraint enforcement (MAX_RUN_LEN ≤ 8, MAX_BATCH_SIZE)
• jtbd: Jobs To Be Done validation framework (validates code accomplishes intended purpose)
• performance: RDTSC benchmarking and tick measurement

Telemetry & Observability (observability)

• otel: OTEL span/metric validation (requires otel feature)
• weaver: Weaver live validation integration (requires weaver feature)

Integration Testing (integration)

• testcontainers: Docker container support (requires testcontainers feature)

Backward Compatibility

All modules are re-exported at the crate root for backward compatibility. Existing code using chicago_tdd_tools::fixture::* continues to work. New code is encouraged to use capability group paths: chicago_tdd_tools::core::fixture::*

Macros

The crate provides several macros to reduce boilerplate and enforce Chicago TDD principles:

Procedural Macros

• #[tdd_test]: Procedural macro for zero-boilerplate tests with AAA validation
  • Import: use chicago_tdd_tools::tdd_test; (re-exported) or use chicago_tdd_tools_proc_macros::tdd_test;
• #[fixture]: Procedural macro for automatic fixture setup/teardown
  • Import: use chicago_tdd_tools::fixture; (re-exported) or use chicago_tdd_tools_proc_macros::fixture;
• #[derive(TestBuilder)]: Derive macro for fluent builder generation

Declarative Macros

Root Cause Fix: All macros below are exported with #[macro_export], making them available at the crate root without import. Importing them with use causes “unused import” errors. Use macros directly (e.g., assert_ok!(result)) without importing.

Exception: In nested modules, you may need to use the full path (e.g., chicago_tdd_tools::assert_ok!()) or create a macro wrapper. See tests/testcontainers/tests.rs for an example.

• test!: Enforce AAA pattern for synchronous tests
• async_test!: Enforce AAA pattern for async tests
• fixture_test!: Async test with automatic fixture setup/teardown
• performance_test!: Performance test with tick budget validation
• assert_ok!: Assert Result is Ok with detailed error messages
• assert_err!: Assert Result is Err with detailed error messages
• assert_fail!: Assert function call fails, returning error value for further assertions
• assert_within_tick_budget!: Validate performance constraints (≤8 ticks)
• assert_in_range!: Assert value is within range with detailed messages
• assert_eq_msg!: Assert equality with custom message
• assert_guard_constraint!: Validate guard constraints
• alert_critical!: Emit critical alert (🚨) - must stop immediately
• alert_warning!: Emit warning alert (⚠️) - should stop
• alert_info!: Emit info alert (ℹ️) - informational
• alert_success!: Emit success alert (✅) - operation completed
• alert_debug!: Emit debug alert (🔍) - detailed diagnostics
• alert!: Emit custom alert with user-defined severity

Re-exports

pub use core::assertions::AssertionBuilder;

pub use core::assertions::ValidatedAssertion;

pub use core::builders::GenericTestDataBuilder;

pub use core::builders::ValidatedTestDataBuilder;

pub use operator_registry::global_registry;

pub use operator_registry::GuardType;

pub use operator_registry::OperatorDescriptor;

pub use operator_registry::OperatorProperties;

pub use operator_registry::OperatorRegistry;

pub use sector_stacks::academic;

pub use sector_stacks::claims;

pub use sector_stacks::OperationReceipt;

pub use sector_stacks::OperationStatus;

pub use sector_stacks::SectorOperation;

pub use swarm::ComposedOperation;

pub use swarm::OperationChain;

pub use swarm::SwarmCoordinator;

pub use swarm::SwarmMember;

pub use swarm::TaskReceipt;

pub use swarm::TaskRequest;

pub use swarm::TaskStatus;

pub use validation::coverage::CoveragePercentage;

pub use validation::coverage::CoveredCount;

pub use validation::coverage::TotalCount;

pub use validation::jtbd::ScenarioIndex;

pub use validation::performance::ValidatedTickBudget;

pub use core::alert;

pub use core::assertions;

pub use core::builders;

pub use core::const_assert;

pub use core::fail_fast;

pub use core::fixture;

pub use core::invariants;

pub use core::state;

pub use testing::generator;

pub use testing::mutation;

pub use testing::property;

pub use validation::coverage;

pub use validation::guards;

pub use validation::jtbd;

pub use validation::performance;

Modules

core

Core Testing Infrastructure

integration

Integration Testing

macros

Macros Module

observability

Unified Observability Testing

operator_registry

Operator Registry - Chatman Equation YAWL Patterns

prelude

Prelude module - import everything you need with use chicago_tdd_tools::prelude::*;

sector_stacks

Sector-Grade Reference Stacks

swarm

Swarm Protocol: Distributed Multi-Sector Coordination

testing

Advanced Testing Techniques

validation

Quality & Validation

Macros

alert

Emit an alert with custom severity

alert_critical

Emit a critical alert (🚨)

alert_debug

Emit a debug alert (🔍)

alert_info

Emit an info alert (ℹ️)

alert_success

Emit a success alert (✅)

alert_warning

Emit a warning alert (⚠️)

assert_approx_eq

Assert that two floating-point values are approximately equal

assert_contains

Assert that a collection contains an item

assert_eq_enhanced

Assert equality with automatic type inference and diff output

assert_eq_msg

Assert equality with detailed error message and diff output

assert_err

Assert that a result is an error with detailed message

assert_fail

Assert that a function call fails, returning the error value

assert_guard_constraint

Assert that a guard constraint is satisfied

assert_in_range

Assert that a value is within a range with detailed error message

assert_json_eq

Assert that two JSON values are semantically equal

assert_matches

Assert that a value matches a pattern

assert_not_contains

Assert that a collection does not contain an item

assert_ok

Assert that a result is successful with detailed error message

assert_subset

Assert that one collection is a subset of another

assert_superset

Assert that one collection is a superset of another

assert_within_tick_budget

Assert that a value is within tick budget (≤8 ticks)

async_test

Macro for async tests with AAA pattern enforcement

async_test_with_timeout

Macro for async tests with custom timeout

ensure_invariant

Helper macro for concise invariant checking in phase implementations.

fixture_test

Macro for async tests with automatic fixture setup and teardown

fixture_test_with_timeout

Macro for async tests with fixture and custom timeout

invariant_context

Helper macro to convert a custom error into an InvariantViolation. Ensures no unwrap/expect escape in invariant-critical paths.

otel_test

Macro for OTEL testing (requires otel feature)

param_test

Parameterized test macro (requires parameterized-testing feature)

performance_test

Macro for performance tests with tick budget validation

test

Macro to enforce AAA (Arrange-Act-Assert) pattern

Attribute Macros

fixture

Procedural macro for TDD fixtures

tdd_test

Procedural macro for TDD tests

Derive Macros

TestBuilder

Derive macro for TestBuilder