test_case/
lib.rs

1//! # Overview
2//! `test_case` crate provides procedural macro attribute that generates parametrized test instances.
3//!
4//! # Getting Started
5//!
6//! Crate has to be added as a dependency to `Cargo.toml`:
7//!
8//! ```toml
9//! [dev-dependencies]
10//! test-case = "3.2.1"
11//! ```
12//!
13//! and imported to the scope of a block where it's being called
14//! (since attribute name collides with rust's built-in `custom_test_frameworks`) via:
15//!
16//! ```rust
17//! use test_case::test_case;
18//! ```
19//!
20//! # Example usage:
21//!
22//! ```rust
23//! #[cfg(test)]
24//! mod tests {
25//!     use test_case::test_case;
26//!
27//!     #[test_case(-2, -4 ; "when both operands are negative")]
28//!     #[test_case(2,  4  ; "when both operands are positive")]
29//!     #[test_case(4,  2  ; "when operands are swapped")]
30//!     fn multiplication_tests(x: i8, y: i8) {
31//!         let actual = (x * y).abs();
32//!
33//!         assert_eq!(8, actual)
34//!     }
35//! }
36//! ```
37//!
38//! Output from `cargo test` for this example:
39//!
40//! ```sh
41//! $ cargo test
42//!
43//! running 4 tests
44//! test tests::multiplication_tests::when_both_operands_are_negative ... ok
45//! test tests::multiplication_tests::when_both_operands_are_positive ... ok
46//! test tests::multiplication_tests::when_operands_are_swapped ... ok
47//!
48//! test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
49//! ```
50//!
51//! ## Test Matrix
52//!
53//! The `#[test_matrix(...)]` macro allows generating multiple test cases from the
54//! Cartesian product of one or more possible values for each test function argument. The
55//! number of arguments to the `test_matrix` macro must be the same as the number of arguments to
56//! the test function. Each macro argument can be:
57//!
58//!     1. A list in array (`[x, y, ...]`) or tuple (`(x, y, ...)`) syntax. The values can be any
59//!        valid [expression](https://doc.rust-lang.org/reference/expressions.html).
60//!     2. A closed numeric range expression (e.g. `0..100` or `1..=99`), which will generate
61//!        argument values for all integers in the range.
62//!     3. A single expression, which can be used to keep one argument constant while varying the
63//!        other test function arguments using a list or range.
64//!
65//! ### Example usage:
66//!
67//! ```rust
68//! #[cfg(test)]
69//! mod tests {
70//!     use test_case::test_matrix;
71//!
72//!     #[test_matrix(
73//!         [-2, 2],
74//!         [-4, 4]
75//!     )]
76//!     fn multiplication_tests(x: i8, y: i8) {
77//!         let actual = (x * y).abs();
78//!
79//!         assert_eq!(8, actual)
80//!     }
81//! }
82//! ```
83//!
84//! # MSRV Policy
85//!
86//! Starting with version 3.0 and up `test-case` introduces policy of only supporting latest stable Rust.
87//! These changes may happen overnight, so if your stack is lagging behind current stable release,
88//! it may be best to consider locking `test-case` version with `=` in your `Cargo.toml`.
89//!
90//! # Documentation
91//!
92//! Most up to date documentation is available in our [wiki](https://github.com/frondeus/test-case/wiki).
93pub use test_case_macros::test_case;
94pub use test_case_macros::test_case as case;
95pub use test_case_macros::test_matrix;
96
97#[cfg(feature = "with-regex")]
98pub use regex::*;