js/tests/README-jsDriver.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>jsDriver.pl</title>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 align="right">jsDriver.pl</h1>
   9
  10     <dl>
  11       <dt><b>NAME</b></dt>
  12       <dd>
  13         <b>jsDriver.pl</b> - execute JavaScript programs in various shells in
  14         batch or single mode, reporting on failures encountered.
  15         <br>
  16         <br>
  17
  18       <dt><b>SYNOPSIS</b></dt>
  19       <dd>
  20         <table>
  21           <tr>
  22             <td align="right" valign="top">
  23               <code>
  24                 <b>jsDriver.pl</b>
  25               </code>
  26             </td>
  27             <td>
  28               <code>
  29                 [-hkt] [-b BUGURL] [-c CLASSPATH] [-f OUTFILE]
  30                 [-j JAVAPATH] [-l TESTLIST ...] [-L NEGLIST ...] [-p TESTPATH]
  31                 [-s SHELLPATH] [-u LXRURL] [--help] [--confail] [--trace]
  32                 [--classpath=CLASSPATH] [--file=OUTFILE] [--javapath=JAVAPATH]
  33                 [--list=TESTLIST] [--neglist=TESTLIST] [--testpath=TESTPATH]
  34                 [--shellpath=SHELLPATH] [--lxrurl=LXRURL] {-e ENGINETYPE |
  35                 --engine=ENGINETYPE}
  36               </code>
  37             </td>
  38           </tr>
  39         </table>
  40         <br>
  41         <br>
  42
  43       <dt><b>DESCRIPTION</b></dt>
  44       <dd>
  45         <b>jsDriver.pl</b> is normally used to run a series of tests against
  46         one of the JavaScript shells.  These tests are expected to be laid out
  47         in a directory structure exactly three levels deep.  The first level
  48         is considered the <b>root</b> of the tests, subdirectories under the
  49         <b>root</b> represent <b>Test Suites</b> and generally mark broad
  50         categories such as <i>ECMA Level 1</i> or <i>Live Connect 3</i>.  Under the
  51         <b>Test Suites</b> are the <b>Test Categories</b>, which divide the
  52         <b>Test Suite</b> into smaller categories, such as <i>Execution Contexts</i>
  53         or <i>Lexical Rules</i>.  Testcases are located under the
  54         <B>Test Categories</b> as normal JavaScript (*.js) files.
  55         <p>
  56           If a file named <b>shell.js</b> exists in either the
  57           <b>Test Suite</b> or the <b>Test Category</b> directory, it is
  58           loaded into the shell before the testcase.  If <b>shell.js</b>
  59           exists in both directories, the version in the <b>Test Suite</b>
  60           directory is loaded <i>first</i>, giving the version associated with
  61           the <b>Test Category</b> the ability to override functions previously
  62           declared.  You can use this to
  63           create functions and variables common to an entire suite or category.
  64         <p>
  65           Testcases can report failures back to <b>jsDriver.pl</b> in one of
  66           two ways.  The most common is to write a line of text containing
  67           the word <code>FAILED!</code> to <b>STDOUT</b> or <b>STDERR</b>.
  68           When the engine encounters a matching line, the test is marked as
  69           failed, and any line containing <code>FAILED!</code> is displayed in
  70           the failure report.  The second way a test case can report failure is
  71           to return an unexpected exit code.  By default, <b>jsDriver.pl</b>
  72           expects all test cases to return exit code 0, although a test
  73           can output a line containing <code>EXPECT EXIT <i>n</i></code> where
  74           <i>n</i> is the exit code the driver should expect to see.  Testcases
  75           can return a nonzero exit code by calling the shell function
  76           <code>quit(<i>n</i>)</code> where <code><i>n</i></code> is the
  77           code to exit with.  The various JavaScript shells report
  78           non-zero exit codes under the following conditions:
  79
  80           <center>
  81             <table border="1">
  82               <tr>
  83                 <th>Reason</th>
  84                 <th>Exit Code</th>
  85               </tr>
  86               <tr>
  87                 <td>
  88                   Engine initialization failure.
  89                 </td>
  90                 <td>
  91                   1
  92                 </td>
  93               </tr>
  94               <tr>
  95                 <td>
  96                   Invalid argument on command line.
  97                 </td>
  98                 <td>
  99                   2
 100                 </td>
 101               </tr>
 102               <tr>
 103                 <td>
 104                   Runtime error (uncaught exception) encountered.
 105                 </td>
 106                 <td>
 107                   3
 108                 </td>
 109               </tr>
 110               <tr>
 111                 <td>
 112                   File argument specified on command line not found.
 113                 </td>
 114                 <td>
 115                   4
 116                 </td>
 117               </tr>
 118               <tr>
 119                 <td>
 120                   Reserved for future use.
 121                 </td>
 122                 <td>
 123                   5-9
 124                 </td>
 125               </tr>
 126             </table>
 127           </center>
 128           <br>
 129           <br>
 130
 131       <dt><b>OPTIONS</b></dt>
 132       <dd>
 133         <dl>
 134           <dt><b>-b URL, --bugurl=URL</b></dt>
 135           <dd>
 136             Bugzilla URL.  When a testcase writes a line in the format
 137             <code>BUGNUMBER <i>n</i></code> to <b>STDOUT</b> or <b>STDERR</b>,
 138             <b>jsDriver.pl</b> interprets <code><i>n</i></code> as a bugnumber
 139             in the <a href="http://bugzilla.mozilla.org">BugZilla</a> bug
 140             tracking system.  In the event that a testcase which has specified
 141             a bugnumber fails, a hyperlink to the BugZilla database
 142             will be included in the output by prefixing the bugnumber with the
 143             URL specified here.  By default, URL is assumed to be
 144             &quot;http://bugzilla.mozilla.org/show_bug.cgi?id=&quot;.
 145             <br>
 146             <br>
 147             <a name="classpath"></a>
 148           <dt><b>-c PATH, --classpath=PATH</b></dt>
 149           <dd>
 150             Classpath to pass the the Java Virtual Machine.  When running tests
 151             against the <b>Rhino</b> engine, PATH will be passed in as the value
 152             to an argument named &quot;-classpath&quot;.  If your particular JVM
 153             does not support this option, it is recommended you specify your
 154             class path via an environment setting.  Refer to your JVM
 155             documentation for more details about CLASSPATH.
 156             <br>
 157             <br>
 158           <dt><b>-e TYPE ..., --engine=TYPE ...</b></dt>
 159           <dd>
 160             Required.  Type of engine(s) to run the tests against.  TYPE can be
 161             one or more of the following values:
 162             <center>
 163               <table border="1">
 164                 <tr>
 165                   <th>TYPE</th>
 166                   <th>Engine</th>
 167                 </tr>
 168                 <tr>
 169                   <td>lcopt</td>
 170                   <td>LiveConnect, optimized</td>
 171                 </tr>
 172                 <tr>
 173                   <td>lcdebug</td>
 174                   <td>LiveConnect, debug</td>
 175                 </tr>
 176                 <tr>
 177                   <td>rhino</td>
 178                   <td>Rhino compiled mode</td>
 179                 </tr>
 180                 <tr>
 181                   <td>rhinoi</td>
 182                   <td>Rhino interpreted mode</td>
 183                 </tr>
 184                 <tr>
 185                   <td>rhinoms</td>
 186                   <td>Rhino compiled mode for the Microsoft VM (jview)</td>
 187                 </tr>
 188                 <tr>
 189                   <td>rhinomsi</td>
 190                   <td>Rhino interpreted mode for the Microsoft VM (jview)</td>
 191                 </tr>
 192                 <tr>
 193                   <td>smopt</td>
 194                   <td>Spider-Monkey, optimized</td>
 195                 </tr>
 196                 <tr>
 197                   <td>smdebug</td>
 198                   <td>Spider-Monkey, debug</td>
 199                 </tr>
 200                 <tr>
 201                   <td>xpcshell</td>
 202                   <td>XPConnect shell</td>
 203                 </tr>
 204               </table>
 205             </center>
 206             <br>
 207             <br>
 208           <dt><b>-f FILE, --file=FILE</b></dt>
 209           <dd>
 210             Generate html output to the HTML file named by FILE.  By default,
 211             a filename will be generated using a combination of the engine type
 212             and a date/time stamp, in the format:
 213             <code>results-<i>&lt;engine-type&gt;</i>-<i>&lt;date-stamp&gt;</i>.html</code>
 214             <br>
 215             <br>
 216           <dt><b>-h, --help</b></dt>
 217           <dd>
 218             Prints usage information.
 219             <br>
 220             <br>
 221           <dt><b>-j PATH, --javapath=PATH</b></dt>
 222           <dd>
 223             Set the location of the Java Virtual Machine to use when running
 224             tests against the <b>Rhino</b> engine.  This can be used to test
 225             against multiple JVMs on the same system.
 226             <br>
 227             <br>
 228           <dt><b>-k, --confail</b></dt>
 229           <dd>
 230             Log failures to the console.  This will show any failures, as they
 231             occur, on <b>STDERR</b> in addition to creating the HTML results
 232             file.  This can be useful for times when it may be
 233             counter-productive to load an HTML version of the results each time
 234             a test is re-run.
 235             <br>
 236             <br>
 237           <dt><b>-l FILE ..., --list=FILE ...</b></dt>
 238           <dd>
 239             Specify a list of tests to execute.  FILE can be a plain text file
 240             containing a list of testcases to execute, a subdirectory
 241             in which to
 242             <a href="http://www.instantweb.com/~foldoc/foldoc.cgi?query=grovel">grovel</a>
 243             for tests, or a single testcase to execute.  Any number of FILE
 244             specifiers may follow this option.  The driver uses the fact that a
 245             valid testcase should be a file ending in .js to make the distinction
 246             between a file containing a list of tests and an actual testcase.
 247             <br>
 248             <br>
 249           <dt><b>-L FILE ..., --neglist=FILE ...</b></dt>
 250           <dd>
 251             Specify a list of tests to skip.  FILE has the same meaning as in
 252             the <b>-l</b> option.  This option is evaluated after
 253             <b>all</b> <b>-l</b> and <b>--list</b> options, allowing a user
 254             to subtract a single testcase, a directory of testcases, or a
 255             collection of unrelated testcases from the execution list.
 256             <br>
 257             <br>
 258           <dt><b>-p PATH, --testpath=PATH</b></dt>
 259           <dd>
 260             Directory holding the &quot;Test Suite&quot; subdirectories.  By
 261             default this is ./
 262             <br>
 263             <br>
 264           <dt><b>-s PATH, --shellpath=PATH</b></dt>
 265           <dd>
 266             Directory holding the JavaScript shell.  This can be used to override
 267             the automatic shell location <b>jsDriver.pl</b> performs based on
 268             you OS and engine type.  For Non <b>Rhino</b> engines, this
 269             includes the name of the executable as well as the path.  In
 270             <b>Rhino</b>, this path will be appended to your
 271             <a href="#classpath">CLASSPATH</a>.  For the
 272             <b>SpiderMonkey</b> shells, this value defaults to
 273             ../src/&lt;Platform-and-buildtype-specific-directory&gt;/[js|jsshell],
 274             for the
 275             <b>LiveConnect</b> shells,
 276             ../src/liveconnect/src/&lt;Platform-and-buildtype-specific-directory&gt;/lschell
 277             and for the <b>xpcshell</b> the default is the value of your
 278             <code>MOZILLA_FIVE_HOME</code> environment variable.  There is no
 279             default (as it is usually not needed) for the <b>Rhino</b> shell.
 280             <br>
 281             <br>
 282           <dt><b>-t, --trace</b></dt>
 283           <dd>
 284             Trace execution of <b>jsDriver.pl</b>.  This option is primarily
 285             used for debugging of the script itself, but if you are interested in
 286             seeing the actual command being run, or generally like gobs of
 287             useless information, you may find it entertaining.
 288             <br>
 289             <br>
 290           <dt><b>-u URL, --lxrurl=URL</b></dt>
 291           <dd>
 292             Failures listed in the HTML results will be hyperlinked to the
 293             lxr source available online by prefixing the test path and
 294             name with this URL.  By default, URL is
 295             http://lxr.mozilla.org/mozilla/source/js/tests/
 296             <br>
 297             <br>
 298
 299         </dl>
 300       <dt><b>SEE ALSO</b></dt>
 301       <dd>
 302         <a href="http://lxr.mozilla.org/mozilla/source/js/tests/jsDriver.pl">jsDriver.pl</a>,
 303         <a href="http://lxr.mozilla.org/mozilla/source/js/tests/mklistpage.pl">mklistpage.pl</a>,
 304         <a href="http://www.mozilla.org/js/">http://www.mozilla.org/js/</a>,
 305         <a href="http://www.mozilla.org/js/tests/library.html">http://www.mozilla.org/js/tests/library.html</a>
 306         <br>
 307         <br>
 308
 309       <dt><b>REQUIREMENTS</b></dt>
 310       <dd>
 311         <b>jsDriver.pl</b> requires the
 312         <a href="http://search.cpan.org/search?module=Getopt::Mixed">Getopt::Mixed</a>
 313         perl package, available from <a href="http://www.cpan.org">cpan.org</a>.
 314         <br>
 315         <br>
 316       <dt><b>EXAMPLES</b></dt>
 317       <dd>
 318           <code>perl jsDriver.pl -e smdebug -L lc*</code><br>
 319           Executes all tests EXCEPT the liveconnect tests against the
 320           SpiderMonkey debug shell, writing the results
 321           to the default result file.  (NOTE: Unix shells take care of wildcard
 322           expansion, turning <code>lc*</code> into <code>lc2 lc3</code>.  Under
 323           a DOS shell, you must explicitly list the directories.)
 324         <p>
 325           <code>perl jsDriver.pl -e rhino -L rhino-n.tests</code><br>
 326           Executes all tests EXCEPT those listed in the
 327           <code>rhino-n.tests</code> file.
 328         <p>
 329           <code>perl -I/home/rginda/perl/lib/ jsDriver.pl -e lcopt -l lc2
 330             lc3 -f lcresults.html -k</code><br>
 331           Executes ONLY the tests under the <code>lc2</code> and <code>lc3</code>
 332           directories against the LiveConnect shell.  Results will be written to
 333           the file <code>lcresults.html</code> <b>AND</b> the console.  The
 334           <code>-I</code> option tells perl to look for modules in the
 335           <code>/home/rginda/perl/lib</code> directory (in addition to the
 336           usual places), useful if you do not have root access to install new
 337           modules on the system.
 338     </dl>
 339     <hr>
 340     Author: Robert Ginda<br>
 341     Currently maintained by <i><a href="mailto:pschwartau@meer.net">Phil Schwartau</a> </i><br>
 342 <!-- Created: Thu Dec  2 19:08:05 PST 1999 -->
 343   </body>
 344 </html>