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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 560 - (show annotations)
Sat Apr 24 15:44:28 2010 UTC (9 years, 6 months ago) by siliconforks
File MIME type: text/html
File size: 27105 byte(s)
Update 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.tar.bz2
56 cd jscoverage-0.5/
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> is 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> creates a file called <code>jscoverage.html</code>
121 which is used to execute the instrumented code.
122 </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 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>
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 Open the generated <code>jscoverage.html</code> file
181 (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
182 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 <p><img src="screenshot.png" alt="Screenshot"></p>
194
195 <p>
196 The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
197 You can load a URL into this frame by entering it into the "URL" input field and clicking the "Open in frame" button.
198 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 </p>
203
204 <p>
205 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 </p>
208
209 <p>
210 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 </p>
215
216 <p><img src="screenshot2.png" alt="Screenshot"></p>
217
218 <p>
219 For this example, the JavaScript does not execute automatically:
220 you have to select one of the radio buttons to execute the code.
221 </p>
222
223 <p><img src="screenshot3.png" alt="Screenshot"></p>
224
225 <h3>3. Generating a coverage report</h3>
226
227 <p>
228 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 </p>
231
232 <p><img src="screenshot4.png" alt="Screenshot"></p>
233
234 <p>
235 You can click the checkbox to show a list of statements missed during execution.
236 </p>
237
238 <p><img src="screenshot5.png" alt="Screenshot"></p>
239
240 <p>
241 You can click one of the links to get a detailed view of a JavaScript source file.
242 </p>
243
244 <p><img src="screenshot6.png" alt="Screenshot"></p>
245
246 <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 <h2>Window mode</h2>
257
258 <p>
259 In some situations it may be difficult to execute your code within the <code>&lt;iframe&gt;</code> in the
260 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 frame. JSCoverage has an alternative mode of operation, called <dfn>window
263 mode</dfn>, which may be useful in this case.
264 </p>
265
266 <p>
267 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 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 <pre class="sh_javascript">
290 window.open('path/to/jscoverage.html');
291 </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 <pre class="sh_html">
306 &lt;button type="button" onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
307 </pre>
308
309 <p>
310 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 An example is located in the <code>doc/example-inverted</code> directory.
316 You can instrument the code with the <code>jscoverage</code> program:
317 </p>
318
319 <pre>
320 jscoverage doc/example-inverted doc/instrumented-inverted
321 </pre>
322
323 <p>
324 You can load the page <code>doc/instrumented-inverted/index.html</code>
325 directly in your web browser.
326 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 <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 <h2><code>jscoverage</code> command line options</h2>
336
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 <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 <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 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
359 <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 <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 <dt><code>--no-highlight</code>
366 <dd>Do not perform syntax highlighting of JavaScript code.
367 <dt><code>--no-instrument=<var>PATH</var></code>
368 <dd>The command
369 <pre>
370 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
371 </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 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
376 (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 (<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 </p>
390
391 <dl>
392 <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 an option without an equals sign.)
395 <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 <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 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
401 (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 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
404 </dl>
405
406 <h2>Using the <code>jscoverage-server</code> program</h2>
407
408 <p>
409 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 </p>
413
414 <pre>
415 cd doc/example
416 jscoverage-server --verbose
417 </pre>
418
419 <p>
420 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 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 <p><img src="screenshot7.png" alt="Screenshot"></p>
439
440 <p>
441 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
442 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
443 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
444 </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 <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 <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 <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 <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 <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 <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 <dt><code>--no-highlight</code>
515 <dd>Do not perform syntax highlighting of JavaScript code.
516 <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 <h2>Advanced topics</h2>
539
540 <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 if (window.jscoverage_report) {
551 jscoverage_report();
552 }
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 if (window.jscoverage_report) {
562 // 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 jscoverage_report(directory);
571 }
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 <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 <p>
588 The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
589 reports programmatically.
590 </p>
591
592 <h3>Ignoring certain lines of code</h3>
593
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 lines should never be executed at all (they may be present only to detect
598 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 </p>
603
604 <p>
605 These comments take the following form:
606 </p>
607
608 <pre class="sh_javascript">
609 //#JSCOVERAGE_IF <var>CONDITION</var>
610 ...
611 //#JSCOVERAGE_ENDIF
612 </pre>
613
614 <p>
615 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 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 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
625 included in coverage statistics; otherwise, they are excluded from coverage
626 statistics.
627 </p>
628
629 <p>
630 For example:
631 </p>
632
633 <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 <p>
644 You can exclude code from coverage statistics unconditionally by using
645 <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
646 </p>
647
648 <pre class="sh_javascript">
649 function f(x) {
650 if (x === null) {
651 //#JSCOVERAGE_IF 0
652 throw 'error';
653 //#JSCOVERAGE_ENDIF
654 }
655 ...
656 </pre>
657
658 <p>
659 There is also a short form, which must appear on the line preceding an
660 <code>if</code> statement:
661 </p>
662
663 <pre class="sh_javascript">
664 //#JSCOVERAGE_IF
665 if (...) {
666 ...
667 }
668 else if (...) {
669 ...
670 }
671 ...
672 else {
673 ...
674 }
675 </pre>
676
677 <p>
678
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 </p>
685
686 <pre class="sh_javascript">
687 function log(s) {
688 //#JSCOVERAGE_IF
689 if (window.console) {
690 console.log(s);
691 }
692 else if (window.opera) {
693 opera.postError(s);
694 }
695 else {
696 throw 'no logging function available';
697 }
698 }
699 </pre>
700
701 <p>
702 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
703 </p>
704
705 <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 <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 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
772 </ul>
773
774 <address>
775 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>
776 <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