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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 474 - (show annotations)
Sun Oct 4 05:35:23 2009 UTC (10 years, 2 months ago) by siliconforks
File MIME type: text/html
File size: 24055 byte(s)
Add type="button" to button element, or else it acts as though it were a submit button and submits the form it is in.

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

  ViewVC Help
Powered by ViewVC 1.1.24