js/src/jit-test/README

   1 JS Trace Test Suite
   2
   3 * PURPOSE
   4
   5 This is a test suite for testing TraceMonkey. All tests are run in the JS shell
   6 with tracing enabled (-j).
   7
   8 * REQUIREMENTS
   9
  10 Python 2.5. This is already a standard requirement for building our tree.
  11
  12 * RUNNING THE TESTS
  13
  14 Basic usage:
  15
  16     python jit_test.py <path-to-js-shell>
  17
  18 The progress bar shows [#tests passed, #tests failed, #tests run] at the left.
  19 If all tests pass, the output is 'PASSED ALL'. The test suite can be interrupted
  20 at any time with Ctrl+C and partial results will be printed.
  21
  22 To run only the basic tests, not including the slow tests:
  23
  24     python jit_test.py <path-to-js-shell> basic
  25
  26 For more options:
  27
  28     python jit_test.py -h
  29
  30 * CREATING NEW TESTS
  31
  32 Simply create a JS file under the 'tests/' directory. Most tests should go in
  33 'tests/basic/'.
  34
  35 All tests are run with 'lib/prolog.js' included first on the command line. The
  36 command line also creates a global variable 'libdir' that is set to the path
  37 of the 'lib' directory. To include a file 'foo.js' from the lib directory in a
  38 test case:
  39
  40     load(libdir + 'foo.js')
  41
  42 * TEST METALINES
  43
  44 The first line of a test case can contain a special comment controlling how the
  45 test is run. For example:
  46
  47     // |jit-test| allow-oom;
  48
  49 The general format in EBNF is:
  50
  51     metaline  ::= cookie { item ";" }
  52     cookie    ::= "|jit-test|"
  53     item      ::= flag | attribute
  54
  55     flag      ::= "slow" | "allow-oom"
  56
  57     attribute ::= name ":" value
  58     name      ::= "TMFLAGS" | "error"
  59     value     ::= <string>
  60
  61 The metaline may appear anywhere in the first line of the file: this allows it
  62 to be placed inside any kind of comment.
  63
  64 The meaning of the items:
  65
  66     slow         Test runs slowly. Do not run if the --no-slow option is given.
  67     allow-oom    If the test runs out of memory, it counts as passing.
  68     valgrind     Run test under valgrind.
  69
  70     error        The test should be considered to pass iff it throws the
  71                  given JS exception.
  72     TMFLAGS      Set the environment variable TMFLAGS to the given value.
  73
  74 * END