Forward attributes on spec! it cases to the generated #[test] (#3)

Attributes written before an `it` (#[ignore], #[should_panic], #[cfg(...)],
and so on) are now parsed and emitted on the generated test function, so the
DSL matches what attribute-style #[test_suite] already allows.

Attributes on hooks (before/after/before_each/after_each) are rejected with a
clear compile error, since a hook isn't a standalone function and the
attribute would otherwise be dropped silently.

Author: brianp

crates/spectacular-macros/src/spec.rs

@@ -9,6 +9,17 @@ use crate::{
     wrap_test_body,
 };
 
+/// A parsed `it` case ready for code generation:
+/// `(description, fn name, body, is_async, params, forwarded attributes)`.
+type SpecTest = (
+    String,
+    Ident,
+    proc_macro2::TokenStream,
+    bool,
+    Vec<PipeParam>,
+    Vec<syn::Attribute>,
+);
+
 /// A parsed parameter from pipe syntax: `|name: &Type, name2: Type|`
 pub(crate) struct PipeParam {
     pat: syn::Pat,
@@ -30,8 +41,14 @@ pub(crate) enum SpecItem {
     //         body                     async  return_type          input_params
     AfterEach(proc_macro2::TokenStream, bool, Vec<PipeParam>),
     //        body                      async  params
-    It(String, proc_macro2::TokenStream, bool, Vec<PipeParam>),
-    //         body                      async  params
+    It(
+        String,
+        proc_macro2::TokenStream,
+        bool,
+        Vec<PipeParam>,
+        Vec<syn::Attribute>,
+    ),
+    //         body                      async  params          attrs
     Other(proc_macro2::TokenStream),
 }
 
@@ -63,6 +80,19 @@ fn parse_pipe_params(input: ParseStream) -> syn::Result<Vec<PipeParam>> {
     Ok(params)
 }
 
+/// Reject attributes on a construct that can't carry them. Attributes are only
+/// forwarded on `it` test cases; hooks and the `suite;`/runtime markers are not
+/// standalone functions, so an attribute there would be silently dropped.
+fn reject_attrs(attrs: &[syn::Attribute], keyword: &str) -> syn::Result<()> {
+    if let Some(attr) = attrs.first() {
+        return Err(syn::Error::new_spanned(
+            attr,
+            format!("attributes are not supported on `{keyword}` (only on `it` test cases)"),
+        ));
+    }
+    Ok(())
+}
+
 /// Parse optional `-> Type` return type.
 fn parse_return_type(input: ParseStream) -> syn::Result<Option<syn::Type>> {
     if input.peek(Token![->]) {
@@ -97,6 +127,10 @@ impl Parse for SpecModule {
         let mut items = Vec::new();
 
         while !content.is_empty() {
+            // Leading `#[...]` attributes are forwarded to `it` test cases and
+            // re-attached to plain items; they're rejected on hooks/markers.
+            let attrs = content.call(syn::Attribute::parse_outer)?;
+
             // Check for `async` keyword first
             if content.peek(Token![async]) {
                 let fork = content.fork();
@@ -112,10 +146,17 @@ impl Parse for SpecModule {
                             let params = parse_pipe_params(&content)?;
                             let body;
                             braced!(body in content);
-                            items.push(SpecItem::It(desc.value(), body.parse()?, true, params));
+                            items.push(SpecItem::It(
+                                desc.value(),
+                                body.parse()?,
+                                true,
+                                params,
+                                attrs,
+                            ));
                             continue;
                         }
                         "before_each" => {
+                            reject_attrs(&attrs, "before_each")?;
                             let _: Token![async] = content.parse()?;
                             let _: Ident = content.parse()?;
                             let params = parse_pipe_params(&content)?;
@@ -126,6 +167,7 @@ impl Parse for SpecModule {
                             continue;
                         }
                         "after_each" => {
+                            reject_attrs(&attrs, "after_each")?;
                             let _: Token![async] = content.parse()?;
                             let _: Ident = content.parse()?;
                             let params = parse_pipe_params(&content)?;
@@ -141,7 +183,7 @@ impl Parse for SpecModule {
                 }
                 // Fall through: parse as regular item (e.g. `async fn helper()`)
                 let item: syn::Item = content.parse()?;
-                items.push(SpecItem::Other(quote! { #item }));
+                items.push(SpecItem::Other(quote! { #(#attrs)* #item }));
                 continue;
             }
 
@@ -150,18 +192,21 @@ impl Parse for SpecModule {
                 let kw: Ident = fork.parse()?;
                 match kw.to_string().as_str() {
                     "suite" => {
+                        reject_attrs(&attrs, "suite")?;
                         let _: Ident = content.parse()?;
                         content.parse::<Token![;]>()?;
                         items.push(SpecItem::Suite);
                         continue;
                     }
                     "tokio" => {
+                        reject_attrs(&attrs, "tokio")?;
                         let _: Ident = content.parse()?;
                         content.parse::<Token![;]>()?;
                         items.push(SpecItem::Runtime(Runtime::Tokio));
                         continue;
                     }
                     "async_std" => {
+                        reject_attrs(&attrs, "async_std")?;
                         let _: Ident = content.parse()?;
                         content.parse::<Token![;]>()?;
                         items.push(SpecItem::Runtime(Runtime::AsyncStd));
@@ -173,10 +218,17 @@ impl Parse for SpecModule {
                         let params = parse_pipe_params(&content)?;
                         let body;
                         braced!(body in content);
-                        items.push(SpecItem::It(desc.value(), body.parse()?, false, params));
+                        items.push(SpecItem::It(
+                            desc.value(),
+                            body.parse()?,
+                            false,
+                            params,
+                            attrs,
+                        ));
                         continue;
                     }
                     "before_each" => {
+                        reject_attrs(&attrs, "before_each")?;
                         let _: Ident = content.parse()?;
                         let params = parse_pipe_params(&content)?;
                         let ret_ty = parse_return_type(&content)?;
@@ -186,6 +238,7 @@ impl Parse for SpecModule {
                         continue;
                     }
                     "after_each" => {
+                        reject_attrs(&attrs, "after_each")?;
                         let _: Ident = content.parse()?;
                         let params = parse_pipe_params(&content)?;
                         let body;
@@ -194,6 +247,7 @@ impl Parse for SpecModule {
                         continue;
                     }
                     "before" => {
+                        reject_attrs(&attrs, "before")?;
                         let _: Ident = content.parse()?;
                         let ret_ty = parse_return_type(&content)?;
                         if content.peek(syn::token::Brace) {
@@ -206,6 +260,7 @@ impl Parse for SpecModule {
                         }
                     }
                     "after" => {
+                        reject_attrs(&attrs, "after")?;
                         let _: Ident = content.parse()?;
                         let params = parse_pipe_params(&content)?;
                         if content.peek(syn::token::Brace) {
@@ -219,13 +274,13 @@ impl Parse for SpecModule {
                     }
                     _ => {
                         let item: syn::Item = content.parse()?;
-                        items.push(SpecItem::Other(quote! { #item }));
+                        items.push(SpecItem::Other(quote! { #(#attrs)* #item }));
                         continue;
                     }
                 }
             }
             let item: syn::Item = content.parse()?;
-            items.push(SpecItem::Other(quote! { #item }));
+            items.push(SpecItem::Other(quote! { #(#attrs)* #item }));
         }
 
         Ok(SpecModule { vis, ident, items })
@@ -254,13 +309,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
     let mut after_each_body: Option<proc_macro2::TokenStream> = None;
     let mut after_each_is_async = false;
     let mut after_each_params: Vec<PipeParam> = Vec::new();
-    let mut tests: Vec<(
-        String,
-        Ident,
-        proc_macro2::TokenStream,
-        bool,
-        Vec<PipeParam>,
-    )> = Vec::new();
+    let mut tests: Vec<SpecTest> = Vec::new();
     let mut other_items: Vec<proc_macro2::TokenStream> = Vec::new();
 
     for item in parsed.items {
@@ -318,9 +367,9 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
                 after_each_is_async = is_async;
                 after_each_params = params;
             }
-            SpecItem::It(desc, body, is_async, params) => {
+            SpecItem::It(desc, body, is_async, params, attrs) => {
                 let fn_name = format_ident!("{}", slugify(&desc));
-                tests.push((desc, fn_name, body, is_async, params));
+                tests.push((desc, fn_name, body, is_async, params, attrs));
             }
             SpecItem::Other(tokens) => {
                 other_items.push(tokens);
@@ -329,7 +378,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
     }
 
     // Validate: async items require a runtime
-    let any_async = tests.iter().any(|(_, _, _, is_async, _)| *is_async)
+    let any_async = tests.iter().any(|(_, _, _, is_async, _, _)| *is_async)
         || before_each_is_async
         || after_each_is_async;
 
@@ -361,7 +410,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
             .iter()
             .chain(before_each_params.iter())
             .chain(after_each_params.iter())
-            .chain(tests.iter().flat_map(|(_, _, _, _, p)| p.iter()));
+            .chain(tests.iter().flat_map(|(_, _, _, _, p, _)| p.iter()));
         for p in ref_sources {
             if p.is_ref
                 && let Some(inner) = ref_inner_type(&p.ty)
@@ -382,7 +431,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
     // Detect inline mode from consumers: tests or after_each have `_`-typed params
     let has_infer_consumers = tests
         .iter()
-        .any(|(_, _, _, _, params)| params.iter().any(|p| is_type_infer(&p.ty)))
+        .any(|(_, _, _, _, params, _)| params.iter().any(|p| is_type_infer(&p.ty)))
         || after_each_params.iter().any(|p| is_type_infer(&p.ty));
     let before_each_needs_inline = !has_before_each_ctx && has_infer_consumers;
     let after_each_needs_inline = after_each_params.iter().any(|p| is_type_infer(&p.ty));
@@ -514,7 +563,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
 
     let test_fn_defs: Vec<proc_macro2::TokenStream> = tests
         .iter()
-        .map(|(_desc, fn_name, body, is_async, test_params)| {
+        .map(|(_desc, fn_name, body, is_async, test_params, attrs)| {
             // A test needs async if it's declared async or any hook it uses is async
             let test_needs_async = *is_async || before_each_is_async || after_each_is_async;
 
@@ -755,6 +804,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
                 let inner = wrap_async_test_body(pre, body_with_bindings, post, needs_catch);
 
                 quote! {
+                    #(#attrs)*
                     #test_attr
                     async fn #fn_name() {
                         #inner
@@ -764,6 +814,7 @@ pub(crate) fn expand(input: proc_macro2::TokenStream) -> syn::Result<proc_macro2
                 let inner = wrap_test_body(pre, body_with_bindings, post, needs_catch);
 
                 quote! {
+                    #(#attrs)*
                     #[test]
                     fn #fn_name() {
                         #inner

crates/spectacular/src/lib.rs

@@ -438,6 +438,34 @@ pub use spectacular_macros::suite;
 /// }
 /// # fn main() {}
 /// ```
+///
+/// # Attributes on `it`
+///
+/// Attributes written before an `it` case are forwarded to the generated
+/// `#[test]` function, so `#[ignore]`, `#[should_panic]`, `#[cfg(...)]`, and
+/// the like work just as they do on a plain test:
+///
+/// ```
+/// use spectacular::spec;
+///
+/// spec! {
+///     mod with_attrs {
+///         #[should_panic(expected = "boom")]
+///         it "panics as expected" {
+///             panic!("boom");
+///         }
+///
+///         #[ignore]
+///         it "skipped by default" {
+///             // only runs with `--ignored`
+///         }
+///     }
+/// }
+/// # fn main() {}
+/// ```
+///
+/// Attributes on hooks (`before`, `after`, `before_each`, `after_each`) are not
+/// supported and produce a compile error.
 pub use spectacular_macros::spec;
 
 /// Marks a module as a test suite using standard Rust attribute syntax.

crates/spectacular/tests/integration.rs

@@ -1148,3 +1148,50 @@ fn after_runs_at_process_exit_even_when_filtered() {
         "`#[after]` ran but received the wrong `#[before]` context at exit"
     );
 }
+
+// ===== Attribute passthrough on spec! `it` cases =====
+//
+// Attributes written before an `it` are forwarded to the generated `#[test]`
+// function, so standard test attributes work in the DSL just like in
+// attribute style.
+
+spec! {
+    mod spec_attr_passthrough {
+        it "a normal test still runs" {
+            assert_eq!(1 + 1, 2);
+        }
+
+        // Forwarded to `#[test]`: the body panics and the test passes.
+        #[should_panic(expected = "boom")]
+        it "should_panic is applied" {
+            panic!("boom");
+        }
+
+        // Forwarded to `#[test]`: this test is skipped by the default runner.
+        // If the attribute were dropped, the panic would fail the run.
+        #[ignore]
+        it "ignore is applied" {
+            panic!("an ignored test must never run");
+        }
+
+        // Excluded from compilation entirely. The body would not type-check if
+        // it were compiled, which proves the `#[cfg]` gate reached the item.
+        #[cfg(any())]
+        it "cfg-excluded never compiles" {
+            let _: () = "definitely not a unit value";
+        }
+    }
+}
+
+// Passthrough also works on `async it`.
+spec! {
+    mod spec_attr_passthrough_async {
+        tokio;
+
+        #[should_panic(expected = "async boom")]
+        async it "should_panic on an async it" {
+            tokio::task::yield_now().await;
+            panic!("async boom");
+        }
+    }
+}

docs/src/content/docs/guides/spec-dsl.md

@@ -284,6 +284,35 @@ The macro detects `_`-typed params in tests or `after_each` and inlines the `bef
 
 Hooks without return types or `_` params continue to work as fire-and-forget (unchanged).
 
+## Attributes on tests
+
+Attributes written before an `it` case are forwarded to the generated `#[test]` function, so the standard test attributes work here too:
+
+```rust
+use spectacular::spec;
+
+spec! {
+    mod with_attrs {
+        #[should_panic(expected = "boom")]
+        it "panics as expected" {
+            panic!("boom");
+        }
+
+        #[ignore]
+        it "skipped unless you pass --ignored" {
+            // ...
+        }
+
+        #[cfg(feature = "integration")]
+        it "only compiled with the integration feature" {
+            // ...
+        }
+    }
+}
+```
+
+This also works on `async it`. Attributes on hooks (`before`, `after`, `before_each`, `after_each`) aren't supported and produce a compile error.
+
 ## Visibility
 
 The generated module inherits the visibility you declare: