thread-flow 0.1.0

<!--
SPDX-FileCopyrightText: 2026 Knitli Inc.

SPDX-License-Identifier: MIT OR Apache-2.0
-->

─────┬──────────────────────────────────────────────────────────────────────────
     │ STDIN
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ # Testing Guide - Thread Flow Crate
   2 │ 
   3 │ Comprehensive guide for running, writing, and maintaining tests for the Thread Flow crate.
   4 │ 
   5 │ ## Table of Contents
   6 │ 
   7 │ 1. [Quick Start](#quick-start)
   8 │ 2. [Test Organization](#test-organization)
   9 │ 3. [Running Tests](#running-tests)
  10 │ 4. [Writing Tests](#writing-tests)
  11 │ 5. [Code Coverage](#code-coverage)
  12 │ 6. [Performance Testing](#performance-testing)
  13 │ 7. [Continuous Integration](#continuous-integration)
  14 │ 8. [Troubleshooting](#troubleshooting)
  15 │ 
  16 │ ---
  17 │ 
  18 │ ## Quick Start
  19 │ 
  20 │ ### Prerequisites
  21 │ 
  22 │ ```bash
  23 │ # Rust toolchain (already installed if you can build the project)
  24 │ rustc --version
  25 │ 
  26 │ # Install cargo-nextest (recommended test runner)
  27 │ cargo install cargo-nextest
  28 │ 
  29 │ # Install coverage tool (optional)
  30 │ cargo install cargo-llvm-cov
  31 │ ```
  32 │ 
  33 │ ### Run All Tests
  34 │ 
  35 │ ```bash
  36 │ # Using cargo (standard)
  37 │ cargo test -p thread-flow --all-features
  38 │ 
  39 │ # Using nextest (faster, better output)
  40 │ cargo nextest run -p thread-flow --all-features
  41 │ 
  42 │ # Run in release mode (for performance tests)
  43 │ cargo test -p thread-flow --all-features --release
  44 │ ```
  45 │ 
  46 │ ### Expected Output
  47 │ 
  48 │ ```
  49 │ running 86 tests
  50 │ test result: ok. 86 passed; 0 failed; 1 ignored
  51 │ Execution time: ~75 seconds
  52 │ ```
  53 │ 
  54 │ ---
  55 │ 
  56 │ ## Test Organization
  57 │ 
  58 │ ### Directory Structure
  59 │ 
  60 │ ```
  61 │ crates/flow/
  62 │ ├── src/
  63 │ │   ├── lib.rs                    # Unit tests (inline)
  64 │ │   ├── cache.rs                  # Cache module tests
  65 │ │   ├── registry.rs               # Registry tests
  66 │ │   └── batch.rs                  # Batch processing tests
  67 │ ├── tests/
  68 │ │   ├── integration_tests.rs      # 18 integration tests
  69 │ │   ├── type_system_tests.rs      # 14 type safety tests
  70 │ │   ├── performance_regression_tests.rs  # 13 performance tests
  71 │ │   └── error_handling_tests.rs   # 27 error handling tests
  72 │ └── TESTING.md                     # This file
  73 │ ```
  74 │ 
  75 │ ### Test Categories
  76 │ 
  77 │ | Category | Location | Count | Purpose |
  78 │ |----------|----------|-------|---------|
  79 │ | **Unit Tests** | \`src/*.rs\` | 14 | Module-level functionality |
  80 │ | **Integration Tests** | \`tests/integration_tests.rs\` | 18 | End-to-end workflows |
  81 │ | **Type System Tests** | \`tests/type_system_tests.rs\` | 14 | Serialization integrity |
  82 │ | **Performance Tests** | \`tests/performance_regression_tests.rs\` | 13 | Performance baselines |
  83 │ | **Error Handling Tests** | \`tests/error_handling_tests.rs\` | 27 | Edge cases & failures |
  84 │ 
  85 │ ---
  86 │ 
  87 │ ## Running Tests
  88 │ 
  89 │ ### Basic Commands
  90 │ 
  91 │ #### Run All Tests
  92 │ ```bash
  93 │ cargo test -p thread-flow --all-features
  94 │ ```
  95 │ 
  96 │ #### Run Specific Test Suite
  97 │ ```bash
  98 │ # Unit tests only (in src/)
  99 │ cargo test -p thread-flow --lib --all-features
 100 │ 
 101 │ # Integration tests
 102 │ cargo test -p thread-flow --test integration_tests --all-features
 103 │ 
 104 │ # Error handling tests
 105 │ cargo test -p thread-flow --test error_handling_tests --all-features
 106 │ 
 107 │ # Performance tests (release mode recommended)
 108 │ cargo test -p thread-flow --test performance_regression_tests --all-features --release
 109 │ 
 110 │ # Type system tests
 111 │ cargo test -p thread-flow --test type_system_tests --all-features
 112 │ ```
 113 │ 
 114 │ #### Run Specific Test
 115 │ ```bash
 116 │ # Run single test by name
 117 │ cargo test -p thread-flow test_cache_basic_operations --all-features
 118 │ 
 119 │ # Run tests matching pattern
 120 │ cargo test -p thread-flow cache --all-features
 121 │ ```
 122 │ 
 123 │ ### Advanced Options
 124 │ 
 125 │ #### Verbose Output
 126 │ ```bash
 127 │ # Show all test output (including println!)
 128 │ cargo test -p thread-flow --all-features -- --nocapture
 129 │ 
 130 │ # Show test names as they run
 131 │ cargo test -p thread-flow --all-features -- --test-threads=1 --nocapture
 132 │ ```
 133 │ 
 134 │ #### Parallel Execution
 135 │ ```bash
 136 │ # Single-threaded (useful for debugging)
 137 │ cargo test -p thread-flow --all-features -- --test-threads=1
 138 │ 
 139 │ # Default (parallel)
 140 │ cargo test -p thread-flow --all-features
 141 │ ```
 142 │ 
 143 │ #### Ignored Tests
 144 │ ```bash
 145 │ # Run only ignored tests
 146 │ cargo test -p thread-flow --all-features -- --ignored
 147 │ 
 148 │ # Run all tests including ignored
 149 │ cargo test -p thread-flow --all-features -- --include-ignored
 150 │ ```
 151 │ 
 152 │ ### Using cargo-nextest
 153 │ 
 154 │ cargo-nextest provides better performance and output:
 155 │ 
 156 │ ```bash
 157 │ # Install (first time only)
 158 │ cargo install cargo-nextest
 159 │ 
 160 │ # Run all tests
 161 │ cargo nextest run -p thread-flow --all-features
 162 │ 
 163 │ # Run with failure output
 164 │ cargo nextest run -p thread-flow --all-features --no-fail-fast
 165 │ 
 166 │ # Run specific test
 167 │ cargo nextest run -p thread-flow --all-features -E 'test(cache)'
 168 │ ```
 169 │ 
 170 │ ---
 171 │ 
 172 │ ## Writing Tests
 173 │ 
 174 │ (Content continues...)
 175 │ 
 176 │ ---
 177 │ 
 178 │ **Last Updated**: 2026-01-28
 179 │ **Test Count**: 86 tests across 5 suites
 180 │ **Maintainers**: Thread Development Team
─────┴──────────────────────────────────────────────────────────────────────────
─────┬──────────────────────────────────────────────────────────────────────────
     │ STDIN
─────┼──────────────────────────────────────────────────────────────────────────
   1 │ 
   2 │ ## Writing Tests (Complete Section)
   3 │ 
   4 │ ### Test Naming Conventions
   5 │ 
   6 │ ```rust
   7 │ // Unit tests: test_<functionality>
   8 │ #[test]
   9 │ fn test_cache_basic_operations() { /* ... */ }
  10 │ 
  11 │ // Integration tests: test_<feature>_<scenario>
  12 │ #[tokio::test]
  13 │ async fn test_parse_rust_code() { /* ... */ }
  14 │ 
  15 │ // Error handling: test_error_<condition>
  16 │ #[tokio::test]
  17 │ async fn test_error_unsupported_language() { /* ... */ }
  18 │ 
  19 │ // Performance: test_<operation>_<metric>
  20 │ #[test]
  21 │ fn test_fingerprint_speed_small_file() { /* ... */ }
  22 │ ```
  23 │ 
  24 │ ### Unit Test Template
  25 │ 
  26 │ ```rust
  27 │ #[cfg(test)]
  28 │ mod tests {
  29 │     use super::*;
  30 │ 
  31 │     #[test]
  32 │     fn test_feature_name() {
  33 │         // Arrange: Set up test data
  34 │         let input = create_test_input();
  35 │ 
  36 │         // Act: Execute the functionality
  37 │         let result = function_under_test(input);
  38 │ 
  39 │         // Assert: Verify expectations
  40 │         assert!(result.is_ok());
  41 │         assert_eq!(result.unwrap(), expected_value);
  42 │     }
  43 │ 
  44 │     #[test]
  45 │     fn test_error_condition() {
  46 │         let invalid_input = create_invalid_input();
  47 │         let result = function_under_test(invalid_input);
  48 │ 
  49 │         assert!(result.is_err());
  50 │         assert!(result.unwrap_err().to_string().contains("expected error"));
  51 │     }
  52 │ }
  53 │ ```
  54 │ 
  55 │ ### Async Integration Test Template
  56 │ 
  57 │ ```rust
  58 │ #[tokio::test]
  59 │ async fn test_async_operation() {
  60 │     // Setup
  61 │     let factory = Arc::new(MyFactory);
  62 │     let context = create_mock_context();
  63 │ 
  64 │     // Build
  65 │     let build_output = factory
  66 │         .build(empty_spec(), vec![], context)
  67 │         .await
  68 │         .expect("Build should succeed");
  69 │ 
  70 │     let executor = build_output.executor.await
  71 │         .expect("Executor should build");
  72 │ 
  73 │     // Execute
  74 │     let inputs = vec![/* test inputs */];
  75 │     let result = executor.evaluate(inputs).await;
  76 │ 
  77 │     // Verify
  78 │     assert!(result.is_ok());
  79 │     let value = result.unwrap();
  80 │     // ... additional assertions
  81 │ }
  82 │ ```
  83 │ 
  84 │ ---
  85 │ 
  86 │ ## Code Coverage
  87 │ 
  88 │ ### Generate Coverage Report
  89 │ 
  90 │ ```bash
  91 │ # Install cargo-llvm-cov (first time only)
  92 │ cargo install cargo-llvm-cov
  93 │ 
  94 │ # Generate HTML report
  95 │ cargo llvm-cov --package thread-flow --all-features --html
  96 │ 
  97 │ # View in browser
  98 │ open target/llvm-cov/html/index.html
  99 │ ```
 100 │ 
 101 │ ### Coverage Summary
 102 │ 
 103 │ ```bash
 104 │ # Text summary only (fast)
 105 │ cargo llvm-cov --package thread-flow --all-features --summary-only
 106 │ ```
 107 │ 
 108 │ ### Expected Coverage
 109 │ 
 110 │ **Core Modules**: 92-99% coverage
 111 │ **Overall**: 30.79% (due to untested infrastructure)
 112 │ 
 113 │ ---
 114 │ 
 115 │ ## Performance Testing
 116 │ 
 117 │ ### Running Performance Tests
 118 │ 
 119 │ ```bash
 120 │ # Always run in release mode
 121 │ cargo test -p thread-flow --test performance_regression_tests --all-features --release
 122 │ ```
 123 │ 
 124 │ ### Performance Baselines
 125 │ 
 126 │ | Operation | Threshold |
 127 │ |-----------|-----------|
 128 │ | Fingerprint (small) | 5µs |
 129 │ | Parse (small) | 1ms |
 130 │ | Full pipeline | 100ms |
 131 │ 
 132 │ ---
 133 │ 
 134 │ ## Troubleshooting
 135 │ 
 136 │ ### Common Issues
 137 │ 
 138 │ 1. **Tests Timing Out**: Run with `--test-threads=1`
 139 │ 2. **Performance Failures**: Always use `--release` mode
 140 │ 3. **Async Test Errors**: Use `#[tokio::test]` attribute
 141 │ 
 142 │ ### Debugging
 143 │ 
 144 │ ```bash
 145 │ # Detailed output
 146 │ cargo test -p thread-flow --all-features -- --nocapture
 147 │ 
 148 │ # With backtrace
 149 │ RUST_BACKTRACE=1 cargo test -p thread-flow --all-features
 150 │ ```
 151 │ 
 152 │ ---
 153 │ 
 154 │ ## Best Practices
 155 │ 
 156 │ ### DO ✅
 157 │ - Write descriptive test names
 158 │ - Test both success and failure paths
 159 │ - Run performance tests in release mode
 160 │ - Keep tests independent
 161 │ 
 162 │ ### DON'T ❌
 163 │ - Skip tests for bug fixes
 164 │ - Use random data without seeding
 165 │ - Commit ignored tests without explanation
 166 │ - Test implementation details
 167 │ 
─────┴──────────────────────────────────────────────────────────────────────────