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