Rust Testing Strategy

Rust Testing Strategy

Verification Commands

• When modifying Rust code, run clippy to detect issues:

  cargo clippy --all-features --all-targets --workspace --no-deps

• Use cargo doc --no-deps --all-features to check documentation

Test Execution

• Use cargo-nextest for running unit and integration tests
• Use the default test runner for documentation tests
• For comprehensive verification, run the complete test suite
• Database seeding can be performed using yarn commands in the project's package.json

Test Subject

Test behavior implemented by our code or its composition. Assume dependencies implement their documented behavior correctly. Do not add tests whose only subject is a dependency's parser, serializer or generated implementation. Deriving or wrapping that API on an application type does not make its implementation ours.

A test that only calls try_parse_from on a #[derive(clap::Parser)] type and checks the declared fields or built-in validation re-tests clap. Test the logic of an application-owned value parser, validation rule or use of the parsed options when the case can expose a bug in our behavior with clap's behavior held fixed. Parsing can be setup for the test without being its whole assertion. Moving a dependency-conformance case into an integration target does not change its subject.

Test Design Principles

• Choose success and error cases that distinguish our intended behavior from a plausible defect
• Do not add a test merely to mirror a trivial mapping or immediate rejection branch
• Test boundary conditions and edge cases explicitly
• Include tests for invalid or malformed inputs
• For streaming encoders/decoders, test partial data handling and buffer management
• Aim for high test coverage but prioritize test quality over quantity
• Structure tests following the Arrange-Act-Assert pattern

Assertion Standards

• Use descriptive assertion messages that explain the expected behavior

• All assertion messages (including expect(), unwrap() and assert*()) should follow the "should..." format:

  // Good examples:
  value.expect("should contain a valid configuration");
  assert_eq!(result, expected, "Result should match the expected value");

• Use expect() or expect_err() with clear messages instead of unwrap() or unwrap_err()

• Prefer assert_eq! with custom messages over bare assertions when comparing values

• When testing errors, assert on specific error types or message contents, not just that an error occurred

• Balance assertions to verify functionality without creating brittle tests

Test Organization

• Group related tests into appropriate modules
• Use helper functions to avoid code duplication in tests
• Consider using parameterized tests for testing similar functionality with different inputs