{# This Source Code Form is subject to the terms of the Mozilla Public # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at http://mozilla.org/MPL/2.0/. #}

# jsDriver.pl

NAME
  jsDriver.pl - execute JavaScript programs in various shells in batch or single mode, reporting on failures encountered.
SYNOPSIS

  `jsDriver.pl` | `[-hkt] [-b BUGURL] [-c CLASSPATH] [-f OUTFILE] [-j JAVAPATH] [-l TESTLIST ...] [-L NEGLIST ...] [-p TESTPATH] [-s SHELLPATH] [-u LXRURL] [--help] [--confail] [--trace] [--classpath=CLASSPATH] [--file=OUTFILE] [--javapath=JAVAPATH] [--list=TESTLIST] [--neglist=TESTLIST] [--testpath=TESTPATH] [--shellpath=SHELLPATH] [--lxrurl=LXRURL] {-e ENGINETYPE | --engine=ENGINETYPE}`

DESCRIPTION
  jsDriver.pl is normally used to run a series of tests against one of the JavaScript shells. These tests are expected to be laid out in a directory structure exactly three levels deep. The first level is considered the root of the tests, subdirectories under the root represent Test Suites and generally mark broad categories such as ECMA Level 1 or Live Connect 3. Under the Test Suites are the Test Categories, which divide the Test Suite into smaller categories, such as Execution Contexts or Lexical Rules. Testcases are located under the Test Categories as normal JavaScript (*.js) files.

  If a file named shell.js exists in either the Test Suite or the Test Category directory, it is loaded into the shell before the testcase. If shell.js exists in both directories, the version in the Test Suite directory is loaded first, giving the version associated with the Test Category the ability to override functions previously declared. You can use this to create functions and variables common to an entire suite or category.

  Testcases can report failures back to jsDriver.pl in one of two ways. The most common is to write a line of text containing the word `FAILED!` to STDOUT or STDERR. When the engine encounters a matching line, the test is marked as failed, and any line containing `FAILED!` is displayed in the failure report. The second way a test case can report failure is to return an unexpected exit code. By default, jsDriver.pl expects all test cases to return exit code 0, although a test can output a line containing `EXPECT EXIT n` where n is the exit code the driver should expect to see. Testcases can return a nonzero exit code by calling the shell function `quit(n)` where `n` is the code to exit with. The various JavaScript shells report non-zero exit codes under the following conditions:

  Reason | Exit Code
  --- | ---
  Engine initialization failure. | 1
  Invalid argument on command line. | 2
  Runtime error (uncaught exception) encountered. | 3
  File argument specified on command line not found. | 4
  Reserved for future use. | 5-9

OPTIONS
  -b URL, --bugurl=URL
    Bugzilla URL. When a testcase writes a line in the format `BUGNUMBER n` to STDOUT or STDERR, jsDriver.pl interprets `n` as a bugnumber in the BugZilla bug tracking system. In the event that a testcase which has specified a bugnumber fails, a hyperlink to the BugZilla database will be included in the output by prefixing the bugnumber with the URL specified here. By default, URL is assumed to be "http://bugzilla.mozilla.org/show_bug.cgi?id=".
  -c PATH, --classpath=PATH
    Classpath to pass the the Java Virtual Machine. When running tests against the Rhino engine, PATH will be passed in as the value to an argument named "-classpath". If your particular JVM does not support this option, it is recommended you specify your class path via an environment setting. Refer to your JVM documentation for more details about CLASSPATH.
  -e TYPE ..., --engine=TYPE ...
    Required. Type of engine(s) to run the tests against. TYPE can be one or more of the following values:

    TYPE | Engine
    --- | ---
    lcopt | LiveConnect, optimized
    lcdebug | LiveConnect, debug
    rhino | Rhino compiled mode
    rhinoi | Rhino interpreted mode
    rhinoms | Rhino compiled mode for the Microsoft VM (jview)
    rhinomsi | Rhino interpreted mode for the Microsoft VM (jview)
    smopt | Spider-Monkey, optimized
    smdebug | Spider-Monkey, debug
    xpcshell | XPConnect shell

  -f FILE, --file=FILE
    Generate html output to the HTML file named by FILE. By default, a filename will be generated using a combination of the engine type and a date/time stamp, in the format: `results-<engine-type>-<date-stamp>.html`
  -h, --help
    Prints usage information.
  -j PATH, --javapath=PATH
    Set the location of the Java Virtual Machine to use when running tests against the Rhino engine. This can be used to test against multiple JVMs on the same system.
  -k, --confail
    Log failures to the console. This will show any failures, as they occur, on STDERR in addition to creating the HTML results file. This can be useful for times when it may be counter-productive to load an HTML version of the results each time a test is re-run.
  -l FILE ..., --list=FILE ...
    Specify a list of tests to execute. FILE can be a plain text file containing a list of testcases to execute, a subdirectory in which to grovel for tests, or a single testcase to execute. Any number of FILE specifiers may follow this option. The driver uses the fact that a valid testcase should be a file ending in .js to make the distinction between a file containing a list of tests and an actual testcase.
  -L FILE ..., --neglist=FILE ...
    Specify a list of tests to skip. FILE has the same meaning as in the -l option. This option is evaluated after all -l and --list options, allowing a user to subtract a single testcase, a directory of testcases, or a collection of unrelated testcases from the execution list.
  -p PATH, --testpath=PATH
    Directory holding the "Test Suite" subdirectories. By default this is ./
  -s PATH, --shellpath=PATH
    Directory holding the JavaScript shell. This can be used to override the automatic shell location jsDriver.pl performs based on you OS and engine type. For Non Rhino engines, this includes the name of the executable as well as the path. In Rhino, this path will be appended to your CLASSPATH. For the SpiderMonkey shells, this value defaults to ../src/<Platform-and-buildtype-specific-directory>/[js|jsshell], for the LiveConnect shells, ../src/liveconnect/src/<Platform-and-buildtype-specific-directory>/lschell and for the xpcshell the default is the value of your `MOZILLA_FIVE_HOME` environment variable. There is no default (as it is usually not needed) for the Rhino shell.
  -t, --trace
    Trace execution of jsDriver.pl. This option is primarily used for debugging of the script itself, but if you are interested in seeing the actual command being run, or generally like gobs of useless information, you may find it entertaining.
  -u URL, --lxrurl=URL
    Failures listed in the HTML results will be hyperlinked to the lxr source available online by prefixing the test path and name with this URL. By default, URL is http://lxr.mozilla.org/mozilla/source/js/tests/
SEE ALSO
  jsDriver.pl, mklistpage.pl, http://www.mozilla.org/js/, http://www.mozilla.org/js/tests/library.html
REQUIREMENTS
  jsDriver.pl requires the Getopt::Mixed perl package, available from cpan.org.
EXAMPLES
  `perl jsDriver.pl -e smdebug -L lc*`
  Executes all tests EXCEPT the liveconnect tests against the SpiderMonkey debug shell, writing the results to the default result file. (NOTE: Unix shells take care of wildcard expansion, turning `lc*` into `lc2 lc3`. Under a DOS shell, you must explicitly list the directories.)

  `perl jsDriver.pl -e rhino -L rhino-n.tests`
  Executes all tests EXCEPT those listed in the `rhino-n.tests` file.

  `perl -I/home/rginda/perl/lib/ jsDriver.pl -e lcopt -l lc2 lc3 -f lcresults.html -k`
  Executes ONLY the tests under the `lc2` and `lc3` directories against the LiveConnect shell. Results will be written to the file `lcresults.html` AND the console. The `-I` option tells perl to look for modules in the `/home/rginda/perl/lib` directory (in addition to the usual places), useful if you do not have root access to install new modules on the system.

Author: Robert Ginda
Currently maintained by Phil Schwartau