/[jscoverage]/trunk/doc/manual.html
ViewVC logotype

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 502 - (hide annotations)
Mon Dec 28 04:21:14 2009 UTC (12 years, 4 months ago) by siliconforks
File MIME type: text/html
File size: 27099 byte(s)
Add documentation for the --mozilla option.

1 siliconforks 197 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2 siliconforks 2 <html>
3     <head>
4     <title>JSCoverage user manual</title>
5 siliconforks 198 <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
6     <link rel="stylesheet" type="text/css" href="doc.css">
7 siliconforks 328 <script type="text/javascript" src="sh_main.min.js"></script>
8     <script type="text/javascript" src="sh_html.min.js"></script>
9     <script type="text/javascript" src="sh_javascript.min.js"></script>
10 siliconforks 2 </head>
11 siliconforks 198 <body onload="sh_highlightDocument();">
12 siliconforks 2
13     <h1>JSCoverage user manual</h1>
14    
15     <p>
16 siliconforks 328 JSCoverage is a tool that measures code coverage for JavaScript programs.
17 siliconforks 2 </p>
18    
19     <p>
20 siliconforks 115 JSCoverage works by adding instrumentation to JavaScript code before it is
21     executed in a web browser. JSCoverage provides several alternative ways of doing
22     this:
23 siliconforks 2 </p>
24    
25 siliconforks 115 <ul>
26     <li>The simplest method is to use the <code>jscoverage</code> program to generate
27     instrumented JavaScript files.
28     </li>
29     <li>Alternatively, you can use the <code>jscoverage-server</code> program, a simple web server that instruments
30     JavaScript code as it is served.
31     </li>
32     <li>Finally, <code>jscoverage-server</code> can be run with the <code>--proxy</code> option to
33     act as a proxy server which instruments any JavaScript code proxied through it.
34     </li>
35     </ul>
36 siliconforks 2
37 siliconforks 115 <p>
38     The <code>jscoverage-server</code> program (with or without the <code>--proxy</code>
39     option) has the advantage of being able to store coverage reports to the filesystem.
40     </p>
41    
42 siliconforks 225 <h2>Compiling JSCoverage</h2>
43 siliconforks 2
44     <p>
45 siliconforks 393 You can compile JSCoverage on GNU/Linux or Microsoft Windows, using the GCC C++ compiler (<code>g++</code>). On
46 siliconforks 2 Windows you will require <a href="http://cygwin.com/">Cygwin</a> or <a
47     href="http://mingw.org/">MinGW/MSYS</a>.
48     </p>
49    
50     <p>
51     You can extract and compile the code with the following commands:
52     </p>
53    
54     <pre>
55 siliconforks 115 tar jxvf jscoverage-0.4.tar.bz2
56     cd jscoverage-0.4/
57 siliconforks 2 ./configure
58     make
59     </pre>
60    
61     <p>
62 siliconforks 115 This will create the <code>jscoverage</code> and <code>jscoverage-server</code>
63     executables (<code>jscoverage.exe</code> and <code>jscoverage-server.exe</code>
64     on Windows). You can install the executables in <code>/usr/local</code> with the
65     command:
66 siliconforks 2 </p>
67    
68     <pre>
69     make install
70     </pre>
71    
72     <p>
73 siliconforks 115 Alternatively, you may simply copy the <code>jscoverage</code> executable and/or
74     the <code>jscoverage-server</code> executable to a suitable location in your
75     <code>PATH</code>.
76 siliconforks 2 </p>
77    
78 siliconforks 115 <h2>Using the <code>jscoverage</code> program</h2>
79 siliconforks 2
80     <p>
81 siliconforks 328 To demonstrate how the <code>jscoverage</code> program works, we will use the
82     trivial example JavaScript code located in the
83     <code>doc/example/</code> directory of the JSCoverage distribution. You can run
84     this example by viewing the file <code>doc/example/index.html</code> in your web browser.
85 siliconforks 2 </p>
86    
87 siliconforks 328 <p>
88     Generating code coverage statistics for this example using the
89     <code>jscoverage</code> program involves the following steps:
90     </p>
91    
92 siliconforks 2 <h3>1. Instrumenting code</h3>
93    
94     <p>
95 siliconforks 115 The first step is to add instrumentation to your JavaScript code. You do this by
96     executing <code>jscoverage</code> with two arguments:
97 siliconforks 2 </p>
98    
99     <pre>
100     jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
101     </pre>
102    
103     <p>
104     <var>SOURCE-DIRECTORY</var> is the directory containing the JavaScript code to be instrumented,
105     and <var>DESTINATION-DIRECTORY</var> is the name of the
106     directory to which <code>jscoverage</code> should output the instrumented code.
107     The <code>jscoverage</code> program will create <var>DESTINATION-DIRECTORY</var> if necessary and (recursively) copy
108     <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>, instrumenting
109     any files ending with a <code>.js</code> extension.
110     </p>
111    
112     <p>
113 siliconforks 328 The directory structure under <var>SOURCE-DIRECTORY</var> is preserved, so that if you have a file
114 siliconforks 2 <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
115     <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
116     <code>jscoverage</code> will create a copy of the HTML file at
117     <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code> and an instrumented
118     version of the script at
119     <code><var>DESTINATION-DIRECTORY</var>/dir/script.js</code>.
120 siliconforks 414 In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
121     which is used to execute the instrumented code.
122 siliconforks 2 </p>
123    
124     <table>
125     <tr>
126     <td><pre>
127     <var>SOURCE-DIRECTORY</var>/
128     dir/
129     index.html
130     script.js
131    
132     </pre></td>
133     <td class="arrow">&rarr;</td>
134     <td><pre>
135     <var>DESTINATION-DIRECTORY</var>/
136     dir/
137     index.html
138     script.js [instrumented]
139     jscoverage.html
140     </pre></td>
141     </tr>
142     </table>
143    
144     <p>
145 siliconforks 414 For the example code in the <code>doc/example/</code> directory, you can execute the
146     following command line from the top-level directory of the JSCoverage distribution:
147 siliconforks 2 </p>
148    
149 siliconforks 328 <pre>
150     jscoverage doc/example doc/instrumented
151     </pre>
152    
153     <p>
154     This will create the directory <code>doc/instrumented/</code> and place an
155     instrumented copy of the code from <code>doc/example/</code> in
156     <code>doc/instrumented/</code>.
157     </p>
158    
159     <table>
160     <tr>
161     <td><pre>
162     doc/example/
163     index.html
164     script.js
165    
166     </pre></td>
167     <td class="arrow">&rarr;</td>
168     <td><pre>
169     doc/instrumented/
170     index.html
171     script.js [instrumented]
172     jscoverage.html
173     </pre></td>
174     </tr>
175     </table>
176    
177 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
178 siliconforks 2
179     <p>
180 siliconforks 328 Open the generated <code>jscoverage.html</code> file
181     (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
182 siliconforks 2 The page contains a tabbed user interface:
183     </p>
184    
185     <ul>
186     <li>The "Browser" tab is used to display pages with instrumented scripts.
187     <li>The "Summary" tab is used to display code coverage data.
188     <li>The "Source" tab is used to display JavaScript code, showing the number of times
189     each line of code was executed.
190     <li>The "About" tab displays information about the current version of JSCoverage.
191     </ul>
192    
193 siliconforks 197 <p><img src="screenshot.png" alt="Screenshot"></p>
194 siliconforks 2
195     <p>
196     The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
197 siliconforks 497 You can load a URL into this frame by entering it into the "URL" input field and clicking the "Open in frame" button.
198 siliconforks 64 You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
199     or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
200     from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
201     server, will give unexpected results.
202 siliconforks 2 </p>
203    
204     <p>
205 siliconforks 328 For example, you can load the file <code>doc/instrumented/index.html</code> by typing
206     <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
207 siliconforks 2 </p>
208    
209     <p>
210 siliconforks 328 Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
211     appending the page URL to the query string of the <code>jscoverage.html</code> URL.
212     For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
213     will cause the <code>index.html</code> file to be loaded automatically.
214 siliconforks 2 </p>
215    
216 siliconforks 197 <p><img src="screenshot2.png" alt="Screenshot"></p>
217 siliconforks 2
218     <p>
219 siliconforks 328 For this example, the JavaScript does not execute automatically:
220 siliconforks 2 you have to select one of the radio buttons to execute the code.
221     </p>
222    
223 siliconforks 197 <p><img src="screenshot3.png" alt="Screenshot"></p>
224 siliconforks 2
225 siliconforks 115 <h3>3. Generating a coverage report</h3>
226 siliconforks 2
227     <p>
228 siliconforks 328 Once the JavaScript code in the page in the "Browser" tab has been executed, click on
229     the "Summary" tab. This will display the current code coverage statistics.
230 siliconforks 2 </p>
231    
232 siliconforks 197 <p><img src="screenshot4.png" alt="Screenshot"></p>
233 siliconforks 2
234     <p>
235 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
236 siliconforks 2 </p>
237    
238 siliconforks 197 <p><img src="screenshot5.png" alt="Screenshot"></p>
239 siliconforks 2
240 siliconforks 41 <p>
241     You can click one of the links to get a detailed view of a JavaScript source file.
242     </p>
243    
244 siliconforks 197 <p><img src="screenshot6.png" alt="Screenshot"></p>
245 siliconforks 41
246 siliconforks 328 <p>
247     As long as you do not reload the
248     <code>jscoverage.html</code> page, the coverage report statistics are
249     cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
250     another scripted page, or by reloading the frame containing a scripted
251     page) and switch to the "Summary" tab again,
252     the coverage report will combine the statistics from the previous report with any newly generated statistics.
253     Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
254     </p>
255    
256 siliconforks 497 <h2>Window mode</h2>
257 siliconforks 14
258     <p>
259 siliconforks 497 In some situations it may be difficult to execute your code within the <code>&lt;iframe&gt;</code> in the
260 siliconforks 14 JSCoverage "Browser" tab. For example, the code may assume that it is running in
261     the top-level browser window, generating errors if it is executed from within a
262 siliconforks 497 frame. JSCoverage has an alternative mode of operation, called <dfn>window
263 siliconforks 41 mode</dfn>, which may be useful in this case.
264 siliconforks 14 </p>
265    
266     <p>
267 siliconforks 497 To use JSCoverage in window mode, load your URL by clicking the "Open in window"
268     button instead of the "Open in frame" button. This will cause your URL to be
269     opened in a new window. (Depending on your browser settings, it may be opened in
270     a new browser tab instead.) Execute your code in this new window, and
271     then return to the <code>jscoverage.html</code> window and click the "Summary"
272     tab to get code coverage statistics.
273     </p>
274    
275     <h2>Inverted mode</h2>
276    
277     <p>
278     There is another alternative mode of operation, called <dfn>inverted
279     mode</dfn>. Like window mode, this allows you to avoid running your code inside an <code>&lt;iframe&gt;</code>.
280     </p>
281    
282     <p>
283 siliconforks 14 Normally you load <code>jscoverage.html</code> in your web browser, and in its
284     "Browser" tab you launch your test code. In inverted mode, you do the
285     opposite: you load your test page directly in your web browser, and from there
286     you launch JSCoverage. To do this you need to add some code to your test page:
287     </p>
288    
289 siliconforks 198 <pre class="sh_javascript">
290     window.open('path/to/jscoverage.html');
291 siliconforks 14 </pre>
292    
293     <p>
294     The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
295     location of the <code>jscoverage.html</code> file (remember, this will be in the
296     top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
297     the <code>jscoverage</code> executable).
298     </p>
299    
300     <p>
301     You can place this code wherever you like in your page: for example, you could
302     attach it to a button:
303     </p>
304    
305 siliconforks 198 <pre class="sh_html">
306 siliconforks 474 &lt;button type="button" onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
307 siliconforks 14 </pre>
308    
309     <p>
310 siliconforks 37 Note that you <em>must</em> use a <code>window.open</code> call; simply making a
311     link to <code>jscoverage.html</code> is not sufficient.
312     </p>
313    
314     <p>
315 siliconforks 14 An example is located in the <code>doc/example-inverted</code> directory.
316 siliconforks 328 You can instrument the code with the <code>jscoverage</code> program:
317 siliconforks 14 </p>
318    
319     <pre>
320     jscoverage doc/example-inverted doc/instrumented-inverted
321     </pre>
322    
323     <p>
324 siliconforks 328 You can load the page <code>doc/instrumented-inverted/index.html</code>
325     directly in your web browser.
326 siliconforks 14 From this page, you select one of the radio buttons and then click the "Coverage
327     report" button to launch the JSCoverage report.
328     </p>
329    
330 siliconforks 273 <p>
331     Another example is located in the <code>doc/example-jsunit</code> directory.
332     See the <a href="faq.html#jsunit">FAQ</a> for more information.
333     </p>
334    
335 siliconforks 115 <h2><code>jscoverage</code> command line options</h2>
336 siliconforks 19
337     <p>
338     The <code>jscoverage</code> program accepts the following options:
339     </p>
340    
341     <dl>
342     <dt><code>-h</code>, <code>--help</code>
343     <dd>Display a brief help message.
344     <dt><code>-V</code>, <code>--version</code>
345     <dd>Display the version of the program.
346     <dt><code>-v</code>, <code>--verbose</code>
347     <dd>Explain what is being done.
348 siliconforks 207 <dt><code>--encoding=<var>ENCODING</var></code>
349     <dd>Assume that all JavaScript files use the given character encoding. The
350     default is ISO-8859-1.
351 siliconforks 19 <dt><code>--exclude=<var>PATH</var></code>
352     <dd>The command
353     <pre>
354     jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
355     </pre>
356     copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
357     recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
358 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
359 siliconforks 19 <var>PATH</var> can be a file or a directory (in which case the directory and
360     its entire contents are skipped). This option may be given multiple times.
361 siliconforks 386 <dt><code>--js-version=<var>VERSION</var></code>
362     <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
363     are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
364     or <code>ECMAv3</code> (the default).
365 siliconforks 207 <dt><code>--no-highlight</code>
366     <dd>Do not perform syntax highlighting of JavaScript code.
367 siliconforks 19 <dt><code>--no-instrument=<var>PATH</var></code>
368     <dd>The command
369     <pre>
370 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
371 siliconforks 19 </pre>
372     copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
373     recursively, but does not instrument any JavaScript code in
374     <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
375 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
376 siliconforks 19 (JavaScript) file or a directory (in which case any JavaScript files located
377     anywhere underneath the directory are not instrumented). This option may be
378     given multiple times.
379     </dl>
380    
381     <h2>Query string options</h2>
382    
383     <p>
384     When accessing <code>jscoverage.html</code> in a web browser, you may provide a
385     query string consisting of options separated by ampersand (<code>&amp;</code>)
386     or semicolon (<code>;</code>). Any option not containing an equals sign
387 siliconforks 497 (<code>=</code>) is considered to be a URL which will be loaded in the
388     <code>&lt;iframe&gt;</code> within the "Browser" tab.
389 siliconforks 19 </p>
390    
391     <dl>
392 siliconforks 497 <dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code>, <code>frame=<var>URL</var></code>, <code>f=<var>URL</var></code>
393     <dd>Load <var>URL</var> in the <code>&lt;iframe&gt;</code> within the "Browser" tab. (This is the same as specifying
394 siliconforks 19 an option without an equals sign.)
395 siliconforks 497 <dt><code>w=<var>URL</var></code>, <code>window=<var>URL</var></code>
396     <dd>Load <var>URL</var> in a new window (window mode).
397 siliconforks 19 <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
398     <dd>Determines whether to initially display the "Missing" column in the "Summary"
399     tab. <var>BOOLEAN</var> can be
400 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
401 siliconforks 19 (to display the "Missing" column), or
402     <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
403 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
404 siliconforks 19 </dl>
405    
406 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
407    
408     <p>
409 siliconforks 198 The <code>jscoverage-server</code> program is a simple web server. You can use
410     <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
411     directory:
412 siliconforks 115 </p>
413    
414     <pre>
415     cd doc/example
416     jscoverage-server --verbose
417     </pre>
418    
419     <p>
420 siliconforks 198 Once the server is running, you can access the JSCoverage web interface by
421     visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
422     load the <code>doc/example/index.html</code> file by entering
423     <code>index.html</code> in the "URL" input field. (Or you can do this all in
424     one step by loading the URL
425     <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
426     browser.) The
427     <code>jscoverage-server</code> program automatically instruments any served
428 siliconforks 115 JavaScript code, so that code coverage data will be gathered as the code is
429     executed in your browser.
430     </p>
431    
432     <p>
433     The web interface is slightly different from that generated by the
434     <code>jscoverage</code> program: it has a new tab named "Store".
435     To store coverage data, click the "Store" tab.
436     </p>
437    
438 siliconforks 197 <p><img src="screenshot7.png" alt="Screenshot"></p>
439 siliconforks 115
440     <p>
441 siliconforks 326 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
442 siliconforks 115 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
443 siliconforks 198 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
444 siliconforks 115 </p>
445    
446     <p>
447     If you use the "Store" tab again to store coverage data, the new data will be merged with
448     the previous data in the <code>jscoverage-report/</code> directory. This can be useful,
449     for instance, if you wish to run a set of tests in different browsers and generate an
450     aggregate report which combines the data for all of them.
451     </p>
452    
453     <p>
454     You can stop the server by running another instance of <code>jscoverage-server</code> with the
455     <code>--shutdown</code> option:
456     </p>
457    
458     <pre>
459     jscoverage-server --shutdown
460     </pre>
461    
462     <h2>Using <code>jscoverage-server --proxy</code></h2>
463    
464     <p>
465     To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
466     </p>
467    
468     <pre>
469     jscoverage-server --verbose --proxy
470     </pre>
471    
472     <p>
473     Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
474     You can then generate code coverage data for a web page on the server <code>example.com</code>
475     by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.
476     Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
477     by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
478     </p>
479    
480 siliconforks 498 <p>
481     Note that if you are using Internet Explorer and running a web server on your
482     local machine, accessing the web server using a host name of
483     <code>127.0.0.1</code> or <code>localhost</code> will <em>not</em> go through
484     the proxy.
485     See the <a href="faq.html#ie-proxy">FAQ</a> for more details.
486     </p>
487    
488 siliconforks 115 <h2><code>jscoverage-server</code> command line options</h2>
489    
490     <dl>
491     <dt><code>-h</code>, <code>--help</code>
492     <dd>Display a brief help message.
493     <dt><code>-V</code>, <code>--version</code>
494     <dd>Display the version of the program.
495     <dt><code>-v</code>, <code>--verbose</code>
496     <dd>Explain what is being done.
497     <dt><code>--document-root=<var>PATH</var></code>
498     <dd>Serve web content from the directory given by <var>PATH</var>. The default is
499     the current directory. This option may not be given with the <code>--proxy</code> option.
500 siliconforks 207 <dt><code>--encoding=<var>ENCODING</var></code>
501     <dd>Assume that all JavaScript files use the given character encoding. The
502     default is ISO-8859-1. Note that if you use the <code>--proxy</code> option, the
503     character encoding will be determined from the <code>charset</code> parameter in
504     the <code>Content-Type</code> HTTP header.
505 siliconforks 115 <dt><code>--ip-address=<var>ADDRESS</var></code>
506     <dd>Run the server on the IP address given by <var>ADDRESS</var>. The default is <code>127.0.0.1</code>. Specify
507     <code>0.0.0.0</code> to use any address.
508 siliconforks 386 <dt><code>--js-version=<var>VERSION</var></code>
509     <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
510     are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
511     or <code>ECMAv3</code> (the default).
512 siliconforks 502 <dt><code>--mozilla</code>
513     <dd>Specify that the source directory contains an application based on the Mozilla platform (see <a href="#mozilla">below</a>).
514 siliconforks 207 <dt><code>--no-highlight</code>
515     <dd>Do not perform syntax highlighting of JavaScript code.
516 siliconforks 115 <dt><code>--no-instrument=<var>URL</var></code>
517     <dd>Do not instrument JavaScript code from <var>URL</var>. If you are running <code>jscoverage-server</code>
518     with the <code>--proxy</code> option, <var>URL</var> should be a full URL. For example:
519     <pre>
520     jscoverage-server --proxy --no-instrument=http://example.com/scripts/
521     </pre>
522     Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
523     <pre>
524     jscoverage-server --no-instrument=/scripts/
525     </pre>
526     This option may be given multiple times.
527     <dt><code>--port=<var>PORT</var></code>
528     <dd>Run the server on the port given by <var>PORT</var>. The default is port 8080.
529     <dt><code>--proxy</code>
530     <dd>Run as a proxy server.
531     <dt><code>--report-dir=<var>PATH</var></code>
532     <dd>Use the directory given by <var>PATH</var> for storing coverage reports. The default is
533     <code>jscoverage-report/</code> in the current directory.
534     <dt><code>--shutdown</code>
535     <dd>Stop a running instance of the server.
536     </dl>
537    
538 siliconforks 158 <h2>Advanced topics</h2>
539    
540 siliconforks 198 <h3>Storing coverage reports programmatically</h3>
541    
542     <p>
543     If you are executing a test suite using <code>jscoverage-server</code>, you can
544     store a coverage report programmatically by having your test suite call the
545     <code>jscoverage_report</code> function (automatically generated by
546     <code>jscoverage-server</code>) after all your tests have finished running:
547     </p>
548    
549     <pre class="sh_javascript">
550 siliconforks 270 if (window.jscoverage_report) {
551     jscoverage_report();
552 siliconforks 198 }
553     </pre>
554    
555     <p>
556     You can specify the name of the directory in which to store the report by
557     passing the name as a parameter to the <code>jscoverage_report</code> function:
558     </p>
559    
560     <pre class="sh_javascript">
561 siliconforks 270 if (window.jscoverage_report) {
562 siliconforks 198 // determine the directory name based on the browser
563     var directory;
564     if (/MSIE/.test(navigator.userAgent)) {
565     directory = 'IE';
566     }
567     else {
568     directory = 'other';
569     }
570 siliconforks 270 jscoverage_report(directory);
571 siliconforks 198 }
572     </pre>
573    
574     <p>
575     This directory will be a subdirectory under the <code>jscoverage-report/</code>
576     directory (or whatever is specified with the <code>--report-dir</code> option).
577     Using the above example, the report would be stored to either
578     <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
579     </p>
580    
581 siliconforks 201 <p>
582     It is not necessary that your test suite be executed within the
583     <code>jscoverage.html</code> web interface to store a coverage report. The URL
584     of the test suite can simply be loaded directly in a web browser.
585     </p>
586    
587 siliconforks 273 <p>
588     The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
589     reports programmatically.
590     </p>
591    
592 siliconforks 240 <h3>Ignoring certain lines of code</h3>
593 siliconforks 158
594     <p>
595     Sometimes you may wish to exclude certain lines of code from coverage
596     statistics. Some lines of code may be executed only in certain browsers; other
597 siliconforks 198 lines should never be executed at all (they may be present only to detect
598 siliconforks 240 programming errors). You can use specially formatted comments in your code to
599     tell JSCoverage to ignore certain lines of code. These lines will not be
600     included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
601     be indicated with the color yellow.
602 siliconforks 158 </p>
603    
604     <p>
605 siliconforks 240 These comments take the following form:
606 siliconforks 158 </p>
607    
608     <pre class="sh_javascript">
609     //#JSCOVERAGE_IF <var>CONDITION</var>
610     ...
611     //#JSCOVERAGE_ENDIF
612     </pre>
613    
614     <p>
615 siliconforks 240 The comment must be formatted exactly as shown: it must be a line comment
616     starting with <code>//</code>, it must start in the first column, and it must be
617     followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
618     uppercase letters with no intervening white space.
619     </p>
620    
621     <p>
622 siliconforks 158 The <var>CONDITION</var> is an ordinary JavaScript expression; if this
623     expression evaluates to <code>true</code>, then the lines of code between the
624 siliconforks 240 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
625 siliconforks 158 included in coverage statistics; otherwise, they are excluded from coverage
626     statistics.
627     </p>
628    
629     <p>
630 siliconforks 240 For example:
631 siliconforks 158 </p>
632    
633 siliconforks 240 <pre class="sh_javascript">
634     function log(s) {
635     if (window.console) {
636     //#JSCOVERAGE_IF window.console
637     console.log(s);
638     //#JSCOVERAGE_ENDIF
639     }
640     }
641     </pre>
642    
643 siliconforks 158 <p>
644 siliconforks 240 You can exclude code from coverage statistics unconditionally by using
645     <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
646 siliconforks 158 </p>
647    
648     <pre class="sh_javascript">
649 siliconforks 240 function f(x) {
650     if (x === null) {
651     //#JSCOVERAGE_IF 0
652     throw 'error';
653 siliconforks 158 //#JSCOVERAGE_ENDIF
654     }
655 siliconforks 240 ...
656 siliconforks 158 </pre>
657    
658     <p>
659 siliconforks 240 There is also a short form, which must appear on the line preceding an
660     <code>if</code> statement:
661 siliconforks 158 </p>
662    
663     <pre class="sh_javascript">
664 siliconforks 240 //#JSCOVERAGE_IF
665     if (...) {
666     ...
667     }
668     else if (...) {
669     ...
670     }
671     ...
672     else {
673     ...
674     }
675 siliconforks 158 </pre>
676    
677     <p>
678 siliconforks 240
679     In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
680     and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
681     that you expect only one branch of the <code>if</code> statement to be executed;
682     coverage statistics will not be collected for the other branch(es). For
683     example:
684 siliconforks 158 </p>
685    
686     <pre class="sh_javascript">
687 siliconforks 240 function log(s) {
688     //#JSCOVERAGE_IF
689     if (window.console) {
690     console.log(s);
691 siliconforks 158 }
692 siliconforks 240 else if (window.opera) {
693     opera.postError(s);
694     }
695     else {
696     throw 'no logging function available';
697     }
698 siliconforks 158 }
699     </pre>
700    
701 siliconforks 201 <p>
702 siliconforks 240 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
703 siliconforks 201 </p>
704    
705 siliconforks 502 <h3 id="mozilla">Code coverage for Mozilla platform applications</h3>
706    
707     <p>
708     JSCoverage can be used to generate code coverage data for applications based on
709     the Mozilla platform.
710     </p>
711    
712     <div class="warning">
713     <h4>Warning</h4>
714     The functionality described here is highly experimental. It may change in future versions.
715     </div>
716    
717     <p>
718     A simple example program is included in the <code>doc/example-mozilla/</code>
719     directory.
720     You can instrument and run this program as follows:
721     </p>
722    
723     <pre>
724     jscoverage --mozilla --no-instrument=defaults doc/example-mozilla doc/example-mozilla-instrumented
725     xulrunner doc/example-mozilla-instrumented/application.ini -console
726     </pre>
727    
728     <p>
729     Note that the <code>--mozilla</code> option is used to specify that the program
730     is based on the Mozilla platform.
731     Also, the code in the <code>defaults/</code> directory is skipped because the
732     <code>.js</code> files in this directory are preferences files (and are
733     different from ordinary JavaScript files).
734     XULRunner is used to run the instrumented application:
735     </p>
736    
737     <p>
738     <img src="mozilla-before-click.png" alt="Screenshot">
739     </p>
740    
741     <p>
742     The JavaScript code in the application is executed by selecting a radio button:
743     </p>
744    
745     <p>
746     <img src="mozilla-after-click.png" alt="Screenshot">
747     </p>
748    
749     <p>
750     When the application is exited, a coverage report is stored in a subdirectory of
751     the application's directory named <code>jscoverage-report/</code>.
752     You can view the report in a web browser by opening the
753     <code>jscoverage.html</code> file in this directory (i.e.,
754     <code>doc/example-mozilla-instrumented/jscoverage-report/jscoverage.html</code>).
755     </p>
756    
757 siliconforks 2 <h2>Caveats</h2>
758    
759     <ul>
760     <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
761     Expect instrumented code to take at least twice as much time to run.
762     <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
763     elements in HTML files.
764     <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
765     the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
766     <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
767     that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
768     statements, you may get strange results.
769     <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
770     those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
771 siliconforks 198 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
772 siliconforks 2 </ul>
773    
774     <address>
775 siliconforks 427 Copyright &copy; 2007, 2008, 2009 <a href="http://siliconforks.com/"><img src="siliconforks-16x16.png" width="16" height="16" class="icon" alt="Silicon Forks"></a> <a href="http://siliconforks.com/">siliconforks.com</a><br>
776 siliconforks 2 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
777     </address>
778    
779     </body>
780     </html>

  ViewVC Help
Powered by ViewVC 1.1.24