Testing

Rand has a number of unit tests, though these are not comprehensive or perfect (improvements welcome). We prefer to have tests for all new functionality.

The first line of testing is simply to run cargo test from the appropriate directory. Since Rand supports no_std (core-only), core+alloc and std environments, it is important to test all three (depending on which features are applicable to the code in question):

# Test using std:
cargo test
# Test using only core:
cargo test --tests --no-default-features
# Test using core + alloc (requires nightly):
cargo +nightly test --tests --no-default-features --features=alloc

It may also be worth testing with other feature flags:

cargo test --all-features

Note that this only tests the current package (i.e. the main Rand lib when run from the repo's top level). To test another lib, cd to its directory.

We do not recommend using Cargo's --package option due to its surprising interactions with --feature options and failure when multiple versions of the same package are in the build tree. The CI instead uses --manifest-path to select packages; while developing, using cd is easier.

Writing tests

Tests may be unit tests within a test sub-module, documentation examples, example applications (examples dir), integration tests (tests dir), or benchmarks (benches dir).

Note that only unit tests and integration tests are expected to pass in no_std (core only) and core+alloc configurations. This is a deliberate choice; example code should only need to target the common case (std).

Random Number Generators

Often test code needs some RNG to test with, but does not need any particular RNG. In this case, we prefer use of ::test::rng which is simple, fast to initialise and deterministic:

let mut rng = ::test::rng(528); // just pick some number

Various tests concern properties which are probably true, but not definitely. We prefer that such tests are deterministic to avoid spurious failures.