tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

README (4373B)

      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.9. 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" | "heavy" | "allow-oom" | "allow-unhandlable-oom" |
     83                   "allow-overrecursed" | "valgrind" | "tz-pacific" | "module" |
     84                   "crash" | "test-also=" values | "test-join=" values |
     85                   "--" switch | "-P" pref
     86 
     87     attribute ::= name ":" value
     88     name      ::= "error" | "exitstatus" | "thread-count" | "include" |
     89                   "local-include" | "skip-if" | "skip-variant-if"
     90     value     ::= <string>
     91     values    ::= <whitespace-separated-strings>
     92     switch    ::= <string>
     93     pref      ::= <string>
     94 
     95 The metaline may appear anywhere in the first line of the file: this allows it
     96 to be placed inside any kind of comment.
     97 
     98 The meaning of the items:
     99 
    100     slow              Test runs slowly. Do not run if the --no-slow option is given.
    101     heavy             Test is heavy and should not be run in parallel with other tests.
    102     allow-oom         If the test runs out of memory, it counts as passing.
    103     allow-unhandlable-oom  Allow unhandlable OOM errors (used for testing OOM handling).
    104     allow-overrecursed     Allow over-recursion errors.
    105     valgrind          Run test under valgrind.
    106     tz-pacific        Always run test with the Pacific time zone (TZ=PST8PDT).
    107     module            Test file is a module.
    108     crash             Test is expected to crash (only allowed in self-test).
    109     test-also=        Run the test with additional configurations (space-separated).
    110     test-join=        Join multiple tests together (space-separated).
    111 
    112     error             The test should be considered to pass iff it throws the
    113                       given JS exception.
    114     exitstatus        The test should exit with the given status value (an integer).
    115     thread-count      Set the number of threads for the test.
    116     include           Include additional library files.
    117     local-include     Include additional script files from the test directory.
    118     skip-if           Skip test if the condition is true.
    119     skip-variant-if   Skip specific test variant if the condition is true (format: variant,condition).
    120 
    121     --SWITCH          Pass --SWITCH through to js
    122     -P pref=value     Set a preference (e.g., -P pref=value)
    123 
    124 * END