Guidelines for Writing Rust Tests

Guidelines for writing new tests for Rust code.

Guidelines

• Test against the public API of the code under test.

• Test private APIs if and only if the private component is highly complex and difficult to test through the public API.

• Use insta whenever you are testing output that is difficult to predict or compare.

• Where appropriate, use proptest to add property-based tests for key invariants.

• Testing code should be written with the same care reserved to production code. Avoid unnecessary duplication, introduce helpers to reduce boilerplate and ensure readability. The intent of a test should be obvious or, if not possible, clearly documented.

• Do not reference exact line numbers in comments, as they may change over time.

Code organization

• Put tests under the tests directory of the relevant crate if they don't rely on private APIs.

• The tests directory should be organized as a crate, with a main.rs file and all tests in modules. Refer to the trie_rs/tests directory as an example.

• If the test must rely on private APIs, co-locate them with the code they test, using a #[cfg(test)] module.

Dealing with extern C symbols

Check out CONTRIBUTING.md for instructions on how to deal with undefined C symbols in Rust tests.