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 "http://bugzilla.mozilla.org/show_bug.cgi?id=";. 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 "-classpath". 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><engine-type></i>-<i><date-stamp></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 "Test Suite" 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/<Platform-and-buildtype-specific-directory>/[js|jsshell], 274 for the 275 <b>LiveConnect</b> shells, 276 ../src/liveconnect/src/<Platform-and-buildtype-specific-directory>/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 (a] netscape.com">Phil Schwartau</a> </i><br> 342 <!-- Created: Thu Dec 2 19:08:05 PST 1999 --> 343 </body> 344 </html> 345
