michael@0: JS Trace Test Suite
michael@0: 
michael@0: * PURPOSE
michael@0: 
michael@0: This is a test suite for testing TraceMonkey. All tests are run in the JS shell
michael@0: with tracing enabled (-j).
michael@0: 
michael@0: * REQUIREMENTS
michael@0: 
michael@0: Python 2.5. This is already a standard requirement for building our tree.
michael@0: 
michael@0: * RUNNING THE TESTS
michael@0: 
michael@0: Basic usage:
michael@0: 
michael@0:     python jit_test.py <path-to-js-shell>
michael@0: 
michael@0: The progress bar shows [#tests passed, #tests failed, #tests run] at the left.
michael@0: If all tests pass, the output is 'PASSED ALL'. The test suite can be interrupted
michael@0: at any time with Ctrl+C and partial results will be printed.
michael@0: 
michael@0: To run only the basic tests, not including the slow tests:
michael@0: 
michael@0:     python jit_test.py <path-to-js-shell> basic
michael@0: 
michael@0: For more options:
michael@0: 
michael@0:     python jit_test.py -h
michael@0: 
michael@0: * CREATING NEW TESTS
michael@0: 
michael@0: Simply create a JS file under the 'tests/' directory. Most tests should go in
michael@0: 'tests/basic/'.
michael@0: 
michael@0: All tests are run with 'lib/prolog.js' included first on the command line. The
michael@0: command line also creates a global variable 'libdir' that is set to the path
michael@0: of the 'lib' directory. To include a file 'foo.js' from the lib directory in a 
michael@0: test case:
michael@0: 
michael@0:     load(libdir + 'foo.js')
michael@0: 
michael@0: * TEST METALINES
michael@0: 
michael@0: The first line of a test case can contain a special comment controlling how the
michael@0: test is run. For example:
michael@0: 
michael@0:     // |jit-test| allow-oom;
michael@0: 
michael@0: The general format in EBNF is:
michael@0: 
michael@0:     metaline  ::= cookie { item ";" }
michael@0:     cookie    ::= "|jit-test|"
michael@0:     item      ::= flag | attribute
michael@0: 
michael@0:     flag      ::= "slow" | "allow-oom" | "valgrind" | "tz-pacific" |
michael@0:                   "ion-eager" | "debug" |
michael@0:                   "dump-bytecode" |
michael@0: 
michael@0: 
michael@0:     attribute ::= name ":" value
michael@0:     name      ::= "error" | "exitstatus"
michael@0:     value     ::= <string>
michael@0: 
michael@0: The metaline may appear anywhere in the first line of the file: this allows it
michael@0: to be placed inside any kind of comment.
michael@0: 
michael@0: The meaning of the items:
michael@0: 
michael@0:     slow         Test runs slowly. Do not run if the --no-slow option is given.
michael@0:     allow-oom    If the test runs out of memory, it counts as passing.
michael@0:     valgrind     Run test under valgrind.
michael@0:     tz-pacific   Always run test with the Pacific time zone (TZ=PST8PDT).
michael@0:     ion-eager    Run js with --ion-eager, whether --jitflags says to or not
michael@0:     debug        Run js with -d, whether --jitflags says to or not
michael@0:     dump-bytecode Run js with -D, whether --jitflags says to or not
michael@0: 
michael@0:     error        The test should be considered to pass iff it throws the
michael@0:                  given JS exception.
michael@0:     exitstatus   The test should exit with the given status value (an integer).
michael@0: 
michael@0: * END