src/libstd/test.rs

   1 // Support code for rustc's built in test runner generator. Currently,
   2 // none of this is meant for users. It is intended to support the
   3 // simplest interface possible for representing and running tests
   4 // while providing a base that other test frameworks may build off of.
   5
   6 import core::comm;
   7 import core::task;
   8 import task::task;
   9 import core::option;
  10 import core::either;
  11 import core::vec;
  12 import core::result::{ok, err};
  13
  14 export test_name;
  15 export test_fn;
  16 export default_test_fn;
  17 export test_desc;
  18 export test_main;
  19 export test_result;
  20 export test_opts;
  21 export tr_ok;
  22 export tr_failed;
  23 export tr_ignored;
  24 export run_tests_console;
  25 export run_tests_console_;
  26 export run_test;
  27 export filter_tests;
  28 export parse_opts;
  29 export test_to_task;
  30 export default_test_to_task;
  31 export configure_test_task;
  32 export joinable;
  33
  34 #[abi = "cdecl"]
  35 native mod rustrt {
  36     fn sched_threads() -> uint;
  37 }
  38
  39
  40 // The name of a test. By convention this follows the rules for rust
  41 // paths; i.e. it should be a series of identifiers seperated by double
  42 // colons. This way if some test runner wants to arrange the tests
  43 // hierarchically it may.
  44 type test_name = str;
  45
  46 // A function that runs a test. If the function returns successfully,
  47 // the test succeeds; if the function fails then the test fails. We
  48 // may need to come up with a more clever definition of test in order
  49 // to support isolation of tests into tasks.
  50 type test_fn<T> = T;
  51
  52 type default_test_fn = test_fn<fn()>;
  53
  54 // The definition of a single test. A test runner will run a list of
  55 // these.
  56 type test_desc<T> = {
  57     name: test_name,
  58     fn: test_fn<T>,
  59     ignore: bool,
  60     should_fail: bool
  61 };
  62
  63 // The default console test runner. It accepts the command line
  64 // arguments and a vector of test_descs (generated at compile time).
  65 fn test_main(args: [str], tests: [test_desc<default_test_fn>]) {
  66     check (vec::is_not_empty(args));
  67     let opts =
  68         alt parse_opts(args) {
  69           either::left(o) { o }
  70           either::right(m) { fail m }
  71         };
  72     if !run_tests_console(opts, tests) { fail "Some tests failed"; }
  73 }
  74
  75 type test_opts = {filter: option::t<str>, run_ignored: bool};
  76
  77 type opt_res = either::t<test_opts, str>;
  78
  79 // Parses command line arguments into test options
  80 fn parse_opts(args: [str]) : vec::is_not_empty(args) -> opt_res {
  81
  82     let args_ = vec::tail(args);
  83     let opts = [getopts::optflag("ignored")];
  84     let match =
  85         alt getopts::getopts(args_, opts) {
  86           ok(m) { m }
  87           err(f) { ret either::right(getopts::fail_str(f)) }
  88         };
  89
  90     let filter =
  91         if vec::len(match.free) > 0u {
  92             option::some(match.free[0])
  93         } else { option::none };
  94
  95     let run_ignored = getopts::opt_present(match, "ignored");
  96
  97     let test_opts = {filter: filter, run_ignored: run_ignored};
  98
  99     ret either::left(test_opts);
 100 }
 101
 102 tag test_result { tr_ok; tr_failed; tr_ignored; }
 103
 104 type joinable = (task, comm::port<task::task_notification>);
 105
 106 // To get isolation and concurrency tests have to be run in their own tasks.
 107 // In cases where test functions are closures it is not ok to just dump them
 108 // into a task and run them, so this transformation gives the caller a chance
 109 // to create the test task.
 110 type test_to_task<T> = fn@(test_fn<T>) -> joinable;
 111
 112 // A simple console test runner
 113 fn run_tests_console(opts: test_opts,
 114                          tests: [test_desc<default_test_fn>]) -> bool {
 115     run_tests_console_(opts, tests, default_test_to_task)
 116 }
 117
 118 fn run_tests_console_<T: copy>(opts: test_opts, tests: [test_desc<T>],
 119                               to_task: test_to_task<T>) -> bool {
 120
 121     type test_state =
 122         @{out: io::writer,
 123           use_color: bool,
 124           mutable total: uint,
 125           mutable passed: uint,
 126           mutable failed: uint,
 127           mutable ignored: uint,
 128           mutable failures: [test_desc<T>]};
 129
 130     fn callback<T: copy>(event: testevent<T>, st: test_state) {
 131         alt event {
 132           te_filtered(filtered_tests) {
 133             st.total = vec::len(filtered_tests);
 134             st.out.write_line(#fmt["\nrunning %u tests", st.total]);
 135           }
 136           te_wait(test) { st.out.write_str(#fmt["test %s ... ", test.name]); }
 137           te_result(test, result) {
 138             alt result {
 139               tr_ok. {
 140                 st.passed += 1u;
 141                 write_ok(st.out, st.use_color);
 142                 st.out.write_line("");
 143               }
 144               tr_failed. {
 145                 st.failed += 1u;
 146                 write_failed(st.out, st.use_color);
 147                 st.out.write_line("");
 148                 st.failures += [test];
 149               }
 150               tr_ignored. {
 151                 st.ignored += 1u;
 152                 write_ignored(st.out, st.use_color);
 153                 st.out.write_line("");
 154               }
 155             }
 156           }
 157         }
 158     }
 159
 160     let st =
 161         @{out: io::stdout(),
 162           use_color: use_color(),
 163           mutable total: 0u,
 164           mutable passed: 0u,
 165           mutable failed: 0u,
 166           mutable ignored: 0u,
 167           mutable failures: []};
 168
 169     run_tests(opts, tests, to_task, bind callback(_, st));
 170
 171     assert (st.passed + st.failed + st.ignored == st.total);
 172     let success = st.failed == 0u;
 173
 174     if !success {
 175         st.out.write_line("\nfailures:");
 176         for test: test_desc<T> in st.failures {
 177             let testname = test.name; // Satisfy alias analysis
 178             st.out.write_line(#fmt["    %s", testname]);
 179         }
 180     }
 181
 182     st.out.write_str(#fmt["\nresult: "]);
 183     if success {
 184         // There's no parallelism at this point so it's safe to use color
 185         write_ok(st.out, true);
 186     } else { write_failed(st.out, true); }
 187     st.out.write_str(#fmt[". %u passed; %u failed; %u ignored\n\n", st.passed,
 188                           st.failed, st.ignored]);
 189
 190     ret success;
 191
 192     fn write_ok(out: io::writer, use_color: bool) {
 193         write_pretty(out, "ok", term::color_green, use_color);
 194     }
 195
 196     fn write_failed(out: io::writer, use_color: bool) {
 197         write_pretty(out, "FAILED", term::color_red, use_color);
 198     }
 199
 200     fn write_ignored(out: io::writer, use_color: bool) {
 201         write_pretty(out, "ignored", term::color_yellow, use_color);
 202     }
 203
 204     fn write_pretty(out: io::writer, word: str, color: u8, use_color: bool) {
 205         if use_color && term::color_supported() {
 206             term::fg(out.get_buf_writer(), color);
 207         }
 208         out.write_str(word);
 209         if use_color && term::color_supported() {
 210             term::reset(out.get_buf_writer());
 211         }
 212     }
 213 }
 214
 215 fn use_color() -> bool { ret get_concurrency() == 1u; }
 216
 217 tag testevent<T> {
 218     te_filtered([test_desc<T>]);
 219     te_wait(test_desc<T>);
 220     te_result(test_desc<T>, test_result);
 221 }
 222
 223 fn run_tests<T: copy>(opts: test_opts, tests: [test_desc<T>],
 224                      to_task: test_to_task<T>,
 225                      callback: fn@(testevent<T>)) {
 226
 227     let filtered_tests = filter_tests(opts, tests);
 228     callback(te_filtered(filtered_tests));
 229
 230     // It's tempting to just spawn all the tests at once but that doesn't
 231     // provide a great user experience because you might sit waiting for the
 232     // result of a particular test for an unusually long amount of time.
 233     let concurrency = get_concurrency();
 234     #debug("using %u test tasks", concurrency);
 235     let total = vec::len(filtered_tests);
 236     let run_idx = 0u;
 237     let wait_idx = 0u;
 238     let futures = [];
 239
 240     while wait_idx < total {
 241         while vec::len(futures) < concurrency && run_idx < total {
 242             futures += [run_test(filtered_tests[run_idx], to_task)];
 243             run_idx += 1u;
 244         }
 245
 246         let future = futures[0];
 247         callback(te_wait(future.test));
 248         let result = future.wait();
 249         callback(te_result(future.test, result));
 250         futures = vec::slice(futures, 1u, vec::len(futures));
 251         wait_idx += 1u;
 252     }
 253 }
 254
 255 fn get_concurrency() -> uint { rustrt::sched_threads() }
 256
 257 fn filter_tests<T: copy>(opts: test_opts,
 258                         tests: [test_desc<T>]) -> [test_desc<T>] {
 259     let filtered = tests;
 260
 261     // Remove tests that don't match the test filter
 262     filtered = if option::is_none(opts.filter) {
 263         filtered
 264     } else {
 265         let filter_str =
 266             alt opts.filter {
 267           option::some(f) { f }
 268           option::none. { "" }
 269         };
 270
 271         fn filter_fn<T: copy>(test: test_desc<T>, filter_str: str) ->
 272             option::t<test_desc<T>> {
 273             if str::find(test.name, filter_str) >= 0 {
 274                 ret option::some(test);
 275             } else { ret option::none; }
 276         }
 277
 278         let filter = bind filter_fn(_, filter_str);
 279
 280         vec::filter_map(filtered, filter)
 281     };
 282
 283     // Maybe pull out the ignored test and unignore them
 284     filtered = if !opts.run_ignored {
 285         filtered
 286     } else {
 287         fn filter<T: copy>(test: test_desc<T>) -> option::t<test_desc<T>> {
 288             if test.ignore {
 289                 ret option::some({name: test.name,
 290                                   fn: test.fn,
 291                                   ignore: false,
 292                                   should_fail: test.should_fail});
 293             } else { ret option::none; }
 294         };
 295
 296         vec::filter_map(filtered, bind filter(_))
 297     };
 298
 299     // Sort the tests alphabetically
 300     filtered =
 301         {
 302             fn lteq<T>(t1: test_desc<T>, t2: test_desc<T>) -> bool {
 303                 str::lteq(t1.name, t2.name)
 304             }
 305             sort::merge_sort(bind lteq(_, _), filtered)
 306         };
 307
 308     ret filtered;
 309 }
 310
 311 type test_future<T> = {test: test_desc<T>, wait: fn@() -> test_result};
 312
 313 fn run_test<T: copy>(test: test_desc<T>,
 314                     to_task: test_to_task<T>) -> test_future<T> {
 315     if test.ignore {
 316         ret {test: test, wait: fn () -> test_result { tr_ignored }};
 317     }
 318
 319     let test_task = to_task(test.fn);
 320     ret {test: test,
 321          wait:
 322              bind fn (test_task: joinable, should_fail: bool) -> test_result {
 323                   alt task::join(test_task) {
 324                     task::tr_success. {
 325                       if should_fail { tr_failed }
 326                       else { tr_ok }
 327                     }
 328                     task::tr_failure. {
 329                       if should_fail { tr_ok }
 330                       else { tr_failed }
 331                     }
 332                   }
 333               }(test_task, test.should_fail)};
 334 }
 335
 336 // We need to run our tests in another task in order to trap test failures.
 337 // This function only works with functions that don't contain closures.
 338 fn default_test_to_task(&&f: default_test_fn) -> joinable {
 339     fn run_task(f: default_test_fn) {
 340         configure_test_task();
 341         f();
 342     }
 343     ret task::spawn_joinable(copy f, run_task);
 344 }
 345
 346 // Call from within a test task to make sure it's set up correctly
 347 fn configure_test_task() {
 348     // If this task fails we don't want that failure to propagate to the
 349     // test runner or else we couldn't keep running tests
 350     task::unsupervise();
 351 }
 352
 353 // Local Variables:
 354 // mode: rust;
 355 // fill-column: 78;
 356 // indent-tabs-mode: nil
 357 // c-basic-offset: 4
 358 // buffer-file-coding-system: utf-8-unix
 359 // End: