cargo-needy and #[needy::requirements(...)]

Usage

1. Add requirements_ids to your dev-dependencies.

$ cargo add --dev requirements_ids

[!TIP] If you want to trace non-test functions, you will need to add it as a normal dependency.

2. Annotate your test functions with the corresponding requirement ids

The requirement can be any valid identifier (see syntax in FLS).

use needy::requirements;

// test a single requirement
#[requirements(REQ_001)]
#[test]
fn it_works() {
    assert_eq!(1 + 1, 2);
}

// test multiple requirements
#[requirements(REQ_001, REQ_002)]
#[test]
fn it_works_also() {
    assert_eq!(1 + 1, 2);
}

3. Use cargo-needy to export a JSON of all requirements

[!WARNING] At the moment cargo-needy requires Rust nightly from 2024-09-26 or later, because of some rust-analyzer features we rely on.

This restriction will be lifted as soon as that rust-analyzer version becomes stable.

Until then run set your Rust toolchain to nightly:

$ # set nightly globally
$ rustup default nightly
$
$ # set nightly for the current directory
$ rustup override set nightly
$
$ # set nightly for the command only
$ cargo +nightly needy

$ rustup component add rust-analyzer
$ cargo install cargo-needy
$ cargo needy <path>

This outputs the collected requirement ids as JSON.

For example for cargo-needy/tests/test-crate it looks like this:

$ cargo needy cargo-needy/tests/test-crate/
Running `cargo check --manifest-path cargo-needy/tests/test-crate/Cargo.toml --all-targets`
  took 45.6ms
Running `rust-analyzer lsif cargo-needy/tests/test-crate/`
  took 11.5s
Analyzing lsif output
  took 89.6ms
{"file":"file:///home/urhengulas/Documents/github.com/ferrocene/cargo-needy/cargo-needy/tests/test-crate/src/main.rs","function_name":"test_main","module":"test_crate","requirement_id":"REQ_001","span":{"start":{"line":10,"character":22},"end":{"line":10,"character":29}},"version":"v1"}
{"file":"file:///home/urhengulas/Documents/github.com/ferrocene/cargo-needy/cargo-needy/tests/test-crate/tests/it_works.rs","function_name":"it_works","module":"it_works","requirement_id":"REQ_002","span":{"start":{"line":0,"character":35},"end":{"line":0,"character":42}},"version":"v1"}
{"file":"file:///home/urhengulas/Documents/github.com/ferrocene/cargo-needy/cargo-needy/tests/test-crate/tests/it_works.rs","function_name":"it_works","module":"it_works","requirement_id":"REQ_003","span":{"start":{"line":0,"character":44},"end":{"line":0,"character":51}},"version":"v1"}

Benchmark

In order to optimize the project there is a benchmark crate which heavily uses the needy::requirements macro.

To get end-to-end timings you can use bench.py which runs cargo-needy multiple iterations via hyperfine.

$ python bench.py
Benchmark 1: cargo +nightly run --release -q -- tests/bench-crate/ 1> /dev/null
  Time (mean ± σ):     8288.6 ms ± 327.0 ms    [User: 8056.2 ms, System: 497.2 ms]
  Range (min … max):   7509.9 ms … 8674.0 ms    10 runs

$ # To get timings of the analysis stage, pass the `--bench-analyze` flag.
$ python bench.py --bench-analyze

$ # To benchmark more iterations, pass the `--more-runs` flag.
$ python bench.py --bench-analyze

Please take care to have a similar setup when you compare timing runs and be aware that there is noise.