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