Crate test_generator

source ·
Expand description

Overview

This crate provides #[test_resources] and #[bench_resources] procedural macro attributes that generates multiple parametrized tests using one body with different resource input parameters. A test is generated for each resource matching the specific resource location pattern.

Crates.io MIT License Apache License Example

Documentation

Repository

Getting Started

First of all you have to add this dependency to your Cargo.toml:

[dev-dependencies]
test-generator = "^0.3"

The test-functionality is supports stable Rust since version 1.30, whereas the bench-functionality requires an API from unstable nightly release.

#![cfg(test)]
extern crate test_generator;

// Don't forget that procedural macros are imported with `use` statement,
// for example importing the macro 'test_resources'
#![cfg(test)]
use test_generator::test_resources;

Example usage test:

The test functionality supports the stable release of Rust-compiler since version 1.30.

#![cfg(test)]
extern crate test_generator;

use test_generator::test_resources;

#[test_resources("res/*/input.txt")]
fn verify_resource(resource: &str) {
   assert!(std::path::Path::new(resource).exists());
}

Output from cargo test for 3 test-input-files matching the pattern, for this example:

$ cargo test

running 3 tests
test tests::verify_resource_res_set1_input_txt ... ok
test tests::verify_resource_res_set2_input_txt ... ok
test tests::verify_resource_res_set3_input_txt ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Example usage bench:

The bench functionality requires the nightly release of the Rust-compiler.

#![feature(test)] // nightly feature required for API test::Bencher

#[macro_use]
extern crate test_generator;

extern crate test; /* required for test::Bencher */

mod bench {
    #[bench_resources("res/*/input.txt")]
    fn measure_resource(b: &mut test::Bencher, resource: &str) {
        let path = std::path::Path::new(resource);
        b.iter(|| path.exists());
    }
}

Output from cargo +nightly bench for 3 bench-input-files matching the pattern, for this example:

running 3 tests
test bench::measure_resource_res_set1_input_txt ... bench:       2,492 ns/iter (+/- 4,027)
test bench::measure_resource_res_set2_input_txt ... bench:       2,345 ns/iter (+/- 2,167)
test bench::measure_resource_res_set3_input_txt ... bench:       2,269 ns/iter (+/- 1,527)

test result: ok. 0 passed; 0 failed; 0 ignored; 3 measured; 0 filtered out

Example

The example demonstrates usage and configuration of these macros, in combination with the crate build-deps monitoring for any change of these resource files and conditional rebuild.

Internals

Let’s assume the following code and 3 files matching the pattern “res/*/input.txt”

#[test_resources("res/*/input.txt")]
fn verify_resource(resource: &str) { assert!(std::path::Path::new(resource).exists()); }

the generated code for this input resource will look like

#[test]
#[allow(non_snake_case)]
fn verify_resource_res_set1_input_txt() { verify_resource("res/set1/input.txt".into()); }
#[test]
#[allow(non_snake_case)]
fn verify_resource_res_set2_input_txt() { verify_resource("res/set2/input.txt".into()); }
#[test]
#[allow(non_snake_case)]
fn verify_resource_res_set3_input_txt() { verify_resource("res/set3/input.txt".into()); }

Note: The trailing into() method-call permits users to implement the Into-Trait for auto-conversations.

Macros

deprecated Generate a benchmark-function call for each list-element
deprecated Generate a benchmark-function call for each file matching the pattern
deprecated Function-Attribute macro expanding glob-file-pattern to a list of directories and generating a test-function for each one.
deprecated Generate a test-function call for each list-element
deprecated Generate a test-function call for each file matching the pattern

Attribute Macros

Macro generating bench-functions, invoking the fn for each item matching the resource-pattern.
Macro generating test-functions, invoking the fn for each item matching the resource-pattern.