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