feat: support outer doc comments for naming matrix tests (#321)

Adds support for using outer doc comments (`///`) instead of
auto-generated tests names for parameterized matrix tests.

e.g. legacy compact syntax:

```rust
expected => [
        /// forty_two
        42,
        /// four
        2*3-2,
    ],
)]
fn test(expected: usize) { ... }
```

e.g. attribute syntax:

```rust
fn test(
    #[values(
        /// forty_two
        42,
        /// four
        2*3-2,
    )]
    expected: usize,
) { ... }
```

The generated test names will be `values_1_len_forty_two` and
`values_2_len_four`.

Fixes <#320>

Signed-off-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>

Author: orhun

CHANGELOG.md

@@ -9,6 +9,10 @@
 
 ### Add
 
+- Doc comments before `#[values(...)]` entries can be used to override the generated matrix
+  test names (both for the legacy `arg => [..]` syntax and the new attribute form).
+  See [#321](https://github.com/la10736/rstest/pull/321) thanks to @orhun.
+
 ### Fixed
 
 -  Fix compilation under bazel by upgrading proc-macro-crate to 3.4.0

rstest/src/lib.rs

@@ -938,6 +938,28 @@ pub use rstest_macros::fixture;
 /// Note that the test names contains the given expression sanitized into
 /// a valid Rust identifier name. This should help to identify which case fails.
 ///
+/// If you prefer to provide an explicit name you can use doc comments before
+/// each value inside the `#[values(...)]` attribute:
+///
+/// ```
+/// # use rstest::rstest;
+/// #[rstest]
+/// fn describe_values(
+///     #[values(
+///         /// short_value
+///         42,
+///         /// long_value
+///         100,
+///     )]
+///     value: u32,
+/// ) {
+///     assert!(value > 0);
+/// }
+/// ```
+///
+/// The generated tests will be named `value_1_short_value` and
+/// `value_2_long_value` instead of using the raw expression text.
+///
 ///
 /// Also value list implements the magic conversion feature: every time the value type
 /// implements `FromStr` trait you can use a literal string to define it.

rstest/tests/resources/rstest/matrix/simple.rs

@@ -7,3 +7,21 @@ use rstest::rstest;
 fn strlen_test(expected: usize, input: &str) {
     assert_eq!(expected, input.len());
 }
+
+#[rstest(
+    expected => [
+        /// len_four
+        4,
+        /// len_four_alt
+        2*3-2,
+    ],
+    input => [
+        /// greet_ciao
+        "ciao",
+        /// greet_buzz
+        "buzz",
+    ],
+)]
+fn doc_comment_strlen_test(expected: usize, input: &str) {
+    assert_eq!(expected, input.len());
+}

rstest/tests/resources/rstest/matrix/use_attr.rs

@@ -18,3 +18,65 @@ fn first(#[values(4, 2*3-2)] expected: usize, input: &str) {
 fn second(expected: usize, #[values("ciao", "buzz")] input: &str) {
     assert_eq!(expected, input.len());
 }
+
+#[rstest]
+fn doc_comment_both(
+    #[values(
+        /// len_four
+        4,
+        /// len_four_alt
+        2*3-2
+    )]
+    expected: usize,
+    #[values(
+        /// greet_ciao
+        "ciao",
+        /// greet_buzz
+        "buzz"
+    )]
+    input: &str,
+) {
+    assert_eq!(expected, input.len());
+}
+
+#[rstest(
+    input => [
+        /// greet_ciao
+        "ciao",
+        /// greet_buzz
+        "buzz",
+    ]
+)]
+fn doc_comment_first(
+    #[values(
+        /// len_four
+        4,
+        /// len_four_alt
+        2*3-2
+    )]
+    expected: usize,
+    input: &str,
+) {
+    assert_eq!(expected, input.len());
+}
+
+#[rstest(
+    expected => [
+        /// len_four
+        4,
+        /// len_four_alt
+        2*3-2,
+    ]
+)]
+fn doc_comment_second(
+    expected: usize,
+    #[values(
+        /// greet_ciao
+        "ciao",
+        /// greet_buzz
+        "buzz"
+    )]
+    input: &str,
+) {
+    assert_eq!(expected, input.len());
+}

rstest/tests/rstest/mod.rs

@@ -907,6 +907,10 @@ mod matrix {
             .ok("strlen_test::expected_1_4::input_2___buzz__")
             .ok("strlen_test::expected_2_2_3_2::input_1___ciao__")
             .ok("strlen_test::expected_2_2_3_2::input_2___buzz__")
+            .ok("doc_comment_strlen_test::expected_1_len_four::input_1_greet_ciao")
+            .ok("doc_comment_strlen_test::expected_1_len_four::input_2_greet_buzz")
+            .ok("doc_comment_strlen_test::expected_2_len_four_alt::input_1_greet_ciao")
+            .ok("doc_comment_strlen_test::expected_2_len_four_alt::input_2_greet_buzz")
             .assert(output);
     }
 
@@ -998,6 +1002,18 @@ mod matrix {
             .ok("second::expected_1_4::input_2___buzz__")
             .ok("second::expected_2_2_3_2::input_1___ciao__")
             .ok("second::expected_2_2_3_2::input_2___buzz__")
+            .ok("doc_comment_both::expected_1_len_four::input_1_greet_ciao")
+            .ok("doc_comment_both::expected_1_len_four::input_2_greet_buzz")
+            .ok("doc_comment_both::expected_2_len_four_alt::input_1_greet_ciao")
+            .ok("doc_comment_both::expected_2_len_four_alt::input_2_greet_buzz")
+            .ok("doc_comment_first::input_1_greet_ciao::expected_1_len_four")
+            .ok("doc_comment_first::input_2_greet_buzz::expected_1_len_four")
+            .ok("doc_comment_first::input_1_greet_ciao::expected_2_len_four_alt")
+            .ok("doc_comment_first::input_2_greet_buzz::expected_2_len_four_alt")
+            .ok("doc_comment_second::expected_1_len_four::input_1_greet_ciao")
+            .ok("doc_comment_second::expected_1_len_four::input_2_greet_buzz")
+            .ok("doc_comment_second::expected_2_len_four_alt::input_1_greet_ciao")
+            .ok("doc_comment_second::expected_2_len_four_alt::input_2_greet_buzz")
             .assert(output);
     }
 }

rstest_macros/src/parse/mod.rs

@@ -19,7 +19,9 @@ use quote::ToTokens;
 use testcase::TestCase;
 
 use self::{
-    expressions::Expressions, just_once::JustOnceFnArgAttributeExtractor, vlist::ValueList,
+    expressions::Expressions,
+    just_once::JustOnceFnArgAttributeExtractor,
+    vlist::{MatrixValues, ValueList},
 };
 
 // To use the macros this should be the first one module
@@ -363,10 +365,11 @@ impl VisitMut for CasesFunctionExtractor {
             if attr_starts_with(&attr, &case) {
                 match attr.parse_args::<Expressions>() {
                     Ok(expressions) => {
+                        let args = expressions.take();
                         let description =
                             attr.path().segments.iter().nth(1).map(|p| p.ident.clone());
                         self.0.push(TestCase {
-                            args: expressions.into(),
+                            args,
                             attrs: std::mem::take(&mut attrs_buffer),
                             description,
                         });
@@ -398,9 +401,9 @@ pub(crate) fn extract_value_list(item_fn: &mut ItemFn) -> Result<Vec<ValueList>,
         type Out = ValueList;
 
         fn build(attr: syn::Attribute, extra: &Pat) -> syn::Result<Self::Out> {
-            attr.parse_args::<Expressions>().map(|v| ValueList {
+            attr.parse_args::<MatrixValues>().map(|v| ValueList {
                 arg: extra.clone(),
-                values: v.take().into_iter().map(|e| e.into()).collect(),
+                values: v.into_values(),
             })
         }
     }

rstest_macros/src/parse/rstest.rs

@@ -1057,6 +1057,44 @@ mod test {
                     &pat("__destruct_2")
                 );
             }
+
+            #[test]
+            fn doc_comment_in_values_attribute_used_as_description() {
+                let mut item_fn = r#"
+                    fn test_fn(
+                        #[values(
+                            /// the answer
+                            42,
+                            /// bigger entry
+                            100,
+                            2
+                        )]
+                        arg: u32
+                    ) {
+                    }
+                "#
+                .ast();
+
+                let mut info = RsTestInfo::default();
+
+                info.extend_with_function_attrs(&mut item_fn).unwrap();
+
+                let list_values = info.data.list_values().cloned().collect::<Vec<_>>();
+
+                assert_eq!(1, list_values.len());
+                let values = &list_values[0].values;
+
+                assert_eq!(3, values.len());
+
+                assert_eq!("the_answer", values[0].description());
+                assert_eq!("42", values[0].expr.to_token_stream().to_string());
+
+                assert_eq!("bigger_entry", values[1].description());
+                assert_eq!("100", values[1].expr.to_token_stream().to_string());
+
+                assert_eq!("2", values[2].description());
+                assert_eq!("2", values[2].expr.to_token_stream().to_string());
+            }
         }
 
         #[test]