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

Test Naming

A test name is a short label with the shape <subject>_<case>[_<variant>]:

• <subject> is the operation, type or function under test. It does not repeat the name of the enclosing module, because the test path already carries that.
• <case> is what distinguishes this test from its siblings under the same subject: an operand shape, an input class, a code path, or an active verb and its object where the behaviour is the distinguishing part (load_redacts_mistyped_values). An active verb is not narration; should, works and correctly are.
• <variant> narrows the case further when two tests share one, and is otherwise absent.

Tests of one subject share a prefix, so a module's test list reads as a table of subject × case and cargo nextest run -E 'test(<subject>_)' selects the family. The name identifies the case and the assertions establish its result. A comment adds setup, reasoning or a contract that those do not explain. A self-explanatory test needs no comment.

What a name never carries:

• A test_ prefix, an article, a narration verb (should, works, correctly) or a when/with/that clause. Put necessary explanation in a comment or assertion message rather than in the name.
• More than about six words. Three to five is the norm, and a longer name is a test doing too much, where the fix is one test per case.
• The rejection, for a negative case. The name is the input class (ice_invalid_subscript_type, rank_positions_short, rows_out_of_domain), with no err_ prefix or _err suffix. An outcome word is the final token only when the case alone is ambiguous (eq_same_type_accepted).

Where the shape meets a test framework:

• A property test, or an rstest case set, takes its name from the property it tests (lattice_laws, solve_anti_symmetry, condensation_is_dag).
• Renaming a snapshot test renames the snapshot files derived from its name in the same change.

// Before: a sentence, three cases in one test, the outcome in the name.
async fn rank_pair_tampers_name_their_own_variants() { /* … */ }
async fn short_node_identity_table_refuses() { /* … */ }

// After: one label per case, the outcome in the doc comment.
/// Open refuses a reverse rank permutation short of the code column, under `Columns`.
async fn rank_positions_short() { /* … */ }
/// Open refuses a reverse rank permutation that is no permutation, under `RankInverse`.
async fn rank_positions_constant() { /* … */ }
/// Open refuses a node identity table short of the code column, under `Identities`.
async fn node_identities_short() { /* … */ }

Test Code Quality

• Follow the same code quality standards in test code as in production code
• Add appropriate assertions for array/slice access to avoid clippy warnings
• Add comments for non-obvious setup, reasoning or contracts that the test's name and body leave unclear. Self-explanatory tests may omit comments.
• Consider adding custom test utilities to simplify common testing patterns
• Use the json! macro from serde_json instead of constructing JSON as raw strings

// Bad:
let json_str = "{\"name\":\"value\",\"nested\":{\"key\":42}}";

// Good:
use serde_json::json;
let json_value = json!({
    "name": "value",
    "nested": {
        "key": 42
    }
});