1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
//! # Overview //! This crate provides `#[test_case]` procedural macro attribute that generates multiple parametrized tests using one body with different input parameters. //! A test is generated for each data set passed in `test_case` attribute. //! Under the hood, all test cases that share same body are grouped into `mod`, giving clear and readable test results. //! //! # Getting Started //! //! First of all you have to add this dependency to your `Cargo.toml`: //! //! ```toml //! [dev-dependencies] //! test-case = "1.0.0" //! ``` //! //! Additionally, you have to import the procedural macro with `use` statement: //! //! ```rust //! use test_case::test_case; //! ``` //! //! The crate depends on `proc_macro` feature that has been stabilized on rustc 1.29+. //! //! # Example usage: //! //! ```rust //! // The next two lines are not needed for 2018 edition or newer //! #[cfg(test)] //! extern crate test_case; //! //! #[cfg(test)] //! mod tests { //! use test_case::test_case; //! //! // Not needed for this example, but useful in general //! use super::*; //! //! #[test_case( 4, 2 ; "when operands are swapped")] //! #[test_case(-2, -4 ; "when both operands are negative")] //! fn multiplication_tests(x: i8, y: i8) { //! let actual = (x * y).abs(); //! //! assert_eq!(8, actual) //! } //! //! // You can still use regular tests too //! #[test] //! fn addition_test() { //! let actual = -2 + 8; //! assert_eq!(6, actual) //! } //! } //! ``` //! //! Output from `cargo test` for this example: //! //! ```sh //! $ cargo test //! //! running 4 tests //! test tests::addition_test ... ok //! test tests::multiplication_tests::when_both_operands_are_negative ... ok //! test tests::multiplication_tests::when_both_operands_are_positive ... ok //! test tests::multiplication_tests::when_operands_are_swapped ... ok //! //! test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out //! ``` //! //! # Examples //! //! If your only assertion is just `assert_eq!`, you can pass the expectation as macro attribute using `=>` syntax: //! //! ```rust //! # use test_case::test_case; //! #[test_case( 2 => 2 ; "returns given number for positive input")] //! #[test_case(-2 => 2 ; "returns opposite number for non-positive input")] //! #[test_case( 0 => 0 ; "returns 0 for 0")] //! fn abs_tests(x: i8) -> i8 { //! if x > 0 { x } else { -x } //! } //! ``` //! //! Which is equivalent to //! //! ```rust //! # use test_case::test_case; //! #[test_case( 2, 2 ; "returns given number for positive input")] //! #[test_case(-2, 2 ; "returns opposite number for non-positive input")] //! #[test_case( 0, 0 ; "returns 0 for 0")] //! fn abs_tests(x: i8, expected: i8){ //! let actual = if x > 0 { x } else { -x }; //! //! assert_eq!(expected, actual); //! } //! ``` //! //! Attributes and expectation may be any expresion unless they contain `=>`, e.g. //! //! ```rust //! # use test_case::test_case; //! #[test_case(None, None => 0 ; "treats none as 0")] //! #[test_case(Some(2), Some(3) => 5)] //! #[test_case(Some(2 + 3), Some(4) => 2 + 3 + 4)] //! fn fancy_addition(x: Option<i8>, y: Option<i8>) -> i8 { //! x.unwrap_or(0) + y.unwrap_or(0) //! } //! ``` //! //! Note: in fact, `=>` is not prohibited, but the parser will always treat last `=>` sign as beginning of expectation definition. //! //! Test case names are optional. They are set using `;` followed by string literal at the end of macro attributes. //! //! Example generated code: //! //! ```rust //! mod fancy_addition { //! #[allow(unused_imports)] //! use super::*; //! //! fn fancy_addition(x: Option<i8>, y: Option<i8>) -> i8 { //! x.unwrap_or(0) + y.unwrap_or(0) //! } //! //! #[test] //! fn treats_none_as_0() { //! let expected = 0; //! let actual = fancy_addition(None, None); //! //! assert_eq!(expected, actual); //! } //! //! #[test] //! fn some_2_some_3() { //! let expected = 5; //! let actual = fancy_addition(Some(2), Some(3)); //! //! assert_eq!(expected, actual); //! } //! //! #[test] //! fn some_2_3_some_4() { //! let expected = 2 + 3 + 4; //! let actual = fancy_addition(Some(2 + 3), Some(4)); //! //! assert_eq!(expected, actual); //! } //! } //! ``` //! //! ## Inconclusive (ignored) test cases (since 0.2.0) //! //! If test case name (passed using `;` syntax described above) contains a word "inconclusive", generated test will be marked with `#[ignore]`. //! //! ### Keyword inconclusive (since 1.0.0) //! //! If test expectation is preceded by keyword `inconclusive` the test will be ignored as if it's description would contain word `inconclusive` //! //! //! ```rust //! # use test_case::test_case; //! #[test_case("42")] //! #[test_case("XX" ; "inconclusive - parsing letters temporarily doesn't work, but it's ok")] //! #[test_case("na" => inconclusive ())] //! fn parses_input(input: &str) { //! // ... //! } //! ``` //! //! Generated code: //! ```ignore //! mod parses_input { //! // ... //! //! #[test] //! pub fn _42() { //! // ... //! } //! //! #[test] //! #[ignore] //! pub fn inconclusive_parsing_letters_temporarily_doesn_t_work_but_it_s_ok() { //! // ... //! } //! //! ``` //! //! ## Pattern matched test cases (since 1.0.0) //! //! If test expectation is preceded by `matches` keyword, the result will be tested whether it fits within provided pattern. //! //! ```rust //! # use test_case::test_case; //! #[test_case("foo", "bar" => matches ("foo", _) ; "first element of zipped tuple is correct")] //! #[test_case("foo", "bar" => matches (_, "bar") ; "second element of zipped tuple is correct")] //! fn zip_test<'a>(left: &'a str, right: &'a str) -> (&'a str, &'a str) { //! (left, right) //! } //! ``` //! //! ## Panicking test cases (since 1.0.0) //! //! If test case expectation is preceded by `panics` keyword and the expectation itself is `&str` **or** expresion that evaluates to `&str` then test case will be expected to panic during execution. //! //! ```rust //! # use test_case::test_case; //! //! #[test_case("foo" => panics "invalid input")] //! #[test_case("bar")] //! fn test_panicking(input: &str) { //! if input == "foo" { //! panic!("invalid input") //! } //! } //! ``` extern crate proc_macro; use proc_macro::TokenStream; use syn::{parse_macro_input, ItemFn}; use quote::quote; use syn::parse_quote; use syn::spanned::Spanned; use test_case::TestCase; mod test_case; mod utils; /// Generates tests for given set of data /// /// In general, test case consists of four elements: /// /// 1. _(Required)_ Arguments passed to test body /// 2. _(Optional)_ Expected result /// 3. _(Optional)_ Test case name /// 4. _(Required)_ Test body /// /// When _expected result_ is provided, it is compared against the actual value generated with _test body_ using `assert_eq!`. /// _Test cases_ that don't provide _expected result_ should contain custom assertions inside _test body_. /// /// # Examples /// /// - Without result and name /// /// ```rust /// # use test_case::test_case; /// #[test_case(5)] /// #[test_case(10)] /// fn is_positive(x: i8) { /// assert!(x > 0) /// } /// ``` /// /// - With name, without result /// /// ```rust /// # use test_case::test_case; /// #[test_case(1 ; "little number")] /// #[test_case(100 ; "big number")] /// #[test_case(5)] // some tests may use default name generated from arguments list /// fn is_positive(x: i8) { /// assert!(x > 0) /// } /// ``` /// /// - With result, without name /// /// ```rust /// # use test_case::test_case; /// #[test_case(1, 2 => 3)] /// #[test_case(-1, -2 => -3)] /// fn addition(x: i8, y: i8) -> i8 { /// x + y /// } /// ``` /// /// - With result and name /// /// ```rust /// # use test_case::test_case; /// #[test_case(1, 2 => 3 ; "both numbers possitive")] /// #[test_case(-1, -2 => -3 ; "both numbers negative")] /// fn addition(x: i8, y: i8) -> i8 { /// x + y /// } /// ``` #[proc_macro_attribute] pub fn test_case(args: TokenStream, input: TokenStream) -> TokenStream { let test_case = parse_macro_input!(args as TestCase); let mut item = parse_macro_input!(input as ItemFn); let mut test_cases = vec![test_case]; let mut attrs_to_remove = vec![]; for (idx, attr) in item.attrs.iter().enumerate() { if attr.path == parse_quote!(test_case) { let test_case = match attr.parse_args::<TestCase>() { Ok(test_case) => test_case, Err(err) => { return syn::Error::new( attr.span(), format!("cannot parse test_case arguments: {:?}", err), ) .to_compile_error() .into() } }; test_cases.push(test_case); attrs_to_remove.push(idx); } } for i in attrs_to_remove.into_iter().rev() { item.attrs.swap_remove(i); } render_test_cases(&test_cases, item) } fn render_test_cases(test_cases: &[TestCase], item: ItemFn) -> TokenStream { let mut rendered_test_cases = vec![]; for test_case in test_cases { rendered_test_cases.push(test_case.render(item.clone())); } let mod_name = item.sig.ident.clone(); let output = quote! { mod #mod_name { #[allow(unused_imports)] use super::*; #[allow(unused_attributes)] #item #(#rendered_test_cases)* } }; output.into() }