feat: Add test_matrix macro (#128)

* Add test_matrix macro

Allows generating Cartesian product test matrices.
Tests and docs forthcoming.

* Add test_matrix macro acceptance tests

Test basic features and for correct compilation error
output

* Add `=>` expression support to test_matrix macro

Required that `TestCaseExpression` and all it's descendant structs be
`Clone` so that TestMatrix can clone them for each TestCase it creates.
Also made TestComment Clone for parity.

Implemented quote::ToTokens for TestComment so that the "illegal
comment" error generated by TestMatrix can point to the correct span of
where the illegal comment begins. On stable Rust, this just highlights
the first token, the semicolon, but on nightly Rust (which has
`quote::Span::join`) it will highlight the entire illegal comment.

* Use isize in test_matrix ranges

`isize` will allow for negative numbers and be compatible
with 32-bit and 64-bit platforms.

Add some acceptance tests for the same.

* Add basic documentation for test_matrix macro

Add unreleased CHANGELOG fragment, README documentation,
and doc comment to src/lib.rs and crate/test-case-macros/src/lib.rs.

Detailed Wiki documentation forthcoming.

* Replace itertools dependency with copied module

Copied multi_product module from itertools 0.11.0
under MIT license. Eliminates dependency on building
all of itertools.

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [Unreleased]
+### New features
+* Add `test_matrix` macro: generates test cases from Cartesian product of possible test function argument values.
+
 ## 3.1.0
 ### New features
 * Copy attribute span to generated test functions so that IDEs recognize them properly as individual tests

README.md

@@ -57,6 +57,39 @@ test tests::multiplication_tests::when_operands_are_swapped ... ok
 test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 ```
 
+### Test Matrix
+
+The `#[test_matrix(...)]` macro allows generating multiple test cases from the
+Cartesian product of one or more possible values for each test function argument. The
+number of arguments to the `test_matrix` macro must be the same as the number of arguments to
+the test function. Each macro argument can be:
+
+1. A list in array (`[x, y, ...]`) or tuple (`(x, y, ...)`) syntax. The values can be any
+   valid [expression](https://doc.rust-lang.org/reference/expressions.html).
+2. A closed numeric range expression (e.g. `0..100` or `1..=99`), which will generate
+   argument values for all integers in the range.
+3. A single expression, which can be used to keep one argument constant while varying the
+   other test function arguments using a list or range.
+
+#### Example usage:
+
+```rust
+#[cfg(test)]
+mod tests {
+    use test_case::test_matrix;
+
+    #[test_matrix(
+        [-2, 2],
+        [-4, 4]
+    )]
+    fn multiplication_tests(x: i8, y: i8) {
+        let actual = (x * y).abs();
+
+        assert_eq!(8, actual)
+    }
+}
+```
+
 ## MSRV Policy
 
 Starting with version 3.0 and up `test-case` introduces policy of only supporting latest stable Rust.

crates/test-case-core/src/comment.rs

@@ -1,7 +1,9 @@
+use crate::TokenStream2;
+use quote::ToTokens;
 use syn::parse::{Parse, ParseStream};
 use syn::{LitStr, Token};
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct TestCaseComment {
     _semicolon: Token![;],
     pub comment: LitStr,
@@ -16,6 +18,13 @@ impl Parse for TestCaseComment {
     }
 }
 
+impl ToTokens for TestCaseComment {
+    fn to_tokens(&self, tokens: &mut TokenStream2) {
+        self._semicolon.to_tokens(tokens);
+        self.comment.to_tokens(tokens);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use crate::comment::TestCaseComment;

crates/test-case-core/src/complex_expr.rs

@@ -38,7 +38,7 @@ mod kw {
     syn::custom_keyword!(matches_regex);
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum OrderingToken {
     Eq,
     Lt,
@@ -47,57 +47,57 @@ pub enum OrderingToken {
     Geq,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum PathToken {
     Any,
     Dir,
     File,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Ord {
     pub token: OrderingToken,
     pub expected_value: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct AlmostEqual {
     pub expected_value: Box<Expr>,
     pub precision: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Path {
     pub token: PathToken,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Contains {
     pub expected_element: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ContainsInOrder {
     pub expected_slice: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Len {
     pub expected_len: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Count {
     pub expected_len: Box<Expr>,
 }
 
 #[cfg(feature = "with-regex")]
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Regex {
     pub expected_regex: Box<Expr>,
 }
 
-#[derive(Debug, PartialEq)]
+#[derive(Clone, Debug, PartialEq)]
 pub enum ComplexTestCase {
     Not(Box<ComplexTestCase>),
     And(Vec<ComplexTestCase>),

crates/test-case-core/src/expr.rs

@@ -18,14 +18,14 @@ pub mod kw {
     syn::custom_keyword!(panics);
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct TestCaseExpression {
     _token: Token![=>],
     pub extra_keywords: HashSet<Modifier>,
     pub result: TestCaseResult,
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub enum TestCaseResult {
     // test_case(a, b, c => keywords)
     Empty,

crates/test-case-core/src/lib.rs

@@ -5,6 +5,8 @@ mod complex_expr;
 mod expr;
 mod modifier;
 mod test_case;
+mod test_matrix;
 mod utils;
 
 pub use test_case::TestCase;
+pub use test_matrix::TestMatrix;

crates/test-case-core/src/modifier.rs

@@ -9,7 +9,7 @@ mod kw {
     syn::custom_keyword!(ignore);
 }
 
-#[derive(PartialEq, Eq, Hash)]
+#[derive(Clone, PartialEq, Eq, Hash)]
 pub enum Modifier {
     Inconclusive,
     InconclusiveWithReason(LitStr),

crates/test-case-core/src/test_case.rs

@@ -10,8 +10,8 @@ use syn::{parse_quote, Error, Expr, Ident, ItemFn, ReturnType, Token};
 #[derive(Debug)]
 pub struct TestCase {
     args: Punctuated<Expr, Token![,]>,
-    expression: Option<TestCaseExpression>,
-    comment: Option<TestCaseComment>,
+    pub(crate) expression: Option<TestCaseExpression>,
+    pub(crate) comment: Option<TestCaseComment>,
 }
 
 impl Parse for TestCase {
@@ -24,6 +24,19 @@ impl Parse for TestCase {
     }
 }
 
+impl<I> From<I> for TestCase
+where
+    I: IntoIterator<Item = Expr>,
+{
+    fn from(into_iter: I) -> Self {
+        Self {
+            args: into_iter.into_iter().collect(),
+            expression: None,
+            comment: None,
+        }
+    }
+}
+
 impl TestCase {
     pub fn test_case_name(&self) -> Ident {
         let case_desc = self