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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.24