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>
345