darin | cd553de | 2003-10-13 02:05:37 +0000 | [diff] [blame] | 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@netscape.com">Phil Schwartau</a> </i><br> |
| 342 | <!-- Created: Thu Dec 2 19:08:05 PST 1999 --> |
| 343 | </body> |
| 344 | </html> |