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