compiler/rustc_builtin_macros/src/test.rs

   1 /// The expansion from a test function to the appropriate test struct for libtest
   2 /// Ideally, this code would be in libtest but for efficiency and error messages it lives here.
   3 use crate::util::{check_builtin_macro_attribute, warn_on_duplicate_attribute};
   4 use rustc_ast as ast;
   5 use rustc_ast::ptr::P;
   6 use rustc_ast_pretty::pprust;
   7 use rustc_errors::Applicability;
   8 use rustc_expand::base::*;
   9 use rustc_session::Session;
  10 use rustc_span::symbol::{sym, Ident, Symbol};
  11 use rustc_span::Span;
  12 use std::iter;
  13 use thin_vec::thin_vec;
  14
  15 /// #[test_case] is used by custom test authors to mark tests
  16 /// When building for test, it needs to make the item public and gensym the name
  17 /// Otherwise, we'll omit the item. This behavior means that any item annotated
  18 /// with #[test_case] is never addressable.
  19 ///
  20 /// We mark item with an inert attribute "rustc_test_marker" which the test generation
  21 /// logic will pick up on.
  22 pub fn expand_test_case(
  23     ecx: &mut ExtCtxt<'_>,
  24     attr_sp: Span,
  25     meta_item: &ast::MetaItem,
  26     anno_item: Annotatable,
  27 ) -> Vec<Annotatable> {
  28     check_builtin_macro_attribute(ecx, meta_item, sym::test_case);
  29     warn_on_duplicate_attribute(&ecx, &anno_item, sym::test_case);
  30
  31     if !ecx.ecfg.should_test {
  32         return vec![];
  33     }
  34
  35     let sp = ecx.with_def_site_ctxt(attr_sp);
  36     let mut item = anno_item.expect_item();
  37     item = item.map(|mut item| {
  38         let test_path_symbol = Symbol::intern(&item_path(
  39             // skip the name of the root module
  40             &ecx.current_expansion.module.mod_path[1..],
  41             &item.ident,
  42         ));
  43         item.vis = ast::Visibility {
  44             span: item.vis.span,
  45             kind: ast::VisibilityKind::Public,
  46             tokens: None,
  47         };
  48         item.ident.span = item.ident.span.with_ctxt(sp.ctxt());
  49         item.attrs.push(ecx.attr_name_value_str(sym::rustc_test_marker, test_path_symbol, sp));
  50         item
  51     });
  52
  53     return vec![Annotatable::Item(item)];
  54 }
  55
  56 pub fn expand_test(
  57     cx: &mut ExtCtxt<'_>,
  58     attr_sp: Span,
  59     meta_item: &ast::MetaItem,
  60     item: Annotatable,
  61 ) -> Vec<Annotatable> {
  62     check_builtin_macro_attribute(cx, meta_item, sym::test);
  63     warn_on_duplicate_attribute(&cx, &item, sym::test);
  64     expand_test_or_bench(cx, attr_sp, item, false)
  65 }
  66
  67 pub fn expand_bench(
  68     cx: &mut ExtCtxt<'_>,
  69     attr_sp: Span,
  70     meta_item: &ast::MetaItem,
  71     item: Annotatable,
  72 ) -> Vec<Annotatable> {
  73     check_builtin_macro_attribute(cx, meta_item, sym::bench);
  74     warn_on_duplicate_attribute(&cx, &item, sym::bench);
  75     expand_test_or_bench(cx, attr_sp, item, true)
  76 }
  77
  78 pub fn expand_test_or_bench(
  79     cx: &mut ExtCtxt<'_>,
  80     attr_sp: Span,
  81     item: Annotatable,
  82     is_bench: bool,
  83 ) -> Vec<Annotatable> {
  84     // If we're not in test configuration, remove the annotated item
  85     if !cx.ecfg.should_test {
  86         return vec![];
  87     }
  88
  89     let (item, is_stmt) = match item {
  90         Annotatable::Item(i) => (i, false),
  91         Annotatable::Stmt(stmt) if matches!(stmt.kind, ast::StmtKind::Item(_)) => {
  92             // FIXME: Use an 'if let' guard once they are implemented
  93             if let ast::StmtKind::Item(i) = stmt.into_inner().kind {
  94                 (i, true)
  95             } else {
  96                 unreachable!()
  97             }
  98         }
  99         other => {
 100             cx.struct_span_err(
 101                 other.span(),
 102                 "`#[test]` attribute is only allowed on non associated functions",
 103             )
 104             .emit();
 105             return vec![other];
 106         }
 107     };
 108
 109     // Note: non-associated fn items are already handled by `expand_test_or_bench`
 110     let ast::ItemKind::Fn(fn_) = &item.kind else {
 111         let diag = &cx.sess.parse_sess.span_diagnostic;
 112         let msg = "the `#[test]` attribute may only be used on a non-associated function";
 113         let mut err = match item.kind {
 114             // These were a warning before #92959 and need to continue being that to avoid breaking
 115             // stable user code (#94508).
 116             ast::ItemKind::MacCall(_) => diag.struct_span_warn(attr_sp, msg),
 117             // `.forget_guarantee()` needed to get these two arms to match types. Because of how
 118             // locally close the `.emit()` call is I'm comfortable with it, but if it can be
 119             // reworked in the future to not need it, it'd be nice.
 120             _ => diag.struct_span_err(attr_sp, msg).forget_guarantee(),
 121         };
 122         err.span_label(attr_sp, "the `#[test]` macro causes a function to be run on a test and has no effect on non-functions")
 123             .span_label(item.span, format!("expected a non-associated function, found {} {}", item.kind.article(), item.kind.descr()))
 124             .span_suggestion(attr_sp, "replace with conditional compilation to make the item only exist when tests are being run", "#[cfg(test)]", Applicability::MaybeIncorrect)
 125             .emit();
 126
 127         return vec![Annotatable::Item(item)];
 128     };
 129
 130     // has_*_signature will report any errors in the type so compilation
 131     // will fail. We shouldn't try to expand in this case because the errors
 132     // would be spurious.
 133     if (!is_bench && !has_test_signature(cx, &item))
 134         || (is_bench && !has_bench_signature(cx, &item))
 135     {
 136         return vec![Annotatable::Item(item)];
 137     }
 138
 139     let sp = cx.with_def_site_ctxt(item.span);
 140     let ret_ty_sp = cx.with_def_site_ctxt(fn_.sig.decl.output.span());
 141     let attr_sp = cx.with_def_site_ctxt(attr_sp);
 142
 143     let test_id = Ident::new(sym::test, attr_sp);
 144
 145     // creates test::$name
 146     let test_path = |name| cx.path(ret_ty_sp, vec![test_id, Ident::from_str_and_span(name, sp)]);
 147
 148     // creates test::ShouldPanic::$name
 149     let should_panic_path = |name| {
 150         cx.path(
 151             sp,
 152             vec![
 153                 test_id,
 154                 Ident::from_str_and_span("ShouldPanic", sp),
 155                 Ident::from_str_and_span(name, sp),
 156             ],
 157         )
 158     };
 159
 160     // creates test::TestType::$name
 161     let test_type_path = |name| {
 162         cx.path(
 163             sp,
 164             vec![
 165                 test_id,
 166                 Ident::from_str_and_span("TestType", sp),
 167                 Ident::from_str_and_span(name, sp),
 168             ],
 169         )
 170     };
 171
 172     // creates $name: $expr
 173     let field = |name, expr| cx.field_imm(sp, Ident::from_str_and_span(name, sp), expr);
 174
 175     let test_fn = if is_bench {
 176         // A simple ident for a lambda
 177         let b = Ident::from_str_and_span("b", attr_sp);
 178
 179         cx.expr_call(
 180             sp,
 181             cx.expr_path(test_path("StaticBenchFn")),
 182             vec![
 183                 // |b| self::test::assert_test_result(
 184                 cx.lambda1(
 185                     sp,
 186                     cx.expr_call(
 187                         sp,
 188                         cx.expr_path(test_path("assert_test_result")),
 189                         vec![
 190                             // super::$test_fn(b)
 191                             cx.expr_call(
 192                                 ret_ty_sp,
 193                                 cx.expr_path(cx.path(sp, vec![item.ident])),
 194                                 vec![cx.expr_ident(sp, b)],
 195                             ),
 196                         ],
 197                     ),
 198                     b,
 199                 ), // )
 200             ],
 201         )
 202     } else {
 203         cx.expr_call(
 204             sp,
 205             cx.expr_path(test_path("StaticTestFn")),
 206             vec![
 207                 // || {
 208                 cx.lambda0(
 209                     sp,
 210                     // test::assert_test_result(
 211                     cx.expr_call(
 212                         sp,
 213                         cx.expr_path(test_path("assert_test_result")),
 214                         vec![
 215                             // $test_fn()
 216                             cx.expr_call(
 217                                 ret_ty_sp,
 218                                 cx.expr_path(cx.path(sp, vec![item.ident])),
 219                                 vec![],
 220                             ), // )
 221                         ],
 222                     ), // }
 223                 ), // )
 224             ],
 225         )
 226     };
 227
 228     let test_path_symbol = Symbol::intern(&item_path(
 229         // skip the name of the root module
 230         &cx.current_expansion.module.mod_path[1..],
 231         &item.ident,
 232     ));
 233
 234     let mut test_const = cx.item(
 235         sp,
 236         Ident::new(item.ident.name, sp),
 237         thin_vec![
 238             // #[cfg(test)]
 239             cx.attr_nested_word(sym::cfg, sym::test, attr_sp),
 240             // #[rustc_test_marker = "test_case_sort_key"]
 241             cx.attr_name_value_str(sym::rustc_test_marker, test_path_symbol, attr_sp),
 242         ],
 243         // const $ident: test::TestDescAndFn =
 244         ast::ItemKind::Const(
 245             ast::Defaultness::Final,
 246             cx.ty(sp, ast::TyKind::Path(None, test_path("TestDescAndFn"))),
 247             // test::TestDescAndFn {
 248             Some(
 249                 cx.expr_struct(
 250                     sp,
 251                     test_path("TestDescAndFn"),
 252                     vec![
 253                         // desc: test::TestDesc {
 254                         field(
 255                             "desc",
 256                             cx.expr_struct(
 257                                 sp,
 258                                 test_path("TestDesc"),
 259                                 vec![
 260                                     // name: "path::to::test"
 261                                     field(
 262                                         "name",
 263                                         cx.expr_call(
 264                                             sp,
 265                                             cx.expr_path(test_path("StaticTestName")),
 266                                             vec![cx.expr_str(sp, test_path_symbol)],
 267                                         ),
 268                                     ),
 269                                     // ignore: true | false
 270                                     field(
 271                                         "ignore",
 272                                         cx.expr_bool(sp, should_ignore(&cx.sess, &item)),
 273                                     ),
 274                                     // ignore_message: Some("...") | None
 275                                     field(
 276                                         "ignore_message",
 277                                         if let Some(msg) = should_ignore_message(cx, &item) {
 278                                             cx.expr_some(sp, cx.expr_str(sp, msg))
 279                                         } else {
 280                                             cx.expr_none(sp)
 281                                         },
 282                                     ),
 283                                     // compile_fail: true | false
 284                                     field("compile_fail", cx.expr_bool(sp, false)),
 285                                     // no_run: true | false
 286                                     field("no_run", cx.expr_bool(sp, false)),
 287                                     // should_panic: ...
 288                                     field(
 289                                         "should_panic",
 290                                         match should_panic(cx, &item) {
 291                                             // test::ShouldPanic::No
 292                                             ShouldPanic::No => {
 293                                                 cx.expr_path(should_panic_path("No"))
 294                                             }
 295                                             // test::ShouldPanic::Yes
 296                                             ShouldPanic::Yes(None) => {
 297                                                 cx.expr_path(should_panic_path("Yes"))
 298                                             }
 299                                             // test::ShouldPanic::YesWithMessage("...")
 300                                             ShouldPanic::Yes(Some(sym)) => cx.expr_call(
 301                                                 sp,
 302                                                 cx.expr_path(should_panic_path("YesWithMessage")),
 303                                                 vec![cx.expr_str(sp, sym)],
 304                                             ),
 305                                         },
 306                                     ),
 307                                     // test_type: ...
 308                                     field(
 309                                         "test_type",
 310                                         match test_type(cx) {
 311                                             // test::TestType::UnitTest
 312                                             TestType::UnitTest => {
 313                                                 cx.expr_path(test_type_path("UnitTest"))
 314                                             }
 315                                             // test::TestType::IntegrationTest
 316                                             TestType::IntegrationTest => {
 317                                                 cx.expr_path(test_type_path("IntegrationTest"))
 318                                             }
 319                                             // test::TestPath::Unknown
 320                                             TestType::Unknown => {
 321                                                 cx.expr_path(test_type_path("Unknown"))
 322                                             }
 323                                         },
 324                                     ),
 325                                     // },
 326                                 ],
 327                             ),
 328                         ),
 329                         // testfn: test::StaticTestFn(...) | test::StaticBenchFn(...)
 330                         field("testfn", test_fn), // }
 331                     ],
 332                 ), // }
 333             ),
 334         ),
 335     );
 336     test_const = test_const.map(|mut tc| {
 337         tc.vis.kind = ast::VisibilityKind::Public;
 338         tc
 339     });
 340
 341     // extern crate test
 342     let test_extern = cx.item(sp, test_id, ast::AttrVec::new(), ast::ItemKind::ExternCrate(None));
 343
 344     debug!("synthetic test item:\n{}\n", pprust::item_to_string(&test_const));
 345
 346     if is_stmt {
 347         vec![
 348             // Access to libtest under a hygienic name
 349             Annotatable::Stmt(P(cx.stmt_item(sp, test_extern))),
 350             // The generated test case
 351             Annotatable::Stmt(P(cx.stmt_item(sp, test_const))),
 352             // The original item
 353             Annotatable::Stmt(P(cx.stmt_item(sp, item))),
 354         ]
 355     } else {
 356         vec![
 357             // Access to libtest under a hygienic name
 358             Annotatable::Item(test_extern),
 359             // The generated test case
 360             Annotatable::Item(test_const),
 361             // The original item
 362             Annotatable::Item(item),
 363         ]
 364     }
 365 }
 366
 367 fn item_path(mod_path: &[Ident], item_ident: &Ident) -> String {
 368     mod_path
 369         .iter()
 370         .chain(iter::once(item_ident))
 371         .map(|x| x.to_string())
 372         .collect::<Vec<String>>()
 373         .join("::")
 374 }
 375
 376 enum ShouldPanic {
 377     No,
 378     Yes(Option<Symbol>),
 379 }
 380
 381 fn should_ignore(sess: &Session, i: &ast::Item) -> bool {
 382     sess.contains_name(&i.attrs, sym::ignore)
 383 }
 384
 385 fn should_ignore_message(cx: &ExtCtxt<'_>, i: &ast::Item) -> Option<Symbol> {
 386     match cx.sess.find_by_name(&i.attrs, sym::ignore) {
 387         Some(attr) => {
 388             match attr.meta_item_list() {
 389                 // Handle #[ignore(bar = "foo")]
 390                 Some(_) => None,
 391                 // Handle #[ignore] and #[ignore = "message"]
 392                 None => attr.value_str(),
 393             }
 394         }
 395         None => None,
 396     }
 397 }
 398
 399 fn should_panic(cx: &ExtCtxt<'_>, i: &ast::Item) -> ShouldPanic {
 400     match cx.sess.find_by_name(&i.attrs, sym::should_panic) {
 401         Some(attr) => {
 402             let sd = &cx.sess.parse_sess.span_diagnostic;
 403
 404             match attr.meta_item_list() {
 405                 // Handle #[should_panic(expected = "foo")]
 406                 Some(list) => {
 407                     let msg = list
 408                         .iter()
 409                         .find(|mi| mi.has_name(sym::expected))
 410                         .and_then(|mi| mi.meta_item())
 411                         .and_then(|mi| mi.value_str());
 412                     if list.len() != 1 || msg.is_none() {
 413                         sd.struct_span_warn(
 414                             attr.span,
 415                             "argument must be of the form: \
 416                              `expected = \"error message\"`",
 417                         )
 418                         .note(
 419                             "errors in this attribute were erroneously \
 420                                 allowed and will become a hard error in a \
 421                                 future release",
 422                         )
 423                         .emit();
 424                         ShouldPanic::Yes(None)
 425                     } else {
 426                         ShouldPanic::Yes(msg)
 427                     }
 428                 }
 429                 // Handle #[should_panic] and #[should_panic = "expected"]
 430                 None => ShouldPanic::Yes(attr.value_str()),
 431             }
 432         }
 433         None => ShouldPanic::No,
 434     }
 435 }
 436
 437 enum TestType {
 438     UnitTest,
 439     IntegrationTest,
 440     Unknown,
 441 }
 442
 443 /// Attempts to determine the type of test.
 444 /// Since doctests are created without macro expanding, only possible variants here
 445 /// are `UnitTest`, `IntegrationTest` or `Unknown`.
 446 fn test_type(cx: &ExtCtxt<'_>) -> TestType {
 447     // Root path from context contains the topmost sources directory of the crate.
 448     // I.e., for `project` with sources in `src` and tests in `tests` folders
 449     // (no matter how many nested folders lie inside),
 450     // there will be two different root paths: `/project/src` and `/project/tests`.
 451     let crate_path = cx.root_path.as_path();
 452
 453     if crate_path.ends_with("src") {
 454         // `/src` folder contains unit-tests.
 455         TestType::UnitTest
 456     } else if crate_path.ends_with("tests") {
 457         // `/tests` folder contains integration tests.
 458         TestType::IntegrationTest
 459     } else {
 460         // Crate layout doesn't match expected one, test type is unknown.
 461         TestType::Unknown
 462     }
 463 }
 464
 465 fn has_test_signature(cx: &ExtCtxt<'_>, i: &ast::Item) -> bool {
 466     let has_should_panic_attr = cx.sess.contains_name(&i.attrs, sym::should_panic);
 467     let sd = &cx.sess.parse_sess.span_diagnostic;
 468     match &i.kind {
 469         ast::ItemKind::Fn(box ast::Fn { sig, generics, .. }) => {
 470             if let ast::Unsafe::Yes(span) = sig.header.unsafety {
 471                 sd.struct_span_err(i.span, "unsafe functions cannot be used for tests")
 472                     .span_label(span, "`unsafe` because of this")
 473                     .emit();
 474                 return false;
 475             }
 476             if let ast::Async::Yes { span, .. } = sig.header.asyncness {
 477                 sd.struct_span_err(i.span, "async functions cannot be used for tests")
 478                     .span_label(span, "`async` because of this")
 479                     .emit();
 480                 return false;
 481             }
 482
 483             // If the termination trait is active, the compiler will check that the output
 484             // type implements the `Termination` trait as `libtest` enforces that.
 485             let has_output = match &sig.decl.output {
 486                 ast::FnRetTy::Default(..) => false,
 487                 ast::FnRetTy::Ty(t) if t.kind.is_unit() => false,
 488                 _ => true,
 489             };
 490
 491             if !sig.decl.inputs.is_empty() {
 492                 sd.span_err(i.span, "functions used as tests can not have any arguments");
 493                 return false;
 494             }
 495
 496             match (has_output, has_should_panic_attr) {
 497                 (true, true) => {
 498                     sd.span_err(i.span, "functions using `#[should_panic]` must return `()`");
 499                     false
 500                 }
 501                 (true, false) => {
 502                     if !generics.params.is_empty() {
 503                         sd.span_err(
 504                             i.span,
 505                             "functions used as tests must have signature fn() -> ()",
 506                         );
 507                         false
 508                     } else {
 509                         true
 510                     }
 511                 }
 512                 (false, _) => true,
 513             }
 514         }
 515         _ => {
 516             // should be unreachable because `is_test_fn_item` should catch all non-fn items
 517             debug_assert!(false);
 518             false
 519         }
 520     }
 521 }
 522
 523 fn has_bench_signature(cx: &ExtCtxt<'_>, i: &ast::Item) -> bool {
 524     let has_sig = match &i.kind {
 525         // N.B., inadequate check, but we're running
 526         // well before resolve, can't get too deep.
 527         ast::ItemKind::Fn(box ast::Fn { sig, .. }) => sig.decl.inputs.len() == 1,
 528         _ => false,
 529     };
 530
 531     if !has_sig {
 532         cx.sess.parse_sess.span_diagnostic.span_err(
 533             i.span,
 534             "functions used as benches must have \
 535             signature `fn(&mut Bencher) -> impl Termination`",
 536         );
 537     }
 538
 539     has_sig
 540 }