copilot-instructions rust-testing.instructions.md

Testing Standards

All code must follow these testing standards to ensure quality and maintainability.

Core Principles

1. Test Coverage: Every public API must have tests
2. Test Organization: Use dedicated test files, not just inline tests
3. Test Naming: Descriptive names following test_[function]_[scenario]_[result] pattern
4. Documentation: All test files must have file-level doc comments
5. Template Precedence: Start concrete test files from the applicable .github/templates/rust-*-template.rs file when one exists; treat inline examples in this instruction as partial guidance only

File Organization

MANDATORY PATTERN: All crates MUST use test_suite.rs as the entry point.

crates/my-crate/
├── src/
│   ├── lib.rs
│   ├── module.rs          # May have inline tests for private functions
│   └── error.rs
└── tests/
    ├── test_suite.rs      # REQUIRED: Main test entry point
    ├── error_tests.rs     # REQUIRED for all crates
    ├── module_tests.rs    # Unit tests for public API
    └── integration_tests.rs

test_suite.rs Structure (REQUIRED)

Every crate MUST have tests/test_suite.rs as the single test entry point:

//! [Crate Name] Test Suite Entry Point
//!
//! Main test suite aggregator for [crate-name] crate.
//! All module tests are organized to mirror the src/ directory structure.

// Module-specific test suites
mod error_tests;
mod module_tests;
mod integration_tests;

// For subdirectories, use #[path] attribute:
#[path = "subdir/mod.rs"]
mod subdir;

Critical Rules:

1. ✅ ALWAYS use test_suite.rs as the entry point
2. ✅ Import all test modules in test_suite.rs
3. ✅ Mirror src/ structure in tests/
4. ✅ Use #[path] for subdirectories
5. ❌ NEVER use lib.rs in tests/
6. ❌ NEVER use individual test files without test_suite.rs
7. ❌ NEVER use Cargo.toml [[test]] sections (except for special cases)

Required Test Files

1. error_tests.rs (MANDATORY)

Every crate MUST have tests/error_tests.rs testing:

• All error variants Display implementation
• All error variants Debug formatting
• All From conversions
• Error propagation with ? operator
• Result type alias (if exists)