mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-10 03:45:46 +00:00
307 lines
12 KiB
HTML
307 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>jsDriver.pl</title>
|
|
<style>
|
|
dt {
|
|
font-family: Courier;
|
|
}
|
|
</style>
|
|
</head>
|
|
|
|
<body bgcolor="white">
|
|
<h1 align="right">jsDriver.pl</h1>
|
|
|
|
<dl>
|
|
<dt><b>NAME</b></dt>
|
|
<dd>
|
|
<b>jsDriver.pl</b> - execute JavaScript programs in various shells in
|
|
batch or single mode, reporting on failures encountered.
|
|
<br>
|
|
<br>
|
|
|
|
<dt><b>SYNOPSIS</b></dt>
|
|
<dd>
|
|
<code>
|
|
<b>jsDriver.pl</b> [-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}
|
|
</code>
|
|
<br>
|
|
<br>
|
|
|
|
<dt><b>DESCRIPTION</b></dt>
|
|
<dd>
|
|
<b>jsDriver.pl</b> 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 two levels deep. The first level
|
|
represents a "Test Suite" and generally marks a broad
|
|
category such as <i>ECMA Level 1</i> or <i>Live Connect 3</i>. The next
|
|
level represents a "Suite Category" and divides tests
|
|
inside a suite into smaller categories, such as <i>Execution Contexts</i>
|
|
or <i>Lexical Rules</i>. Testcases reside under the "Suite
|
|
Categories" as normal JavaScript (*.js) files. If a file named
|
|
shell.js exists in either the suite path (the parent directory of the
|
|
"Test Suites") or the indiviual "Suite Category"
|
|
directory, it is loaded into the shell before the testcase. You can
|
|
use this to declare functions and variables common to an entire suite
|
|
or category.
|
|
<p>
|
|
Testcases can report failures back to <b>jsDriver.pl</b> in one of
|
|
two ways. The most common is to write a line of text containing
|
|
the word <code>FAILED!</code> to <b>STDOUT</b> or <b>STDERR</b>.
|
|
When the engine encounters a matching line, the test is marked as
|
|
failed, and any line containing <code>FAILED!</code> is displayed in
|
|
the failure report. The second way a test case can report failure is
|
|
to return an unexpected exit code. By default, <b>jsDriver.pl</b>
|
|
expects all test cases to return exit code 0, although a test
|
|
can output a line containing <code>EXPECT EXIT <i>n</i></code> where
|
|
<i>n</i> is the exit code the driver should expect to see. Testcases
|
|
can return a nonzero exit code by calling the shell function
|
|
<code>exit(<i>n</i>)</code> where <code><i>n</i></code> is the
|
|
code to exit with. Also, the various JavaScript shells report
|
|
non-zero exit codes under the following conditions:
|
|
|
|
<center>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Reason</th>
|
|
<th>Exit Code</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Engine initialization failure.
|
|
</td>
|
|
<td>
|
|
1
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Invalid argument on command line.
|
|
</td>
|
|
<td>
|
|
2
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Runtime error (uncaught exception) encountered.
|
|
</td>
|
|
<td>
|
|
3
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
File argument specified on command line not found.
|
|
</td>
|
|
<td>
|
|
4
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Reserverd for future use.
|
|
</td>
|
|
<td>
|
|
5-9
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<br>
|
|
<br>
|
|
|
|
<dt><b>OPTIONS</b></dt>
|
|
<dd>
|
|
<dl>
|
|
<dt><b>-b URL, --bugurl=URL</b></dt>
|
|
<dd>
|
|
Bugzilla URL. When a testcase writes a line in the format
|
|
<code>BUGNUMBER <i>n</i></code> to <b>STDOUT</b> or <b>STDERR</b>,
|
|
<b>jsDriver.pl</b> interprets <code><i>n</i></code> as a bugnumber
|
|
in the <a href="http://bugzilla.mozilla.org">BugZilla</a> bug
|
|
tracking system. In the event that a testcase which has specified
|
|
a bugnumber in the manner 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=".
|
|
<br>
|
|
<br>
|
|
<a name="classpath"></a>
|
|
<dt><b>-c PATH, --classpath=PATH</b></dt>
|
|
<dd>
|
|
Classpath to pass the the Java Virtual Machine. When running tests
|
|
against the <b>Rhino</b> 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.
|
|
<br>
|
|
<br>
|
|
<dt><b>-e TYPE, --engine=TYPE</b></dt>
|
|
<dd>
|
|
Required. Type of engine to run the tests against. TYPE can be one
|
|
of the following values:
|
|
<center>
|
|
<table border="1">
|
|
<tr>
|
|
<th>TYPE</th>
|
|
<th>Engine</th>
|
|
</tr>
|
|
<tr>
|
|
<td>lcopt</td>
|
|
<td>LiveConnect, optimized</td>
|
|
</tr>
|
|
<tr>
|
|
<td>lcdebug</td>
|
|
<td>LiveConnect, debug</td>
|
|
</tr>
|
|
<tr>
|
|
<td>rhino</td>
|
|
<td>Rhino</td>
|
|
</tr>
|
|
<tr>
|
|
<td>smopt</td>
|
|
<td>Spider-Monkey, optimized</td>
|
|
</tr>
|
|
<tr>
|
|
<td>smdebug</td>
|
|
<td>Spider-Monkey, debug</td>
|
|
</tr>
|
|
<tr>
|
|
<td>xpcshell</td>
|
|
<td>XPConnect shell</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<br>
|
|
<br>
|
|
<dt><b>-f FILE, --file=FILE</b></dt>
|
|
<dd>
|
|
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
|
|
<br>
|
|
<br>
|
|
<dt><b>-h, --help</b></dt>
|
|
<dd>
|
|
Prints usage information.
|
|
<br>
|
|
<br>
|
|
<dt><b>-j PATH, --javapath=PATH</b></dt>
|
|
<dd>
|
|
Set the location of the Java Virtual Machine to use when running
|
|
tests against the <b>Rhino</b> engine. This can be used to test
|
|
against multiple JVMs on the same system.
|
|
<br>
|
|
<br>
|
|
<dt><b>-k, --confail</b></dt>
|
|
<dd>
|
|
Log failures to the console. This will show any failures, as they
|
|
occur, on <b>STDERR</b> 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.
|
|
<br>
|
|
<br>
|
|
<dt><b>-l FILE ..., --list=FILE ...</b></dt>
|
|
<dd>
|
|
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
|
|
<a href="http://www.instantweb.com/~foldoc/foldoc.cgi?query=grovel">
|
|
grovel (2)</a>
|
|
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 containg a list of tests and an actual testcase.
|
|
<br>
|
|
<br>
|
|
<dt><b>-L FILE ..., --neglist=FILE ...</b></dt>
|
|
<dd>
|
|
Specify a list of tests to skip. FILE has the same meaning as in
|
|
the <b>-l</b> option. This option is evaluated after
|
|
<b>all</b> <b>-l</b> and <b>--list</b> options, allowing a user
|
|
to subtract a single testcase, a directory of testcases, or a
|
|
collection of unrelated testcases from the exection list.
|
|
<br>
|
|
<br>
|
|
<dt><b>-p PATH, --testpath=PATH</b></dt>
|
|
<dd>
|
|
Directory holding the "Test Suite" subdirectories. By
|
|
default this is ./
|
|
<br>
|
|
<br>
|
|
<dt><b>-s PATH, --shellpath=PATH</b></dt>
|
|
<dd>
|
|
Directory holding the JavaScript shell. This can be used to override
|
|
the automatic shell location <b>jsDriver.pl</b> performs based on
|
|
you OS and engine type. For Non <b>Rhino</b> engines, this
|
|
includes the name of the executable as well as the path. In
|
|
<b>Rhino</b>, this path will be appended to your
|
|
<a href="#classpath">CLASSPATH</a>. For the
|
|
<b>SpiderMonkey</b> shells, this value defaults to
|
|
../src/<Platform-and-buildtype-specific-directory>/[js|jsshell],
|
|
for the
|
|
<b>LiveConnect</b> shells,
|
|
../src/liveconnect/src/<Platform-and-buildtype-specific-directory>/lschell
|
|
and for the <b>xpcshell</b> the default is the value of your
|
|
<code>MOZILLA_FIVE_HOME</code> environment variable. There is no
|
|
default (as it is usually not needed) for the <b>Rhino</b> shell.
|
|
<br>
|
|
<br>
|
|
<dt><b>-t, --trace</b></dt>
|
|
<dd>
|
|
Trace execution of <b>jsDriver.pl</b>. 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.
|
|
<br>
|
|
<br>
|
|
<dt><b>-u URL, --lxrurl=URL</b></dt>
|
|
<dd>
|
|
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/
|
|
<br>
|
|
<br>
|
|
|
|
</dl>
|
|
|
|
<dt><b>BUGS</b></dt>
|
|
<dd>
|
|
This script needs to be modified to work with MacPerl<br>
|
|
At the time of this writing (12/02/99), the LiveConnect shell does not
|
|
return proper exit codes. This is expected to be changed soon.<br>
|
|
|
|
<dt><b>SEE ALSO</b></dt>
|
|
<dd>
|
|
mklistpage.pl,
|
|
<a href="http://www.mozilla.org/js/">http://www.mozilla.org/js/</a>
|
|
<br>
|
|
<br>
|
|
|
|
<dt><b>BUGS</b></dt>
|
|
<dd>
|
|
This script needs to be modified to work with MacPerl<br>
|
|
At the time of this writing (12/02/99), the LiveConnect shell does not
|
|
return proper exit codes. This is expected to be changed soon.<br>
|
|
|
|
</dl>
|
|
<hr>
|
|
<address><a href="mailto:rginda@netscape.com">Robert Ginda</a></address>
|
|
<!-- Created: Thu Dec 2 19:08:05 PST 1999 -->
|
|
<!-- hhmts start -->
|
|
Last modified: Tue Dec 7 11:46:36 PST 1999
|
|
<!-- hhmts end -->
|
|
</body>
|
|
</html>
|