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

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 589 - (hide annotations)
Mon Sep 20 13:04:15 2010 UTC (9 years, 1 month ago) by siliconforks
File MIME type: text/html
File size: 29153 byte(s)
Increment version number.

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 589 tar jxvf jscoverage-0.5.1.tar.bz2
56     cd jscoverage-0.5.1/
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 584 The directory structure under <var>SOURCE-DIRECTORY</var> will be 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 584 In addition, <code>jscoverage</code> will create a file called <code>jscoverage.html</code>
121     which will be used to execute the instrumented code.
122 siliconforks 2 </p>
123    
124 siliconforks 584 <table summary="">
125 siliconforks 2 <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 siliconforks 584 <table summary="">
160 siliconforks 328 <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 584 You should generally execute your instrumented code by loading it from a web
181     server.
182     Using a web browser, connect to your web server and open the generated
183     <code>jscoverage.html</code> file.
184 siliconforks 2 </p>
185    
186 siliconforks 584 <div class="warning">
187     <h4>Warning</h4>
188    
189     <p>
190     You should avoid accessing <code>jscoverage.html</code> using a
191     <code>file:</code> URL.
192     Previous versions of this manual suggested using such a URL, but recent web
193     browsers have been adding <a
194     href="http://code.google.com/p/chromium/issues/detail?id=4197">new security
195     restrictions</a> on <code>file:</code> URLs, which can cause problems with
196     JSCoverage.
197     Use a web server to avoid these problems.
198     </p>
199    
200     <p>
201     Any web server can be used. For example,
202     you might choose to place your <var>DESTINATION-DIRECTORY</var> inside an <a
203     href="http://httpd.apache.org/">Apache</a> web server installation, so that
204     Apache can serve files from it; or you might want
205     to run a simpler web server, such as the <code>SimpleHTTPServer</code> that
206     comes with <a href="http://python.org/">Python</a>:
207     </p>
208     <pre>python.exe C:\Python27\Lib\SimpleHTTPServer.py</pre>
209    
210     <p>
211     If for some reason you cannot run a web server and must use a <code>file:</code> URL,
212     there are a few things you can try:
213     </p>
214    
215     <ul style="margin-bottom: 0;">
216     <li>If using Firefox, organize your test suite so that all your HTML files are located in the same directory, without any subdirectories.</li>
217     <li>If using Google Chrome, try starting the browser with the <code>--allow-file-access-from-files</code> command line option.</li>
218     <li>Try using an older web browser. IE 6 works quite well. :)</li>
219     </ul>
220     </div>
221    
222     <p>
223     The <code>jscoverage.html</code> page contains a tabbed user interface:
224     </p>
225    
226 siliconforks 2 <ul>
227     <li>The "Browser" tab is used to display pages with instrumented scripts.
228     <li>The "Summary" tab is used to display code coverage data.
229     <li>The "Source" tab is used to display JavaScript code, showing the number of times
230     each line of code was executed.
231     <li>The "About" tab displays information about the current version of JSCoverage.
232     </ul>
233    
234 siliconforks 587 <p><img src="jscoverage.png" alt="Screenshot"></p>
235 siliconforks 2
236     <p>
237     The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
238 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.
239 siliconforks 64 You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
240     or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
241     from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
242     server, will give unexpected results.
243 siliconforks 2 </p>
244    
245     <p>
246 siliconforks 328 For example, you can load the file <code>doc/instrumented/index.html</code> by typing
247     <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
248 siliconforks 2 </p>
249    
250     <p>
251 siliconforks 328 Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
252     appending the page URL to the query string of the <code>jscoverage.html</code> URL.
253     For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
254     will cause the <code>index.html</code> file to be loaded automatically.
255 siliconforks 2 </p>
256    
257 siliconforks 587 <p><img src="jscoverage-browser.png" alt="Screenshot"></p>
258 siliconforks 2
259     <p>
260 siliconforks 328 For this example, the JavaScript does not execute automatically:
261 siliconforks 2 you have to select one of the radio buttons to execute the code.
262     </p>
263    
264 siliconforks 587 <p><img src="jscoverage-browser-executed.png" alt="Screenshot"></p>
265 siliconforks 2
266 siliconforks 115 <h3>3. Generating a coverage report</h3>
267 siliconforks 2
268     <p>
269 siliconforks 328 Once the JavaScript code in the page in the "Browser" tab has been executed, click on
270     the "Summary" tab. This will display the current code coverage statistics.
271 siliconforks 2 </p>
272    
273 siliconforks 587 <p><img src="jscoverage-summary.png" alt="Screenshot"></p>
274 siliconforks 2
275     <p>
276 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
277 siliconforks 2 </p>
278    
279 siliconforks 587 <p><img src="jscoverage-summary-missing.png" alt="Screenshot"></p>
280 siliconforks 2
281 siliconforks 41 <p>
282     You can click one of the links to get a detailed view of a JavaScript source file.
283     </p>
284    
285 siliconforks 587 <p><img src="jscoverage-source.png" alt="Screenshot"></p>
286 siliconforks 41
287 siliconforks 328 <p>
288     As long as you do not reload the
289     <code>jscoverage.html</code> page, the coverage report statistics are
290     cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
291     another scripted page, or by reloading the frame containing a scripted
292     page) and switch to the "Summary" tab again,
293     the coverage report will combine the statistics from the previous report with any newly generated statistics.
294     Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
295     </p>
296    
297 siliconforks 497 <h2>Window mode</h2>
298 siliconforks 14
299     <p>
300 siliconforks 497 In some situations it may be difficult to execute your code within the <code>&lt;iframe&gt;</code> in the
301 siliconforks 14 JSCoverage "Browser" tab. For example, the code may assume that it is running in
302     the top-level browser window, generating errors if it is executed from within a
303 siliconforks 497 frame. JSCoverage has an alternative mode of operation, called <dfn>window
304 siliconforks 41 mode</dfn>, which may be useful in this case.
305 siliconforks 14 </p>
306    
307     <p>
308 siliconforks 497 To use JSCoverage in window mode, load your URL by clicking the "Open in window"
309     button instead of the "Open in frame" button. This will cause your URL to be
310     opened in a new window. (Depending on your browser settings, it may be opened in
311     a new browser tab instead.) Execute your code in this new window, and
312     then return to the <code>jscoverage.html</code> window and click the "Summary"
313     tab to get code coverage statistics.
314     </p>
315    
316     <h2>Inverted mode</h2>
317    
318     <p>
319     There is another alternative mode of operation, called <dfn>inverted
320     mode</dfn>. Like window mode, this allows you to avoid running your code inside an <code>&lt;iframe&gt;</code>.
321     </p>
322    
323     <p>
324 siliconforks 14 Normally you load <code>jscoverage.html</code> in your web browser, and in its
325     "Browser" tab you launch your test code. In inverted mode, you do the
326     opposite: you load your test page directly in your web browser, and from there
327     you launch JSCoverage. To do this you need to add some code to your test page:
328     </p>
329    
330 siliconforks 198 <pre class="sh_javascript">
331     window.open('path/to/jscoverage.html');
332 siliconforks 14 </pre>
333    
334     <p>
335     The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
336     location of the <code>jscoverage.html</code> file (remember, this will be in the
337     top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
338     the <code>jscoverage</code> executable).
339     </p>
340    
341     <p>
342     You can place this code wherever you like in your page: for example, you could
343     attach it to a button:
344     </p>
345    
346 siliconforks 198 <pre class="sh_html">
347 siliconforks 474 &lt;button type="button" onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
348 siliconforks 14 </pre>
349    
350     <p>
351 siliconforks 37 Note that you <em>must</em> use a <code>window.open</code> call; simply making a
352     link to <code>jscoverage.html</code> is not sufficient.
353     </p>
354    
355     <p>
356 siliconforks 14 An example is located in the <code>doc/example-inverted</code> directory.
357 siliconforks 328 You can instrument the code with the <code>jscoverage</code> program:
358 siliconforks 14 </p>
359    
360     <pre>
361     jscoverage doc/example-inverted doc/instrumented-inverted
362     </pre>
363    
364     <p>
365 siliconforks 328 You can load the page <code>doc/instrumented-inverted/index.html</code>
366     directly in your web browser.
367 siliconforks 14 From this page, you select one of the radio buttons and then click the "Coverage
368     report" button to launch the JSCoverage report.
369     </p>
370    
371 siliconforks 273 <p>
372     Another example is located in the <code>doc/example-jsunit</code> directory.
373     See the <a href="faq.html#jsunit">FAQ</a> for more information.
374     </p>
375    
376 siliconforks 115 <h2><code>jscoverage</code> command line options</h2>
377 siliconforks 19
378     <p>
379     The <code>jscoverage</code> program accepts the following options:
380     </p>
381    
382     <dl>
383     <dt><code>-h</code>, <code>--help</code>
384     <dd>Display a brief help message.
385     <dt><code>-V</code>, <code>--version</code>
386     <dd>Display the version of the program.
387     <dt><code>-v</code>, <code>--verbose</code>
388     <dd>Explain what is being done.
389 siliconforks 207 <dt><code>--encoding=<var>ENCODING</var></code>
390     <dd>Assume that all JavaScript files use the given character encoding. The
391     default is ISO-8859-1.
392 siliconforks 19 <dt><code>--exclude=<var>PATH</var></code>
393     <dd>The command
394     <pre>
395     jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
396     </pre>
397     copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
398     recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
399 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
400 siliconforks 19 <var>PATH</var> can be a file or a directory (in which case the directory and
401     its entire contents are skipped). This option may be given multiple times.
402 siliconforks 386 <dt><code>--js-version=<var>VERSION</var></code>
403     <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
404     are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
405     or <code>ECMAv3</code> (the default).
406 siliconforks 207 <dt><code>--no-highlight</code>
407     <dd>Do not perform syntax highlighting of JavaScript code.
408 siliconforks 19 <dt><code>--no-instrument=<var>PATH</var></code>
409     <dd>The command
410     <pre>
411 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
412 siliconforks 19 </pre>
413     copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
414     recursively, but does not instrument any JavaScript code in
415     <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
416 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
417 siliconforks 19 (JavaScript) file or a directory (in which case any JavaScript files located
418     anywhere underneath the directory are not instrumented). This option may be
419     given multiple times.
420     </dl>
421    
422     <h2>Query string options</h2>
423    
424     <p>
425     When accessing <code>jscoverage.html</code> in a web browser, you may provide a
426     query string consisting of options separated by ampersand (<code>&amp;</code>)
427     or semicolon (<code>;</code>). Any option not containing an equals sign
428 siliconforks 497 (<code>=</code>) is considered to be a URL which will be loaded in the
429     <code>&lt;iframe&gt;</code> within the "Browser" tab.
430 siliconforks 19 </p>
431    
432     <dl>
433 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>
434     <dd>Load <var>URL</var> in the <code>&lt;iframe&gt;</code> within the "Browser" tab. (This is the same as specifying
435 siliconforks 19 an option without an equals sign.)
436 siliconforks 497 <dt><code>w=<var>URL</var></code>, <code>window=<var>URL</var></code>
437     <dd>Load <var>URL</var> in a new window (window mode).
438 siliconforks 19 <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
439     <dd>Determines whether to initially display the "Missing" column in the "Summary"
440     tab. <var>BOOLEAN</var> can be
441 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
442 siliconforks 19 (to display the "Missing" column), or
443     <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
444 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
445 siliconforks 19 </dl>
446    
447 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
448    
449     <p>
450 siliconforks 198 The <code>jscoverage-server</code> program is a simple web server. You can use
451     <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
452     directory:
453 siliconforks 115 </p>
454    
455     <pre>
456     cd doc/example
457     jscoverage-server --verbose
458     </pre>
459    
460     <p>
461 siliconforks 198 Once the server is running, you can access the JSCoverage web interface by
462     visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
463     load the <code>doc/example/index.html</code> file by entering
464     <code>index.html</code> in the "URL" input field. (Or you can do this all in
465     one step by loading the URL
466     <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
467     browser.) The
468     <code>jscoverage-server</code> program automatically instruments any served
469 siliconforks 115 JavaScript code, so that code coverage data will be gathered as the code is
470     executed in your browser.
471     </p>
472    
473     <p>
474     The web interface is slightly different from that generated by the
475     <code>jscoverage</code> program: it has a new tab named "Store".
476     To store coverage data, click the "Store" tab.
477     </p>
478    
479 siliconforks 587 <p><img src="jscoverage-store.png" alt="Screenshot"></p>
480 siliconforks 115
481     <p>
482 siliconforks 326 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
483 siliconforks 584 You can view this stored report at any time by opening <code>jscoverage-report/jscoverage.html</code> in
484 siliconforks 198 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
485 siliconforks 115 </p>
486    
487 siliconforks 584
488     <div class="warning">
489     <h4>Warning</h4>
490    
491     <p style="margin-bottom: 0;">
492     The report does not work in Google Chrome when viewed using a <code>file:</code>
493     URL. Either use a web server to serve the report (not <code>jscoverage-server</code>, but an ordinary web server)
494     or start Google Chrome with the <code>--allow-file-access-from-files</code> command line option.
495     </p>
496     </div>
497    
498 siliconforks 115 <p>
499     If you use the "Store" tab again to store coverage data, the new data will be merged with
500     the previous data in the <code>jscoverage-report/</code> directory. This can be useful,
501     for instance, if you wish to run a set of tests in different browsers and generate an
502     aggregate report which combines the data for all of them.
503     </p>
504    
505     <p>
506     You can stop the server by running another instance of <code>jscoverage-server</code> with the
507     <code>--shutdown</code> option:
508     </p>
509    
510     <pre>
511     jscoverage-server --shutdown
512     </pre>
513    
514     <h2>Using <code>jscoverage-server --proxy</code></h2>
515    
516     <p>
517     To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
518     </p>
519    
520     <pre>
521     jscoverage-server --verbose --proxy
522     </pre>
523    
524     <p>
525     Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
526     You can then generate code coverage data for a web page on the server <code>example.com</code>
527     by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.
528     Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
529     by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
530     </p>
531    
532 siliconforks 498 <p>
533     Note that if you are using Internet Explorer and running a web server on your
534     local machine, accessing the web server using a host name of
535     <code>127.0.0.1</code> or <code>localhost</code> will <em>not</em> go through
536     the proxy.
537     See the <a href="faq.html#ie-proxy">FAQ</a> for more details.
538     </p>
539    
540 siliconforks 115 <h2><code>jscoverage-server</code> command line options</h2>
541    
542     <dl>
543     <dt><code>-h</code>, <code>--help</code>
544     <dd>Display a brief help message.
545     <dt><code>-V</code>, <code>--version</code>
546     <dd>Display the version of the program.
547     <dt><code>-v</code>, <code>--verbose</code>
548     <dd>Explain what is being done.
549     <dt><code>--document-root=<var>PATH</var></code>
550     <dd>Serve web content from the directory given by <var>PATH</var>. The default is
551     the current directory. This option may not be given with the <code>--proxy</code> option.
552 siliconforks 207 <dt><code>--encoding=<var>ENCODING</var></code>
553     <dd>Assume that all JavaScript files use the given character encoding. The
554     default is ISO-8859-1. Note that if you use the <code>--proxy</code> option, the
555     character encoding will be determined from the <code>charset</code> parameter in
556     the <code>Content-Type</code> HTTP header.
557 siliconforks 115 <dt><code>--ip-address=<var>ADDRESS</var></code>
558     <dd>Run the server on the IP address given by <var>ADDRESS</var>. The default is <code>127.0.0.1</code>. Specify
559     <code>0.0.0.0</code> to use any address.
560 siliconforks 386 <dt><code>--js-version=<var>VERSION</var></code>
561     <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
562     are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
563     or <code>ECMAv3</code> (the default).
564 siliconforks 502 <dt><code>--mozilla</code>
565     <dd>Specify that the source directory contains an application based on the Mozilla platform (see <a href="#mozilla">below</a>).
566 siliconforks 207 <dt><code>--no-highlight</code>
567     <dd>Do not perform syntax highlighting of JavaScript code.
568 siliconforks 115 <dt><code>--no-instrument=<var>URL</var></code>
569     <dd>Do not instrument JavaScript code from <var>URL</var>. If you are running <code>jscoverage-server</code>
570     with the <code>--proxy</code> option, <var>URL</var> should be a full URL. For example:
571     <pre>
572     jscoverage-server --proxy --no-instrument=http://example.com/scripts/
573     </pre>
574     Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
575     <pre>
576     jscoverage-server --no-instrument=/scripts/
577     </pre>
578     This option may be given multiple times.
579     <dt><code>--port=<var>PORT</var></code>
580     <dd>Run the server on the port given by <var>PORT</var>. The default is port 8080.
581     <dt><code>--proxy</code>
582     <dd>Run as a proxy server.
583     <dt><code>--report-dir=<var>PATH</var></code>
584     <dd>Use the directory given by <var>PATH</var> for storing coverage reports. The default is
585     <code>jscoverage-report/</code> in the current directory.
586     <dt><code>--shutdown</code>
587     <dd>Stop a running instance of the server.
588     </dl>
589    
590 siliconforks 158 <h2>Advanced topics</h2>
591    
592 siliconforks 198 <h3>Storing coverage reports programmatically</h3>
593    
594     <p>
595     If you are executing a test suite using <code>jscoverage-server</code>, you can
596     store a coverage report programmatically by having your test suite call the
597     <code>jscoverage_report</code> function (automatically generated by
598     <code>jscoverage-server</code>) after all your tests have finished running:
599     </p>
600    
601     <pre class="sh_javascript">
602 siliconforks 270 if (window.jscoverage_report) {
603     jscoverage_report();
604 siliconforks 198 }
605     </pre>
606    
607     <p>
608     You can specify the name of the directory in which to store the report by
609     passing the name as a parameter to the <code>jscoverage_report</code> function:
610     </p>
611    
612     <pre class="sh_javascript">
613 siliconforks 270 if (window.jscoverage_report) {
614 siliconforks 198 // determine the directory name based on the browser
615     var directory;
616     if (/MSIE/.test(navigator.userAgent)) {
617     directory = 'IE';
618     }
619     else {
620     directory = 'other';
621     }
622 siliconforks 270 jscoverage_report(directory);
623 siliconforks 198 }
624     </pre>
625    
626     <p>
627     This directory will be a subdirectory under the <code>jscoverage-report/</code>
628     directory (or whatever is specified with the <code>--report-dir</code> option).
629     Using the above example, the report would be stored to either
630     <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
631     </p>
632    
633 siliconforks 201 <p>
634     It is not necessary that your test suite be executed within the
635     <code>jscoverage.html</code> web interface to store a coverage report. The URL
636     of the test suite can simply be loaded directly in a web browser.
637     </p>
638    
639 siliconforks 273 <p>
640     The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
641     reports programmatically.
642     </p>
643    
644 siliconforks 240 <h3>Ignoring certain lines of code</h3>
645 siliconforks 158
646     <p>
647     Sometimes you may wish to exclude certain lines of code from coverage
648     statistics. Some lines of code may be executed only in certain browsers; other
649 siliconforks 198 lines should never be executed at all (they may be present only to detect
650 siliconforks 240 programming errors). You can use specially formatted comments in your code to
651     tell JSCoverage to ignore certain lines of code. These lines will not be
652     included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
653     be indicated with the color yellow.
654 siliconforks 158 </p>
655    
656     <p>
657 siliconforks 240 These comments take the following form:
658 siliconforks 158 </p>
659    
660     <pre class="sh_javascript">
661     //#JSCOVERAGE_IF <var>CONDITION</var>
662     ...
663     //#JSCOVERAGE_ENDIF
664     </pre>
665    
666     <p>
667 siliconforks 240 The comment must be formatted exactly as shown: it must be a line comment
668     starting with <code>//</code>, it must start in the first column, and it must be
669     followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
670     uppercase letters with no intervening white space.
671     </p>
672    
673     <p>
674 siliconforks 158 The <var>CONDITION</var> is an ordinary JavaScript expression; if this
675     expression evaluates to <code>true</code>, then the lines of code between the
676 siliconforks 240 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
677 siliconforks 158 included in coverage statistics; otherwise, they are excluded from coverage
678     statistics.
679     </p>
680    
681     <p>
682 siliconforks 240 For example:
683 siliconforks 158 </p>
684    
685 siliconforks 240 <pre class="sh_javascript">
686     function log(s) {
687     if (window.console) {
688     //#JSCOVERAGE_IF window.console
689     console.log(s);
690     //#JSCOVERAGE_ENDIF
691     }
692     }
693     </pre>
694    
695 siliconforks 158 <p>
696 siliconforks 240 You can exclude code from coverage statistics unconditionally by using
697     <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
698 siliconforks 158 </p>
699    
700     <pre class="sh_javascript">
701 siliconforks 240 function f(x) {
702     if (x === null) {
703     //#JSCOVERAGE_IF 0
704     throw 'error';
705 siliconforks 158 //#JSCOVERAGE_ENDIF
706     }
707 siliconforks 240 ...
708 siliconforks 158 </pre>
709    
710     <p>
711 siliconforks 240 There is also a short form, which must appear on the line preceding an
712     <code>if</code> statement:
713 siliconforks 158 </p>
714    
715     <pre class="sh_javascript">
716 siliconforks 240 //#JSCOVERAGE_IF
717     if (...) {
718     ...
719     }
720     else if (...) {
721     ...
722     }
723     ...
724     else {
725     ...
726     }
727 siliconforks 158 </pre>
728    
729     <p>
730 siliconforks 240
731     In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
732     and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
733     that you expect only one branch of the <code>if</code> statement to be executed;
734     coverage statistics will not be collected for the other branch(es). For
735     example:
736 siliconforks 158 </p>
737    
738     <pre class="sh_javascript">
739 siliconforks 240 function log(s) {
740     //#JSCOVERAGE_IF
741     if (window.console) {
742     console.log(s);
743 siliconforks 158 }
744 siliconforks 240 else if (window.opera) {
745     opera.postError(s);
746     }
747     else {
748     throw 'no logging function available';
749     }
750 siliconforks 158 }
751     </pre>
752    
753 siliconforks 201 <p>
754 siliconforks 240 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
755 siliconforks 201 </p>
756    
757 siliconforks 502 <h3 id="mozilla">Code coverage for Mozilla platform applications</h3>
758    
759     <p>
760     JSCoverage can be used to generate code coverage data for applications based on
761     the Mozilla platform.
762     </p>
763    
764     <div class="warning">
765     <h4>Warning</h4>
766     The functionality described here is highly experimental. It may change in future versions.
767     </div>
768    
769     <p>
770     A simple example program is included in the <code>doc/example-mozilla/</code>
771     directory.
772     You can instrument and run this program as follows:
773     </p>
774    
775     <pre>
776     jscoverage --mozilla --no-instrument=defaults doc/example-mozilla doc/example-mozilla-instrumented
777     xulrunner doc/example-mozilla-instrumented/application.ini -console
778     </pre>
779    
780     <p>
781     Note that the <code>--mozilla</code> option is used to specify that the program
782     is based on the Mozilla platform.
783     Also, the code in the <code>defaults/</code> directory is skipped because the
784     <code>.js</code> files in this directory are preferences files (and are
785     different from ordinary JavaScript files).
786     XULRunner is used to run the instrumented application:
787     </p>
788    
789     <p>
790     <img src="mozilla-before-click.png" alt="Screenshot">
791     </p>
792    
793     <p>
794     The JavaScript code in the application is executed by selecting a radio button:
795     </p>
796    
797     <p>
798     <img src="mozilla-after-click.png" alt="Screenshot">
799     </p>
800    
801     <p>
802     When the application is exited, a coverage report is stored in a subdirectory of
803     the application's directory named <code>jscoverage-report/</code>.
804     You can view the report in a web browser by opening the
805     <code>jscoverage.html</code> file in this directory (i.e.,
806     <code>doc/example-mozilla-instrumented/jscoverage-report/jscoverage.html</code>).
807     </p>
808    
809 siliconforks 2 <h2>Caveats</h2>
810    
811     <ul>
812     <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
813     Expect instrumented code to take at least twice as much time to run.
814     <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
815     elements in HTML files.
816     <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
817     the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
818     <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
819     that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
820     statements, you may get strange results.
821     <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
822     those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
823 siliconforks 198 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
824 siliconforks 2 </ul>
825    
826     <address>
827 siliconforks 505 Copyright &copy; 2007, 2008, 2009, 2010 <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>
828 siliconforks 2 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
829     </address>
830    
831     </body>
832     </html>

  ViewVC Help
Powered by ViewVC 1.1.24