Rust testing framework enforcing Chicago-style TDD (Classicist Test-Driven Development) through compile-time guarantees.
If it compiles, correctness follows. Type system encodes invariants. Quality is the default, not an afterthought.
Chicago-style TDD (Classicist approach) focuses on behavior verification using real collaborators instead of mocks. This framework enforces that philosophy through Rust's type system:
- Type-First Design: Compiler prevents invalid test states before runtime. State machines encoded at type levelβif your test compiles, the AAA (Arrange-Act-Assert) pattern is enforced.
- Error Prevention (Poka-Yoke): Mistakes caught at compile time, not in CI. No
.unwrap()in production code. Nopanic!(). Git hooks prevent them from being committed. - Zero-Cost Abstractions: All safety guarantees compiled awayβperformance equals unsafe manual code.
- 80/20 Focus: Framework solves 80% of testing problems with 20% extra effort via generics, const generics, and macros.
Result: Tests that actually verify behavior. Bugs prevented before code review. Production panic rate: ~zero.
# Install cargo-make (required)
cargo install cargo-make
# Create test file: tests/my_first_test.rs
mkdir -p tests
cat > tests/my_first_test.rs << 'EOF'
use chicago_tdd_tools::prelude::*;
test!(test_addition, {
// Arrange
let x = 5;
let y = 3;
// Act
let result = x + y;
// Assert
assert_eq!(result, 8);
});
async_test!(test_async_example, {
let result = async { 5 + 3 }.await;
assert_eq!(result, 8);
});
fixture_test!(test_with_fixture, fixture, {
let counter = fixture.test_counter();
assert!(counter >= 0);
});
EOF
# Run tests
cargo make testβ Installation complete when cargo make test shows 3 passing tests.
# Browse working examples (18 included, all tested)
ls examples/
# Run a specific example
cargo run --example basic_test
cargo run --example fail_fast_verification
cargo run --example sector_stacks_workflowsπ Complete examples guide: See examples/README.md for all 18 examples organized by category.
cargo make docs # Generate and open RustdocSee Integration Testing section below.
See Observability & Weaver section below.
Synchronous tests (no async runtime needed):
use chicago_tdd_tools::prelude::*;
test!(test_sync_behavior, {
// Arrange: Set up test data
let input = vec![1, 2, 3, 4, 5];
// Act: Execute code under test
let sum: i32 = input.iter().sum();
// Assert: Verify behavior
assert_eq!(sum, 15);
});Async tests (1s default timeout):
async_test!(test_async_operation, {
// Arrange
let data = async { vec![1, 2, 3] }.await;
// Act: Run async code
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
let result = data.len();
// Assert
assert_eq!(result, 3);
});Fixture-based tests (automatic setup/teardown):
fixture_test!(test_with_fixture_isolation, fixture, {
// Arrange: Fixture created automatically, isolated per test
let counter = fixture.test_counter();
// Act: Use fixture
let incremented = counter + 1;
// Assert
assert!(incremented > counter);
// Cleanup: Automatic on scope exit
});Performance tests (tick budget validation):
performance_test!(test_performance_constraint, {
// Arrange
let work = || {
let mut sum = 0;
for i in 0..100 {
sum += i;
}
sum
};
// Act
let result = work();
// Assert within tick budget (default: β€8 ticks)
assert_within_tick_budget!(result > 0);
});Result type assertions:
test!(test_result_assertions, {
let success: Result<i32, String> = Ok(42);
let failure: Result<i32, String> = Err("oops".to_string());
// Assert success case
assert_ok!(success);
assert_eq!(success.unwrap_or(0), 42);
// Assert error case with detailed messages
assert_err!(failure);
assert_in_range!(success.unwrap_or(0), 40, 50);
// Custom assertion messages
assert_eq_msg!(success.unwrap_or(0), 42, "Expected 42, got: {:?}", success);
});Zero-tolerance execution context with 12-phase verification pipeline:
use chicago_tdd_tools::core::fail_fast::*;
test!(test_fail_fast_verification, {
// Arrange: Create strict execution context
let mut ctx = StrictExecutionContext::new("contract-123")?;
// Act: Execute phases with fail-fast semantics
ctx.phase_1_contract_definition(12)?;
ctx.phase_2_thermal_testing(5, 8)?; // Ο β€ 8 enforced
// Any violation causes immediate failure
match ctx.phase_2_thermal_testing(10, 8) {
Ok(PhaseResult::Violation(v)) => {
panic!("Thermal bound exceeded: {}", v);
}
_ => {}
}
});Key features:
- 47 invariant violations covering all failure modes
- 12 distinct phases from Contract Definition to Quality Dashboard
- Self-validating receipts with version and checksum
- No degradation, no warnings ignored, no partial success
π Example: See examples/fail_fast_verification.rs
Production-grade implementations demonstrating the Chatman Equation in real-world workflows:
use chicago_tdd_tools::sector_stacks::academic::*;
test!(test_academic_workflow, {
// Arrange: Create paper submission
let paper = PaperSubmission {
paper_id: "paper-001".to_string(),
title: "Advanced Testing".to_string(),
authors: vec!["Dr. Smith".to_string()],
abstract_text: "Abstract...".to_string(),
file_size_bytes: 500_000,
};
// Act: Process through workflow
let operation = AcademicOperation::new(paper.clone(), vec![]);
let assignment = operation.assign_reviewers();
// Collect reviews
let reviews = vec![/* ... */];
let operation = AcademicOperation::new(paper, reviews);
// Assert: Generate receipt
let receipt = operation.generate_receipt(OperationStatus::Success);
assert_eq!(receipt.sector, "Academic");
});Available sectors:
- Academic Publishing: Paper review lifecycle with deterministic decision algorithms
- Enterprise Claims: Insurance claims processing with fraud detection and settlement
π Example: See examples/sector_stacks_workflows.rs
Ontologies as single source of truth for workflow validation:
use chicago_tdd_tools::sector_stacks::rdf::*;
test!(test_rdf_validation, {
// Arrange: Create ontology
let mut ontology = SectorOntology::new("Academic".to_string());
ontology.add_stage(WorkflowStage {
id: "submission".to_string(),
name: "Submission".to_string(),
stage_number: 1,
is_deterministic: true,
max_latency_seconds: 60,
});
// Act: Validate operations
let validator = RdfOperationValidator::new().with_ontology(ontology);
let result = validator.validate_operation_defined("submission");
// Assert
assert!(result.is_ok());
});π Example: See examples/rdf_validation.rs
Distributed multi-sector coordination with task receipts:
use chicago_tdd_tools::swarm::*;
test!(test_swarm_coordination, {
// Arrange: Create coordinator
let mut coordinator = SwarmCoordinator::new();
coordinator.register_member(
SwarmMember::new("agent-1".to_string(), "Agent 1".to_string())
.with_sector("Academic".to_string())
.with_capacity(10),
);
// Act: Submit and distribute task
coordinator.submit_task(TaskRequest::new(
"task-001".to_string(),
"Academic".to_string(),
"desk-review".to_string(),
"paper-123".to_string(),
));
let (task_id, member_id) = coordinator.distribute_next_task()?;
// Assert
assert_eq!(task_id, "task-001");
});π Example: See examples/swarm_coordination.rs
Generate random test data and verify properties hold for all inputs:
use chicago_tdd_tools::property::*;
test!(test_commutativity_property, {
// Arrange: Create property test generator
let mut generator = PropertyTestGenerator::<100, 5>::new().with_seed(42);
// Generate random test data
let test_data = generator.generate_test_data();
// Act & Assert: Verify property holds for all generated data
for _item in test_data {
// Property: a + b == b + a (commutativity)
let a = rand::random::<u32>();
let b = rand::random::<u32>();
assert_eq!(a + b, b + a, "Addition is commutative");
}
});With proptest (requires property-testing feature):
test!(test_distributivity_with_proptest, {
use proptest::prelude::*;
let strategy = ProptestStrategy::new().with_cases(100);
// Test: a * (b + c) == (a * b) + (a * c)
strategy.test(
proptest::prelude::any::<(u32, u32, u32)>(),
|(a, b, c)| a * (b + c) == (a * b) + (a * c)
);
});When to use: Edge cases are hard to imagine. Random generation finds them automatically.
Verify test quality by intentionally breaking code and checking tests catch it:
use chicago_tdd_tools::mutation::*;
use std::collections::HashMap;
test!(test_mutation_detection, {
// Arrange: Create mutation tester with test data
let mut data = HashMap::new();
data.insert("key1", "value1");
let mut tester = MutationTester::new(data);
// Act: Apply mutation (remove a key)
tester.apply_mutation(MutationOperator::RemoveKey("key1".to_string()));
// Assert: Test should fail because we removed data
let mutated = tester.current_data();
assert!(mutated.is_empty(), "Mutation was not caught!");
// Calculate mutation score
let score = MutationScore::calculate(95, 100); // 95 mutations caught of 100
assert!(score.is_acceptable(), "Score: {}%", score.score());
});Mutation operators: RemoveKey, AddKey, ChangeValue, NegateCondition
Target: β₯80% mutation score indicates thorough test coverage.
Verify complex outputs (JSON, HTML, serialized data) don't change unexpectedly:
test!(test_snapshot_comparison, {
use insta::assert_snapshot; // Requires snapshot-testing feature
let data = serde_json::json!({
"user": "alice",
"status": "active"
});
// Assert snapshot matches expected output
assert_snapshot!(data.to_string());
// Workflow:
// 1. First run: creates snapshot file
// 2. Second run: compares against snapshot
// 3. Change output? Update snapshot with: cargo make snapshot-accept
});Snapshot management:
cargo make snapshot-review # Review changes
cargo make snapshot-accept # Accept new snapshots
cargo make snapshot-reject # Reject and revertDetect race conditions with deterministic thread-safe testing:
test!(test_concurrent_safety, {
use chicago_tdd_tools::concurrency::*;
// Arrange: Use loom for deterministic testing
loom::model(|| {
let data = std::sync::Arc::new(std::sync::Mutex::new(0));
let data_clone = data.clone();
// Act: Spawn thread accessing shared data
let handle = loom::thread::spawn(move || {
let mut guard = data_clone.lock().unwrap();
*guard += 1;
});
// Verify no panics (loom exhaustively tests interleavings)
handle.join().unwrap();
});
});Test command-line interfaces like they're black boxes:
test!(test_cli_invocation, {
use chicago_tdd_tools::testing::cli::*;
// Arrange: Prepare CLI test
let mut cli_test = CliTest::new("my-cli-tool");
// Act: Run command
let output = cli_test
.arg("--help")
.run()
.expect("CLI should run");
// Assert: Check output
assert!(output.stdout.contains("Usage:"));
assert_eq!(output.exit_code, 0);
});Test with real services (Postgres, Redis, etc.) without manual Docker commands:
fixture_test!(test_with_postgres, fixture, {
use chicago_tdd_tools::integration::testcontainers::*;
// Arrange: Fixture automatically spins up Postgres container
let container = fixture.postgres_container()
.expect("Postgres container should start");
// Get connection string
let conn_string = container.connection_string();
println!("Connected to: {}", conn_string);
// Act: Execute query
let result = container.execute_query(
"SELECT count(*) FROM pg_tables;"
).await;
// Assert: Verify result
assert_ok!(result);
// Cleanup: Container automatically stopped on fixture drop
});Enable with:
[dev-dependencies]
chicago-tdd-tools = { path = "../chicago-tdd-tools", features = ["testcontainers"] }Run with:
cargo make test-integration # Requires Docker runningTest OpenTelemetry (OTEL) instrumentation and semantic convention compliance with Weaver live-check.
# Download Weaver CLI + semantic convention registry
cargo make weaver-bootstrap
# This creates:
# - target/<profile>/weaver (executable)
# - registry/ (semantic conventions)# Verify Weaver works + send test span
cargo make weaver-smoke
# Output: Weaver version + telemetry validationuse chicago_tdd_tools::observability::otel::*;
test!(test_otel_span_validation, {
// Arrange: Create OTEL span context
let trace_id = TraceId::new(12345);
let span_id = SpanId::new(67890);
let context = SpanContext::new(trace_id, span_id);
// Act: Create span with attributes
let span = Span::new("http.request", context)
.with_attribute("http.method", "GET")
.with_attribute("http.url", "https://example.com");
// Assert: Validate span structure
assert_eq!(span.name(), "http.request");
assert!(span.has_attribute("http.method"));
});Validates spans/metrics against OpenTelemetry semantic conventions in real-time:
fixture_test!(test_weaver_live_check, fixture, {
use chicago_tdd_tools::observability::weaver::*;
// Arrange: Create Weaver validator (requires weaver feature + bootstrap)
let weaver = fixture.weaver_instance()
.expect("Weaver should initialize");
// Act: Send OTEL span
let span = create_http_span("GET", "/api/users");
send_otel_span(span.clone());
// Assert: Validate against semantic conventions
let result = weaver.validate_span("http.request", &span);
assert_ok!(result, "Span should comply with semantic conventions");
});Enable with:
[dev-dependencies]
chicago-tdd-tools = {
path = "../chicago-tdd-tools",
features = ["weaver", "otel"] # otel auto-enabled with weaver
}Run integration tests:
cargo make test-integration # Includes Weaver tests
# Or skip if Docker unavailable:
WEAVER_ALLOW_SKIP=1 cargo make test-integrationcargo make, never raw cargo:
cargo make check # Compilation check (fast)
cargo make test # Unit tests only
cargo make test-unit # Same as test
cargo make test-integration # Integration tests (Docker, Weaver)
cargo make test-all # Unit + integration
cargo make lint # Clippy checks
cargo make fmt # Code formatting
cargo make pre-commit # fmt + lint + unit tests (always run before commit)
cargo make ci-local # Simulate full CI pipelineWhy mandatory?
- Handles proc-macro crates correctly
- Enforces timeouts (prevents hanging)
- Consistent build environment
- Single source of truth for build process
Essential for safety:
cargo make install-hooks # Install git hooks that prevent unwrap/expect in productionType-level AAA enforcement: If test compiles, AAA pattern is correct.
Sealed traits: Can't create invalid test states.
Const assertions: Size and alignment checked at compile time.
Git hooks: Prevent .unwrap(), .expect(), panic!() from being committed.
Clippy enforcement: All warnings treated as errors (-D warnings).
Timeout SLAs enforced:
- Quick checks: 5s (fmt, check)
- Compilation: 5-30s depending on profile
- Lint: 300s (CI cold-start)
- Unit tests: 1s per test
- Integration tests: 30s with Docker
- Coverage: 30s
Result-based errors: No panics in production code.
// β Never in production
let value = result.unwrap();
// β
Always do this
let value = result?; // Propagate errors
// OR
let value = match result {
Ok(v) => v,
Err(e) => { alert_warning!("Failed: {}", e); default_value }
};Alert macros for structured logging:
alert_critical!("Database unreachable"); // π¨ Must stop
alert_warning!("Retry attempt {}", n); // β οΈ Should stop
alert_info!("Processing {} items", count); // βΉοΈ Informational
alert_success!("Backup complete"); // β
Success
alert_debug!("State: {:?}", state); // π Diagnostics| Risk | Original | Current | Mitigation |
|---|---|---|---|
| Production panics (unwrap/expect) | RPN 180 | RPN 36 | Git hooks, CI checks, lint deny |
| Tests pass locally, fail CI | RPN 105 | RPN 21 | Multi-OS, pre-commit simulation |
| Clippy warnings accumulate | RPN 112 | RPN 11 | CI enforcement, pre-commit |
| Flaky tests | RPN 120 | RPN 24 | Retry logic (3x), test isolation |
| Coverage regressions | RPN 336 | RPN 67 | Coverage tracking, Codecov |
Core (always available): test!, async_test!, fixture_test!, builders, assertions
Enable as needed:
[dev-dependencies]
chicago-tdd-tools = {
path = "../chicago-tdd-tools",
features = [
"testing-extras", # property-testing + snapshot-testing + fake data (most common)
"otel", # OpenTelemetry span/metric validation
"weaver", # Weaver semantic convention live-check (implies otel)
"testcontainers", # Docker container support
"async", # Async fixture providers (Rust 1.75+)
]
}Recommended bundles:
- 80% use case:
["testing-extras"](property + snapshot + fake data) - Full testing:
["testing-extras", "testcontainers"] - With observability:
["testing-extras", "otel", "weaver"] - Everything:
["testing-extras", "otel", "weaver", "testcontainers", "async"]
- Getting Started - Installation, first test, troubleshooting
- Quick Guide - Essential patterns (80% of use cases, 15 min read)
- User Guide - Comprehensive usage (deep dive, 1 hour)
- Weaver Live-Check - Full OTEL + Weaver setup
- CLI Testing Guide - Test command-line tools
- Observability Testing - OTEL testing patterns
- Timeout Enforcement - Custom timeout SLAs
- API Reference - Complete API documentation
- Architecture - Design principles, module organization
- SLA Reference - Service level agreements, quality standards
- SPR Guide - Elite Rust standards, best practices
- Code Review Checklist - What reviewers look for
- FMEA: Tests, Build, Actions - Risk analysis, improvements
- Test Isolation Guide - Preventing test interdependencies
- Pattern Cookbook - Alexander-style patterns (20 documented)
Problem: "command not found: cargo-make"
- Fix:
cargo install cargo-make
Problem: "cannot find macro 'test!'"
- Fix: Add
use chicago_tdd_tools::prelude::*;to your test file
Problem: "feature 'X' is required for module Y"
- Fix: Enable feature in
Cargo.toml:features = ["feature-name"]
Problem: Tests pass locally but fail in CI
- Fix: Run
cargo make ci-localto simulate CI environment
More help: See Getting Started - Troubleshooting
18 complete, runnable examples are included, all with tests. Browse them:
# List examples
ls examples/
# Run an example
cargo run --example basic_test
cargo run --example fail_fast_verification
cargo run --example sector_stacks_workflows
cargo run --example rdf_validation
cargo run --example swarm_coordination
cargo run --example operator_registryπ Complete examples guide: See examples/README.md for full documentation.
Example categories:
Tutorials (Learning-oriented):
basic_test.rs- Fixtures, builders, assertionsmacro_examples.rs- Test/assertion macrossector_stacks_workflows.rs- Production-grade workflows (v1.4.0)
How-To Guides (Task-oriented):
property_testing.rs- Random test generation, propertiesmutation_testing.rs- Test quality validationsnapshot_testing.rs- Output comparison (enhanced in v1.4.0)concurrency_testing.rs- Thread safety with loomcli_testing.rs- Command-line testingtestcontainers_example.rs- Docker integrationotel_weaver_testing.rs- Observability testingfail_fast_verification.rs- 12-phase verification pipeline (v1.4.0)rdf_validation.rs- RDF-driven validation (v1.4.0)swarm_coordination.rs- Distributed coordination (v1.4.0)
Explanation (Understanding-oriented):
go_extra_mile.rs- 1st/2nd/3rd idea progression, 80/20 thinkingadvanced_features.rs- Type-level guarantees, zero-cost abstractions
Reference:
operator_registry.rs- Pattern registration and guard system (v1.4.0)all_phases_pipeline.rs- Complete 12-phase pipeline demonstrationhyper_advanced_microkernel.rs- Hyper-advanced ΞΌ-kernel features
| Component | Minimum | Verify | Install |
|---|---|---|---|
| Rust | 1.70 | rustc --version |
rustup |
| Cargo | Latest stable | cargo --version |
Included with Rust |
| cargo-make | Latest | cargo make --version |
cargo install cargo-make |
| Tokio | 1.0+ | (add to Cargo.toml) | tokio |
| Docker* | Latest | docker ps |
Docker Desktop |
| Rust 1.75+* | For async fixtures | rustc --version |
rustup update stable |
* Optionalβonly needed for specific features (Docker, async fixtures)
- Issues/Questions: GitHub Issues
- Documentation Feedback: Create issue with
[docs]tag - Code Contributions: Follow Code Review Checklist
MIT
# Development
cargo make pre-commit # Format + lint + test (before every commit)
cargo make ci-local # Simulate full CI pipeline
# Testing
cargo make test # Unit tests (fast)
cargo make test-all # Unit + integration
cargo make test-property # Property-based tests
cargo make test-mutation # Mutation testing
cargo make test-snapshot # Snapshot tests
# Observability
cargo make weaver-bootstrap # Setup Weaver (once)
cargo make weaver-smoke # Verify Weaver works
cargo make test-integration # Full integration tests
# Code Quality
cargo make lint # Clippy checks (strict)
cargo make fmt # Code formatting
cargo make coverage # Test coverage report
cargo make docs # Generate & open Rustdoc
# Build
cargo make check # Compilation check
cargo make build # Debug binary
cargo make build-release # Optimized binaryProduction-Grade Verification Infrastructure:
- π‘οΈ Fail-Fast Hardening - 47 invariant violations, zero-tolerance execution with 12-phase verification pipeline
- π DMAIC Workflow Integration - Define-Measure-Analyze-Improve-Control methodology with exponential backoff retry logic
- π Sector-Grade Reference Stacks - Academic publishing & claims processing workflows with deterministic operations
- π RDF Integration - Ontologies as single source of truth for workflow validation
- π Operator Registry - Global pattern registration with guard system and constraint enforcement
- π Swarm Protocol - Distributed multi-sector coordination with task receipts and state machines
- πΈ Enhanced Snapshot Testing - Better fixtures and organization with graceful degradation
Latest Improvements (Post v1.4.0):
- β Weaver + Testcontainers Hardening - Registry health checks with 5-second timeout, exponential backoff for container startup
- β OTEL Validation Refinement - Graceful degradation when registry schema has validation issues
- β Integration Test Reliability - 28/28 tests passing, zero timeouts on infrastructure checks
- β Lint & Production Safety - 0 clippy warnings, zero unwrap/expect in production code, all test code properly allowed
- β Pre-Push Validation - Comprehensive 6-gate validation system preventing bad code from reaching remote
100% backward compatible with v1.3.0. Upgrade with confidence.
π Documentation:
- Release Notes - Complete feature documentation
- GitHub Release - GitHub release notes
- Changelog - Full change history
- Release Checklist - Pre-release verification
Next Step: Follow the Quick Start path that matches your need, or jump to Learning Path for structured learning.
Questions? See Troubleshooting or check Getting Started.