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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 589 - (show 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 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2 <html>
3 <head>
4 <title>JSCoverage user manual</title>
5 <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
6 <link rel="stylesheet" type="text/css" href="doc.css">
7 <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 </head>
11 <body onload="sh_highlightDocument();">
12
13 <h1>JSCoverage user manual</h1>
14
15 <p>
16 JSCoverage is a tool that measures code coverage for JavaScript programs.
17 </p>
18
19 <p>
20 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 </p>
24
25 <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
37 <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 <h2>Compiling JSCoverage</h2>
43
44 <p>
45 You can compile JSCoverage on GNU/Linux or Microsoft Windows, using the GCC C++ compiler (<code>g++</code>). On
46 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 tar jxvf jscoverage-0.5.1.tar.bz2
56 cd jscoverage-0.5.1/
57 ./configure
58 make
59 </pre>
60
61 <p>
62 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 </p>
67
68 <pre>
69 make install
70 </pre>
71
72 <p>
73 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 </p>
77
78 <h2>Using the <code>jscoverage</code> program</h2>
79
80 <p>
81 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 </p>
86
87 <p>
88 Generating code coverage statistics for this example using the
89 <code>jscoverage</code> program involves the following steps:
90 </p>
91
92 <h3>1. Instrumenting code</h3>
93
94 <p>
95 The first step is to add instrumentation to your JavaScript code. You do this by
96 executing <code>jscoverage</code> with two arguments:
97 </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 The directory structure under <var>SOURCE-DIRECTORY</var> will be preserved, so that if you have a file
114 <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 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 </p>
123
124 <table summary="">
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 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 </p>
148
149 <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 summary="">
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 <h3>2. Executing the instrumented code in a web browser</h3>
178
179 <p>
180 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 </p>
185
186 <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 <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 <p><img src="jscoverage.png" alt="Screenshot"></p>
235
236 <p>
237 The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
238 You can load a URL into this frame by entering it into the "URL" input field and clicking the "Open in frame" button.
239 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 </p>
244
245 <p>
246 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 </p>
249
250 <p>
251 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 </p>
256
257 <p><img src="jscoverage-browser.png" alt="Screenshot"></p>
258
259 <p>
260 For this example, the JavaScript does not execute automatically:
261 you have to select one of the radio buttons to execute the code.
262 </p>
263
264 <p><img src="jscoverage-browser-executed.png" alt="Screenshot"></p>
265
266 <h3>3. Generating a coverage report</h3>
267
268 <p>
269 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 </p>
272
273 <p><img src="jscoverage-summary.png" alt="Screenshot"></p>
274
275 <p>
276 You can click the checkbox to show a list of statements missed during execution.
277 </p>
278
279 <p><img src="jscoverage-summary-missing.png" alt="Screenshot"></p>
280
281 <p>
282 You can click one of the links to get a detailed view of a JavaScript source file.
283 </p>
284
285 <p><img src="jscoverage-source.png" alt="Screenshot"></p>
286
287 <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 <h2>Window mode</h2>
298
299 <p>
300 In some situations it may be difficult to execute your code within the <code>&lt;iframe&gt;</code> in the
301 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 frame. JSCoverage has an alternative mode of operation, called <dfn>window
304 mode</dfn>, which may be useful in this case.
305 </p>
306
307 <p>
308 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 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 <pre class="sh_javascript">
331 window.open('path/to/jscoverage.html');
332 </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 <pre class="sh_html">
347 &lt;button type="button" onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
348 </pre>
349
350 <p>
351 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 An example is located in the <code>doc/example-inverted</code> directory.
357 You can instrument the code with the <code>jscoverage</code> program:
358 </p>
359
360 <pre>
361 jscoverage doc/example-inverted doc/instrumented-inverted
362 </pre>
363
364 <p>
365 You can load the page <code>doc/instrumented-inverted/index.html</code>
366 directly in your web browser.
367 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 <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 <h2><code>jscoverage</code> command line options</h2>
377
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 <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 <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 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
400 <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 <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 <dt><code>--no-highlight</code>
407 <dd>Do not perform syntax highlighting of JavaScript code.
408 <dt><code>--no-instrument=<var>PATH</var></code>
409 <dd>The command
410 <pre>
411 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
412 </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 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
417 (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 (<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 </p>
431
432 <dl>
433 <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 an option without an equals sign.)
436 <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 <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 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
442 (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 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
445 </dl>
446
447 <h2>Using the <code>jscoverage-server</code> program</h2>
448
449 <p>
450 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 </p>
454
455 <pre>
456 cd doc/example
457 jscoverage-server --verbose
458 </pre>
459
460 <p>
461 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 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 <p><img src="jscoverage-store.png" alt="Screenshot"></p>
480
481 <p>
482 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
483 You can view this stored report at any time by opening <code>jscoverage-report/jscoverage.html</code> in
484 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
485 </p>
486
487
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 <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 <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 <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 <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 <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 <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 <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 <dt><code>--no-highlight</code>
567 <dd>Do not perform syntax highlighting of JavaScript code.
568 <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 <h2>Advanced topics</h2>
591
592 <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 if (window.jscoverage_report) {
603 jscoverage_report();
604 }
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 if (window.jscoverage_report) {
614 // 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 jscoverage_report(directory);
623 }
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 <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 <p>
640 The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
641 reports programmatically.
642 </p>
643
644 <h3>Ignoring certain lines of code</h3>
645
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 lines should never be executed at all (they may be present only to detect
650 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 </p>
655
656 <p>
657 These comments take the following form:
658 </p>
659
660 <pre class="sh_javascript">
661 //#JSCOVERAGE_IF <var>CONDITION</var>
662 ...
663 //#JSCOVERAGE_ENDIF
664 </pre>
665
666 <p>
667 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 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 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
677 included in coverage statistics; otherwise, they are excluded from coverage
678 statistics.
679 </p>
680
681 <p>
682 For example:
683 </p>
684
685 <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 <p>
696 You can exclude code from coverage statistics unconditionally by using
697 <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
698 </p>
699
700 <pre class="sh_javascript">
701 function f(x) {
702 if (x === null) {
703 //#JSCOVERAGE_IF 0
704 throw 'error';
705 //#JSCOVERAGE_ENDIF
706 }
707 ...
708 </pre>
709
710 <p>
711 There is also a short form, which must appear on the line preceding an
712 <code>if</code> statement:
713 </p>
714
715 <pre class="sh_javascript">
716 //#JSCOVERAGE_IF
717 if (...) {
718 ...
719 }
720 else if (...) {
721 ...
722 }
723 ...
724 else {
725 ...
726 }
727 </pre>
728
729 <p>
730
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 </p>
737
738 <pre class="sh_javascript">
739 function log(s) {
740 //#JSCOVERAGE_IF
741 if (window.console) {
742 console.log(s);
743 }
744 else if (window.opera) {
745 opera.postError(s);
746 }
747 else {
748 throw 'no logging function available';
749 }
750 }
751 </pre>
752
753 <p>
754 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
755 </p>
756
757 <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 <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 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
824 </ul>
825
826 <address>
827 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 <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