# JAEB Test Suite Documentation Index
This directory contains comprehensive documentation of the jaeb event bus test suite, created to inform example creation and provide guidance for
feature development.
## Overview
The jaeb crate includes 18 integration test files and 1 benchmark file, totaling approximately 3,500 lines of test code. These tests comprehensively
validate:
- Core event dispatch (sync and async)
- Handler subscription and management
- Error handling and recovery
- Middleware filtering and interception
- Resource management and flow control
- Graceful shutdown and cleanup
- Performance characteristics
## Documentation Files
### 1. **TEST_SUMMARY.md** (Comprehensive Reference)
**Best for:** Detailed understanding of each test file
Contents:
- 18 detailed test file analyses
- Feature coverage for each test
- Code patterns and examples
- Key usage demonstrations
- Benchmark analysis
- Learning path recommendations
**When to use:** Deep dive into specific features or complex patterns
### 2. **TEST_QUICK_REFERENCE.md** (Quick Lookup)
**Best for:** Finding information quickly
Contents:
- Summary table of all test files
- Feature-to-file mapping
- Complexity levels (Beginner/Intermediate/Advanced)
- Execution flow examples
- Error case catalog
- Learning path progression
**When to use:** Quick lookups during development or review
### 3. **TEST_EXPLORATION_SUMMARY.txt** (Executive Summary)
**Best for:** Getting oriented quickly
Contents:
- High-level statistics
- File organization by complexity
- Key usage patterns
- Hidden features (not obvious from API)
- Recommended example topics
- Error types covered
**When to use:** Initial orientation or high-level overview
### 4. **TEST_VISUAL_MAP.txt** (Architecture Visualization)
**Best for:** Understanding system relationships
Contents:
- Visual feature hierarchy
- Test characteristics matrix
- Complexity pyramid
- Code distribution (line count and percentage)
- Error type dependency graph
- Test coverage visualization
**When to use:** Understanding relationships between features or architecture review
## Test File Summary
### By Complexity Level
**Beginner (14 files)**
- `dispatch.rs` - Core async/sync dispatch
- `closure_handlers.rs` - Closure-based handlers
- `builder_validation.rs` - Config validation
- `backpressure.rs` - Flow control
- `clone.rs` - Bus cloning
- `once.rs` - Single-fire listeners
- `unsubscribe.rs` - Dynamic removal
- `subscription_guard.rs` - RAII cleanup
- `named_subscriptions.rs` - Handler naming
- `introspection.rs` - Stats & observability
- `test_utils.rs` - Testing utilities
- `semaphore.rs` - Concurrency limits
- Additional foundational tests
**Intermediate (3 files)**
- `retry.rs` - Retry strategies and backoff
- `dead_letter.rs` - Failure diagnostics
- `shutdown.rs` - Graceful termination
- `panic_safety.rs` - Panic isolation
**Advanced (2 files)**
- `middleware.rs` - Complex interceptor pipeline
- `snapshot.rs` - Internal architecture validation
### By Feature Domain
**Core Dispatch**
- `dispatch.rs` - Basic handler execution
- `closure_handlers.rs` - Alternative patterns
**Error Handling**
- `retry.rs` - Retry policies
- `dead_letter.rs` - Dead-letter queues
- `panic_safety.rs` - Panic isolation
**Advanced Features**
- `middleware.rs` - Event filtering
- `snapshot.rs` - Internal slots
**Lifecycle**
- `shutdown.rs` - Termination
- `once.rs` - Single-fire
- `unsubscribe.rs` - Removal
- `subscription_guard.rs` - RAII
**Resource Management**
- `backpressure.rs` - Flow control
- `semaphore.rs` - Concurrency
- `clone.rs` - State sharing
**Observability**
- `introspection.rs` - Metrics
- `named_subscriptions.rs` - Names
**Testing**
- `test_utils.rs` - TestBus
## File Locations
```
Repository Root: /home/linket/Development/Private/jaeb/
Test Files:
tests/
dispatch.rs
closure_handlers.rs
backpressure.rs
builder_validation.rs
clone.rs
retry.rs
dead_letter.rs
middleware.rs
shutdown.rs
snapshot.rs
introspection.rs
once.rs
unsubscribe.rs
subscription_guard.rs
named_subscriptions.rs
panic_safety.rs
semaphore.rs
test_utils.rs
Benchmarks:
benches/
throughput.rs
Documentation:
TEST_SUMMARY.md
TEST_QUICK_REFERENCE.md
TEST_EXPLORATION_SUMMARY.txt
TEST_VISUAL_MAP.txt
TEST_DOCUMENTATION_INDEX.md (this file)
```
## Key Patterns Demonstrated
### Handler Patterns
- **Trait-based:** `EventHandler<E>` and `SyncEventHandler<E>`
- **Closure-based:** Type-erased closures with inference
- **Mixed types:** Both sync and async on same event
### Subscription Patterns
- **Standard:** `subscribe(handler)`
- **Once:** `subscribe_once(handler)`
- **With policy:** `subscribe_with_policy(handler, policy)`
- **Guard:** `.into_guard()` for RAII
- **Dead-letter:** `subscribe_dead_letters(handler)`
### Publishing Patterns
- **Blocking:** `bus.publish(event).await`
- **Non-blocking:** `bus.try_publish(event)`
- **Cloned bus:** `let bus2 = bus.clone()`
### Failure Handling
- **Retries:** Fixed, Exponential, ExponentialWithJitter
- **Dead letters:** Full metadata + original event
- **Recursion guard:** Prevents infinite loops
### Advanced Features
- **Middleware:** Global/typed, sync/async, ordered
- **Snapshots:** Per-type dispatch slots with FIFO
- **Stats:** Handler names, in-flight counts
- **Shutdown:** Timeout-based termination
## Recommended Example Topics
Based on test coverage, create examples for:
1. **hello-world.rs** - Minimal publish/subscribe
2. **closures.rs** - Lambda-based handlers
3. **error-handling.rs** - Retry + dead-letter patterns
4. **middleware-pipeline.rs** - Event filtering
5. **graceful-shutdown.rs** - Timeout handling
6. **testing-integration.rs** - TestBus usage
7. **backpressure.rs** - Flow control
8. **load-limiting.rs** - Concurrency limits
## Feature Coverage Checklist
### Dispatch
- [x] Async handler execution
- [x] Sync handler execution
- [x] Multi-handler fanout
- [x] Type-based routing
### Handlers
- [x] Struct-based handlers
- [x] Sync closures
- [x] Async closures
- [x] Mixed handler types
### Publishing
- [x] Blocking publish
- [x] Non-blocking try_publish
- [x] Publishing with no listeners
- [x] Multiple concurrent publishers
### Failure Handling
- [x] Fixed retry strategy
- [x] Exponential backoff
- [x] Jittered exponential backoff
- [x] Dead-letter queue
- [x] Failure metadata
- [x] Recursion prevention
### Middleware
- [x] Global sync middleware
- [x] Global async middleware
- [x] Typed sync middleware
- [x] Typed async middleware
- [x] Middleware ordering (FIFO)
- [x] Event rejection
### Lifecycle
- [x] Single-fire subscriptions
- [x] Dynamic unsubscribe
- [x] RAII cleanup guards
- [x] Graceful shutdown
- [x] Shutdown timeout
- [x] Task draining
### Resource Management
- [x] Bounded queue capacity
- [x] Backpressure handling
- [x] Async concurrency limits
- [x] Bus cloning (Arc sharing)
### Observability
- [x] Runtime statistics
- [x] Handler naming
- [x] In-flight task tracking
- [x] Per-type metrics
### Safety
- [x] Panic isolation
- [x] Concurrent publish/unsubscribe
- [x] Safe handler failures
- [x] Proper error propagation
## Testing Approach
The test suite uses:
- **Atomic counters** for verification (no runtime overhead)
- **Tokio barriers** for concurrent testing
- **Time measurement** for performance validation
- **Arc/Mutex** for test coordination
- **Notify** for event signaling
- **Strategic sleeps** to create backpressure
## Build & Run Commands
```bash
# Run all tests
cargo test --all
# Run specific test file
cargo test --test dispatch
# Run specific test
cargo test --test dispatch -- sync_handler
# Run with output
cargo test --all -- --nocapture
# Run benchmarks
cargo bench
# Run with feature flags
cargo test --features test-utils
```
## Next Steps
1. **Review** - Start with TEST_QUICK_REFERENCE.md
2. **Deep Dive** - Read TEST_SUMMARY.md for patterns
3. **Visualize** - Check TEST_VISUAL_MAP.txt for architecture
4. **Reference** - Use TEST_EXPLORATION_SUMMARY.txt for guidance
5. **Implement** - Create examples following the progression
6. **Test** - Verify against corresponding test files
## Document Maintenance
These documents are generated from the current test suite. When new tests are added or existing tests modified:
1. Review the TEST_SUMMARY.md for accuracy
2. Update feature coverage as needed
3. Check test counts in TEST_EXPLORATION_SUMMARY.txt
4. Verify test file groupings in TEST_VISUAL_MAP.txt
5. Update complexity levels in TEST_QUICK_REFERENCE.md
---
**Last Updated:** 2026-04-10
**Test Suite Version:** Latest
**Total Coverage:** 18 test files + 1 benchmark = ~3,500 lines