gecko/js/src/trace-test

JS Trace Test Suite

* PURPOSE

This is a test suite for testing TraceMonkey. All tests are run in the JS shell
with tracing enabled (-j).

* REQUIREMENTS

Python 2.5. This is already a standard requirement for building our tree.

* RUNNING THE TESTS

Basic usage:

    python trace-test.py <path-to-js-shell>

The progress bar shows [#tests passed, #tests failed, #tests run] at the left.
If all tests pass, the output is 'PASSED ALL'. The test suite can be interrupted
at any time with Ctrl+C and partial results will be printed.

To run only the basic tests, not including the slow tests:

    python trace-test.py <path-to-js-shell> basic

For more options:

    python trace-test.py -h

* CREATING NEW TESTS

Simply create a JS file under the 'tests/' directory. Most tests should go in
'tests/basic/'.

All tests are run with 'lib/prolog.js' included first on the command line. The
command line also creates a global variable 'libdir' that is set to the path
of the 'lib' directory. To include a file 'foo.js' from the lib directory in a 
test case:

    load(libdir + 'foo.js')

* TEST METALINES

The first line of a test case can contain a special comment controlling how the
test is run. For example:

    // |trace-test| allow-oom;

The general format in EBNF is:

    metaline  ::= cookie { item ";" }
    cookie    ::= "|trace-test|"
    item      ::= flag | attribute

    flag      ::= "slow" | "allow-oom"

    attribute ::= name ":" value
    name      ::= "TMFLAGS"
    value     ::= <string>

The metaline may appear anywhere in the first line of the file: this allows it
to be placed inside any kind of comment.

The meaning of the items:

    slow         Test runs slowly. Do not run if the --no-slow option is given.
    allow-oom    If the test runs out of memory, it counts as passing.
    TMFLAGS      Set the environment variable TMFLAGS to the given value.

* END