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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 393 - (show annotations)
Tue Nov 11 22:00:48 2008 UTC (11 years ago) by siliconforks
File MIME type: text/html
File size: 24034 byte(s)
Mention that g++ is now required for compilation.

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.4.tar.bz2
56 cd jscoverage-0.4/
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 </p>
121
122 <table>
123 <tr>
124 <td><pre>
125 <var>SOURCE-DIRECTORY</var>/
126 dir/
127 index.html
128 script.js
129
130 </pre></td>
131 <td class="arrow">&rarr;</td>
132 <td><pre>
133 <var>DESTINATION-DIRECTORY</var>/
134 dir/
135 index.html
136 script.js [instrumented]
137 jscoverage.html
138 </pre></td>
139 </tr>
140 </table>
141
142 <p>
143 In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
144 which is used to execute the instrumented code.
145 </p>
146
147 <p>
148 To instrument the code in the <code>doc/example/</code> directory, execute the
149 following command from the top-level directory of the JSCoverage distribution:
150 </p>
151
152 <pre>
153 jscoverage doc/example doc/instrumented
154 </pre>
155
156 <p>
157 This will create the directory <code>doc/instrumented/</code> and place an
158 instrumented copy of the code from <code>doc/example/</code> in
159 <code>doc/instrumented/</code>.
160 </p>
161
162 <table>
163 <tr>
164 <td><pre>
165 doc/example/
166 index.html
167 script.js
168
169 </pre></td>
170 <td class="arrow">&rarr;</td>
171 <td><pre>
172 doc/instrumented/
173 index.html
174 script.js [instrumented]
175 jscoverage.html
176 </pre></td>
177 </tr>
178 </table>
179
180 <h3>2. Executing the instrumented code in a web browser</h3>
181
182 <p>
183 Open the generated <code>jscoverage.html</code> file
184 (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
185 The page contains a tabbed user interface:
186 </p>
187
188 <ul>
189 <li>The "Browser" tab is used to display pages with instrumented scripts.
190 <li>The "Summary" tab is used to display code coverage data.
191 <li>The "Source" tab is used to display JavaScript code, showing the number of times
192 each line of code was executed.
193 <li>The "About" tab displays information about the current version of JSCoverage.
194 </ul>
195
196 <p><img src="screenshot.png" alt="Screenshot"></p>
197
198 <p>
199 The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
200 You can load a page into this frame by
201 entering its URL into the "URL" input field.
202 You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
203 or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
204 from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
205 server, will give unexpected results.
206 </p>
207
208 <p>
209 For example, you can load the file <code>doc/instrumented/index.html</code> by typing
210 <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
211 </p>
212
213 <p>
214 Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
215 appending the page URL to the query string of the <code>jscoverage.html</code> URL.
216 For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
217 will cause the <code>index.html</code> file to be loaded automatically.
218 </p>
219
220 <p><img src="screenshot2.png" alt="Screenshot"></p>
221
222 <p>
223 For this example, the JavaScript does not execute automatically:
224 you have to select one of the radio buttons to execute the code.
225 </p>
226
227 <p><img src="screenshot3.png" alt="Screenshot"></p>
228
229 <h3>3. Generating a coverage report</h3>
230
231 <p>
232 Once the JavaScript code in the page in the "Browser" tab has been executed, click on
233 the "Summary" tab. This will display the current code coverage statistics.
234 </p>
235
236 <p><img src="screenshot4.png" alt="Screenshot"></p>
237
238 <p>
239 You can click the checkbox to show a list of statements missed during execution.
240 </p>
241
242 <p><img src="screenshot5.png" alt="Screenshot"></p>
243
244 <p>
245 You can click one of the links to get a detailed view of a JavaScript source file.
246 </p>
247
248 <p><img src="screenshot6.png" alt="Screenshot"></p>
249
250 <p>
251 As long as you do not reload the
252 <code>jscoverage.html</code> page, the coverage report statistics are
253 cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
254 another scripted page, or by reloading the frame containing a scripted
255 page) and switch to the "Summary" tab again,
256 the coverage report will combine the statistics from the previous report with any newly generated statistics.
257 Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
258 </p>
259
260 <h2>Inverted mode</h2>
261
262 <p>
263 In some situations it may be difficult to execute your code within the
264 JSCoverage "Browser" tab. For example, the code may assume that it is running in
265 the top-level browser window, generating errors if it is executed from within a
266 frame. JSCoverage has an alternative mode of operation, called <dfn>inverted
267 mode</dfn>, which may be useful in this case.
268 </p>
269
270 <p>
271 Normally you load <code>jscoverage.html</code> in your web browser, and in its
272 "Browser" tab you launch your test code. In inverted mode, you do the
273 opposite: you load your test page directly in your web browser, and from there
274 you launch JSCoverage. To do this you need to add some code to your test page:
275 </p>
276
277 <pre class="sh_javascript">
278 window.open('path/to/jscoverage.html');
279 </pre>
280
281 <p>
282 The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
283 location of the <code>jscoverage.html</code> file (remember, this will be in the
284 top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
285 the <code>jscoverage</code> executable).
286 </p>
287
288 <p>
289 You can place this code wherever you like in your page: for example, you could
290 attach it to a button:
291 </p>
292
293 <pre class="sh_html">
294 &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
295 </pre>
296
297 <p>
298 Note that you <em>must</em> use a <code>window.open</code> call; simply making a
299 link to <code>jscoverage.html</code> is not sufficient.
300 </p>
301
302 <p>
303 An example is located in the <code>doc/example-inverted</code> directory.
304 You can instrument the code with the <code>jscoverage</code> program:
305 </p>
306
307 <pre>
308 jscoverage doc/example-inverted doc/instrumented-inverted
309 </pre>
310
311 <p>
312 You can load the page <code>doc/instrumented-inverted/index.html</code>
313 directly in your web browser.
314 From this page, you select one of the radio buttons and then click the "Coverage
315 report" button to launch the JSCoverage report.
316 </p>
317
318 <p>
319 Another example is located in the <code>doc/example-jsunit</code> directory.
320 See the <a href="faq.html#jsunit">FAQ</a> for more information.
321 </p>
322
323 <h2><code>jscoverage</code> command line options</h2>
324
325 <p>
326 The <code>jscoverage</code> program accepts the following options:
327 </p>
328
329 <dl>
330 <dt><code>-h</code>, <code>--help</code>
331 <dd>Display a brief help message.
332 <dt><code>-V</code>, <code>--version</code>
333 <dd>Display the version of the program.
334 <dt><code>-v</code>, <code>--verbose</code>
335 <dd>Explain what is being done.
336 <dt><code>--encoding=<var>ENCODING</var></code>
337 <dd>Assume that all JavaScript files use the given character encoding. The
338 default is ISO-8859-1.
339 <dt><code>--exclude=<var>PATH</var></code>
340 <dd>The command
341 <pre>
342 jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
343 </pre>
344 copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
345 recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
346 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
347 <var>PATH</var> can be a file or a directory (in which case the directory and
348 its entire contents are skipped). This option may be given multiple times.
349 <dt><code>--js-version=<var>VERSION</var></code>
350 <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
351 are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
352 or <code>ECMAv3</code> (the default).
353 <dt><code>--no-highlight</code>
354 <dd>Do not perform syntax highlighting of JavaScript code.
355 <dt><code>--no-instrument=<var>PATH</var></code>
356 <dd>The command
357 <pre>
358 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
359 </pre>
360 copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
361 recursively, but does not instrument any JavaScript code in
362 <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
363 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
364 (JavaScript) file or a directory (in which case any JavaScript files located
365 anywhere underneath the directory are not instrumented). This option may be
366 given multiple times.
367 </dl>
368
369 <h2>Query string options</h2>
370
371 <p>
372 When accessing <code>jscoverage.html</code> in a web browser, you may provide a
373 query string consisting of options separated by ampersand (<code>&amp;</code>)
374 or semicolon (<code>;</code>). Any option not containing an equals sign
375 (<code>=</code>) is considered to be a URL which will be loaded in the "Browser"
376 tab.
377 </p>
378
379 <dl>
380 <dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code>
381 <dd>Load <var>URL</var> in the "Browser" tab. (This is the same as specifying
382 an option without an equals sign.)
383 <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
384 <dd>Determines whether to initially display the "Missing" column in the "Summary"
385 tab. <var>BOOLEAN</var> can be
386 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
387 (to display the "Missing" column), or
388 <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
389 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
390 </dl>
391
392 <h2>Using the <code>jscoverage-server</code> program</h2>
393
394 <p>
395 The <code>jscoverage-server</code> program is a simple web server. You can use
396 <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
397 directory:
398 </p>
399
400 <pre>
401 cd doc/example
402 jscoverage-server --verbose
403 </pre>
404
405 <p>
406 Once the server is running, you can access the JSCoverage web interface by
407 visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
408 load the <code>doc/example/index.html</code> file by entering
409 <code>index.html</code> in the "URL" input field. (Or you can do this all in
410 one step by loading the URL
411 <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
412 browser.) The
413 <code>jscoverage-server</code> program automatically instruments any served
414 JavaScript code, so that code coverage data will be gathered as the code is
415 executed in your browser.
416 </p>
417
418 <p>
419 The web interface is slightly different from that generated by the
420 <code>jscoverage</code> program: it has a new tab named "Store".
421 To store coverage data, click the "Store" tab.
422 </p>
423
424 <p><img src="screenshot7.png" alt="Screenshot"></p>
425
426 <p>
427 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
428 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
429 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
430 </p>
431
432 <p>
433 If you use the "Store" tab again to store coverage data, the new data will be merged with
434 the previous data in the <code>jscoverage-report/</code> directory. This can be useful,
435 for instance, if you wish to run a set of tests in different browsers and generate an
436 aggregate report which combines the data for all of them.
437 </p>
438
439 <p>
440 You can stop the server by running another instance of <code>jscoverage-server</code> with the
441 <code>--shutdown</code> option:
442 </p>
443
444 <pre>
445 jscoverage-server --shutdown
446 </pre>
447
448 <h2>Using <code>jscoverage-server --proxy</code></h2>
449
450 <p>
451 To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
452 </p>
453
454 <pre>
455 jscoverage-server --verbose --proxy
456 </pre>
457
458 <p>
459 Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
460 You can then generate code coverage data for a web page on the server <code>example.com</code>
461 by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.
462 Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
463 by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
464 </p>
465
466 <h2><code>jscoverage-server</code> command line options</h2>
467
468 <dl>
469 <dt><code>-h</code>, <code>--help</code>
470 <dd>Display a brief help message.
471 <dt><code>-V</code>, <code>--version</code>
472 <dd>Display the version of the program.
473 <dt><code>-v</code>, <code>--verbose</code>
474 <dd>Explain what is being done.
475 <dt><code>--document-root=<var>PATH</var></code>
476 <dd>Serve web content from the directory given by <var>PATH</var>. The default is
477 the current directory. This option may not be given with the <code>--proxy</code> option.
478 <dt><code>--encoding=<var>ENCODING</var></code>
479 <dd>Assume that all JavaScript files use the given character encoding. The
480 default is ISO-8859-1. Note that if you use the <code>--proxy</code> option, the
481 character encoding will be determined from the <code>charset</code> parameter in
482 the <code>Content-Type</code> HTTP header.
483 <dt><code>--ip-address=<var>ADDRESS</var></code>
484 <dd>Run the server on the IP address given by <var>ADDRESS</var>. The default is <code>127.0.0.1</code>. Specify
485 <code>0.0.0.0</code> to use any address.
486 <dt><code>--js-version=<var>VERSION</var></code>
487 <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
488 are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
489 or <code>ECMAv3</code> (the default).
490 <dt><code>--no-highlight</code>
491 <dd>Do not perform syntax highlighting of JavaScript code.
492 <dt><code>--no-instrument=<var>URL</var></code>
493 <dd>Do not instrument JavaScript code from <var>URL</var>. If you are running <code>jscoverage-server</code>
494 with the <code>--proxy</code> option, <var>URL</var> should be a full URL. For example:
495 <pre>
496 jscoverage-server --proxy --no-instrument=http://example.com/scripts/
497 </pre>
498 Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
499 <pre>
500 jscoverage-server --no-instrument=/scripts/
501 </pre>
502 This option may be given multiple times.
503 <dt><code>--port=<var>PORT</var></code>
504 <dd>Run the server on the port given by <var>PORT</var>. The default is port 8080.
505 <dt><code>--proxy</code>
506 <dd>Run as a proxy server.
507 <dt><code>--report-dir=<var>PATH</var></code>
508 <dd>Use the directory given by <var>PATH</var> for storing coverage reports. The default is
509 <code>jscoverage-report/</code> in the current directory.
510 <dt><code>--shutdown</code>
511 <dd>Stop a running instance of the server.
512 </dl>
513
514 <h2>Advanced topics</h2>
515
516 <h3>Storing coverage reports programmatically</h3>
517
518 <p>
519 If you are executing a test suite using <code>jscoverage-server</code>, you can
520 store a coverage report programmatically by having your test suite call the
521 <code>jscoverage_report</code> function (automatically generated by
522 <code>jscoverage-server</code>) after all your tests have finished running:
523 </p>
524
525 <pre class="sh_javascript">
526 if (window.jscoverage_report) {
527 jscoverage_report();
528 }
529 </pre>
530
531 <p>
532 You can specify the name of the directory in which to store the report by
533 passing the name as a parameter to the <code>jscoverage_report</code> function:
534 </p>
535
536 <pre class="sh_javascript">
537 if (window.jscoverage_report) {
538 // determine the directory name based on the browser
539 var directory;
540 if (/MSIE/.test(navigator.userAgent)) {
541 directory = 'IE';
542 }
543 else {
544 directory = 'other';
545 }
546 jscoverage_report(directory);
547 }
548 </pre>
549
550 <p>
551 This directory will be a subdirectory under the <code>jscoverage-report/</code>
552 directory (or whatever is specified with the <code>--report-dir</code> option).
553 Using the above example, the report would be stored to either
554 <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
555 </p>
556
557 <p>
558 It is not necessary that your test suite be executed within the
559 <code>jscoverage.html</code> web interface to store a coverage report. The URL
560 of the test suite can simply be loaded directly in a web browser.
561 </p>
562
563 <p>
564 The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
565 reports programmatically.
566 </p>
567
568 <h3>Ignoring certain lines of code</h3>
569
570 <p>
571 Sometimes you may wish to exclude certain lines of code from coverage
572 statistics. Some lines of code may be executed only in certain browsers; other
573 lines should never be executed at all (they may be present only to detect
574 programming errors). You can use specially formatted comments in your code to
575 tell JSCoverage to ignore certain lines of code. These lines will not be
576 included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
577 be indicated with the color yellow.
578 </p>
579
580 <p>
581 These comments take the following form:
582 </p>
583
584 <pre class="sh_javascript">
585 //#JSCOVERAGE_IF <var>CONDITION</var>
586 ...
587 //#JSCOVERAGE_ENDIF
588 </pre>
589
590 <p>
591 The comment must be formatted exactly as shown: it must be a line comment
592 starting with <code>//</code>, it must start in the first column, and it must be
593 followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
594 uppercase letters with no intervening white space.
595 </p>
596
597 <p>
598 The <var>CONDITION</var> is an ordinary JavaScript expression; if this
599 expression evaluates to <code>true</code>, then the lines of code between the
600 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
601 included in coverage statistics; otherwise, they are excluded from coverage
602 statistics.
603 </p>
604
605 <p>
606 For example:
607 </p>
608
609 <pre class="sh_javascript">
610 function log(s) {
611 if (window.console) {
612 //#JSCOVERAGE_IF window.console
613 console.log(s);
614 //#JSCOVERAGE_ENDIF
615 }
616 }
617 </pre>
618
619 <p>
620 You can exclude code from coverage statistics unconditionally by using
621 <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
622 </p>
623
624 <pre class="sh_javascript">
625 function f(x) {
626 if (x === null) {
627 //#JSCOVERAGE_IF 0
628 throw 'error';
629 //#JSCOVERAGE_ENDIF
630 }
631 ...
632 </pre>
633
634 <p>
635 There is also a short form, which must appear on the line preceding an
636 <code>if</code> statement:
637 </p>
638
639 <pre class="sh_javascript">
640 //#JSCOVERAGE_IF
641 if (...) {
642 ...
643 }
644 else if (...) {
645 ...
646 }
647 ...
648 else {
649 ...
650 }
651 </pre>
652
653 <p>
654
655 In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
656 and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
657 that you expect only one branch of the <code>if</code> statement to be executed;
658 coverage statistics will not be collected for the other branch(es). For
659 example:
660 </p>
661
662 <pre class="sh_javascript">
663 function log(s) {
664 //#JSCOVERAGE_IF
665 if (window.console) {
666 console.log(s);
667 }
668 else if (window.opera) {
669 opera.postError(s);
670 }
671 else {
672 throw 'no logging function available';
673 }
674 }
675 </pre>
676
677 <p>
678 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
679 </p>
680
681 <h2>Caveats</h2>
682
683 <ul>
684 <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
685 Expect instrumented code to take at least twice as much time to run.
686 <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
687 elements in HTML files.
688 <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
689 the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
690 <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
691 that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
692 statements, you may get strange results.
693 <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
694 those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
695 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
696 </ul>
697
698 <address>
699 Copyright &copy; 2007, 2008 <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>
700 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
701 </address>
702
703 </body>
704 </html>

  ViewVC Help
Powered by ViewVC 1.1.24