js/src/jit-test/README

   1 JS Internal Test Suite
   2
   3 * PURPOSE
   4
   5 This is a test suite primarily for testing the SpiderMonkey JIT, GC, and any
   6 other internal mechanisms that are not visible to test262. All tests are run in
   7 the JS shell.
   8
   9 In the future, we intend to migrate the "non262" jstests over to this framework.
  10
  11 * CONTINUOUS INTEGRATION
  12
  13 In CI, these tests will be run as part of the "SM(...)" set of jobs. They will
  14 also be packaged up and then run via mozharness as separate test jobs on some
  15 platforms. These will appear on treeherder as jobs starting with "Jit", eg
  16 "Jit", "Jit3", "Jit-1proc3", etc.
  17
  18 Unlike jstests, we do not run jit-tests in the browser. All tests may assume
  19 they are running in the JS shell environment.
  20
  21 * REQUIREMENTS
  22
  23 Python 3.7. This is already a standard requirement for building our tree.
  24
  25 * RUNNING THE TESTS
  26
  27 Basic usage:
  28
  29     ./mach jit-test
  30
  31 from the top of the checkout. Directly invoking
  32
  33     python jit_test.py <path-to-js-shell>
  34
  35 will also work. The progress bar shows [#tests passed, #tests failed, #tests
  36 run] at the left. If all tests pass, the output is 'PASSED ALL'. The test suite
  37 can be interrupted at any time with Ctrl+C and partial results will be printed.
  38
  39 To run only the basic tests, not including the slow tests:
  40
  41     ./mach jit-test <path-to-js-shell> basic
  42
  43 For more options:
  44
  45     ./mach jit-test -- -h
  46
  47 or
  48
  49     python jit_test.py -h
  50
  51 for the jit-test harness options, or
  52
  53     ./mach jit-test -h
  54
  55 for the mach driver's options (eg --cgc).
  56
  57 * CREATING NEW TESTS
  58
  59 Simply create a JS file under the 'tests/' directory. Most tests should go in
  60 'tests/basic/'.
  61
  62 All tests are run with 'lib/prologue.js' included first on the command line. The
  63 command line also creates a global variable 'libdir' that is set to the path
  64 of the 'lib' directory. To include a file 'foo.js' from the lib directory in a
  65 test case:
  66
  67     load(libdir + 'foo.js')
  68
  69 * TEST METALINES
  70
  71 The first line of a test case can contain a special comment controlling how the
  72 test is run. For example:
  73
  74     // |jit-test| allow-oom; --no-threads
  75
  76 The general format in EBNF is:
  77
  78     metaline  ::= cookie { item ";" }
  79     cookie    ::= "|jit-test|"
  80     item      ::= flag | attribute
  81
  82     flag      ::= "slow" | "allow-oom" | "valgrind" | "tz-pacific" | "debug" |
  83                   "--" switch
  84
  85     attribute ::= name ":" value
  86     name      ::= "error" | "exitstatus"
  87     value     ::= <string>
  88     switch    ::= <string>
  89
  90 The metaline may appear anywhere in the first line of the file: this allows it
  91 to be placed inside any kind of comment.
  92
  93 The meaning of the items:
  94
  95     slow         Test runs slowly. Do not run if the --no-slow option is given.
  96     allow-oom    If the test runs out of memory, it counts as passing.
  97     valgrind     Run test under valgrind.
  98     tz-pacific   Always run test with the Pacific time zone (TZ=PST8PDT).
  99
 100     error        The test should be considered to pass iff it throws the
 101                  given JS exception.
 102     exitstatus   The test should exit with the given status value (an integer).
 103
 104     debug        Run js with -d, whether --jitflags says to or not
 105     --SWITCH     Pass --SWITCH through to js
 106
 107 * END