Rust tests

Same three rules as the TypeScript side: the name is the sentence, the body is blocks separated by blank lines, and there are no comments. The differences are where a test lives and what setup it is allowed to do.

#[test]
fn refuses_to_scan_without_credentials() {
    let state = test_state();
    let progress = Progress::default();

    let err = scan(&state, &progress.record(), &never_cancelled()).unwrap_err();

    assert!(matches!(err, ScanError::NoApiKey));
    assert_eq!(progress.seen(), vec![]);
}

The four blocks

A body is up to four blocks, always in this order, one blank line between them:

Block	Holds
setup	Fixtures, state, the world the behaviour needs
mock	Fakes and the responses they are primed with
test	The one call under test
verify	The assertions

• A blank line only ever separates two blocks. Never one inside a block, never two in a row.
• An empty block is absent, not blank. Most tests have three, because a test-support helper builds the world and there is nothing left to fake.
• No comment names a block. The order is the label.
• Every assertion in verify. An assert! in the setup block is a precondition, and one worth checking is its own test.
• let bindings that only feed the call belong in setup, not squeezed into the test line. One statement under test, readable on its own.

Rust makes the mock block rarer than TypeScript does: a trait with a small fake implementation is setup, not mocking, and it lives above the tests with a name.

Naming

The function name is the sentence, in the present tense, describing behaviour:

fn refuses_to_scan_without_credentials()   // good
fn marks_a_missing_file_absent()           // good

fn test_scan()                             // names the function under test
fn scan_works()                            // says nothing
fn test_scan_returns_err_when_key_is_none() // describes the code, not the rule

Drop the test_ prefix. #[test] already says it.

Size and setup

One situation, one action, one assertion. Shared setup belongs in a named test-support module, not repeated in each test. Find the one the crate already has before writing a second: test_support, common, tests/common/mod.rs and fixtures are all conventional names, and a crate usually has exactly one.

use crate::test_support::{seed_fixture, test_state};

When a test needs a fake collaborator, give it a name and keep it above the tests, not inline:

#[derive(Default)]
struct Progress(RefCell<Vec<(usize, usize)>>);

A test that runs long is two tests, or a fixture that wants a name, or a function that needs too many collaborators to say anything.

No comments

No banner, no note above a case, no paragraph explaining what the module pins. The name carries the behaviour and the blank lines carry the phases. A comment survives only for a genuinely non-obvious fixture value, stating why that value and not another.

// SAFETY: still applies inside unsafe, in tests as everywhere else.

Assert behaviour

• assert!(matches!(err, ScanError::NoApiKey)) beats asserting on a formatted string: the message is prose and prose changes.
• Assert the observable result, not the number of times a collaborator was called, unless the count is the behaviour.
• unwrap() and expect() are fine in a test. A panic is a failure and that is the point.
• Never weaken an assertion to make a suite green.

Where it goes

• Unit tests live beside the code in a #[cfg(test)] mod tests, with access to the module's private items. This is where most tests belong.
• Integration tests live in the crate's tests/ directory and see only the public API, which is what makes them worth having: a test that cannot reach a private helper proves the public surface is usable.
• Some projects keep API integration tests beside the handlers behind a file-name prefix instead, so the test moves with the route it covers. Follow the tree.
• A workspace member is tested by name. In a repo whose members are separate workspaces rather than one, --workspace from the root does not reach them, so check whether the project ships a script that iterates them.

Async and time

• #[tokio::test] for anything awaiting. Keep the runtime default unless the test needs otherwise.
• Never sleep to synchronise. Wait on the thing itself: a channel, a notify, a join handle. A sleep is a flake with a timer on it.
• Pass time in rather than reading the clock, so the test does not depend on when it runs.

Running one

cargo test -p <crate>              # one crate
cargo test --workspace <filter>    # one test name, everywhere
cargo test -p <crate> -- --nocapture

Run from the workspace root that owns the crate. Where the repo holds more than one workspace, cd to the right one first.

Before the PR

cargo clippy --workspace --all-targets && cargo test --workspace

Then whatever the project's manifest scripts run for members outside that workspace, because --workspace does not reach them.

Where the file goes on disk, and what its suffix means, belong to the naming skill.