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

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 386 - (hide annotations)
Thu Oct 30 03:13:46 2008 UTC (12 years, 1 month ago) by siliconforks
File MIME type: text/html
File size: 23998 byte(s)
Document the --js-version option.
1 siliconforks 197 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2 siliconforks 2 <html>
3     <head>
4     <title>JSCoverage user manual</title>
5 siliconforks 198 <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
6     <link rel="stylesheet" type="text/css" href="doc.css">
7 siliconforks 328 <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 siliconforks 2 </head>
11 siliconforks 198 <body onload="sh_highlightDocument();">
12 siliconforks 2
13     <h1>JSCoverage user manual</h1>
14    
15     <p>
16 siliconforks 328 JSCoverage is a tool that measures code coverage for JavaScript programs.
17 siliconforks 2 </p>
18    
19     <p>
20 siliconforks 115 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 siliconforks 2 </p>
24    
25 siliconforks 115 <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 siliconforks 2
37 siliconforks 115 <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 siliconforks 225 <h2>Compiling JSCoverage</h2>
43 siliconforks 2
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 siliconforks 115 tar jxvf jscoverage-0.4.tar.bz2
56     cd jscoverage-0.4/
57 siliconforks 2 ./configure
58     make
59     </pre>
60    
61     <p>
62 siliconforks 115 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 siliconforks 2 </p>
67    
68     <pre>
69     make install
70     </pre>
71    
72     <p>
73 siliconforks 115 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 siliconforks 2 </p>
77    
78 siliconforks 115 <h2>Using the <code>jscoverage</code> program</h2>
79 siliconforks 2
80     <p>
81 siliconforks 328 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 siliconforks 2 </p>
86    
87 siliconforks 328 <p>
88     Generating code coverage statistics for this example using the
89     <code>jscoverage</code> program involves the following steps:
90     </p>
91    
92 siliconforks 2 <h3>1. Instrumenting code</h3>
93    
94     <p>
95 siliconforks 115 The first step is to add instrumentation to your JavaScript code. You do this by
96     executing <code>jscoverage</code> with two arguments:
97 siliconforks 2 </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 siliconforks 328 The directory structure under <var>SOURCE-DIRECTORY</var> is preserved, so that if you have a file
114 siliconforks 2 <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 siliconforks 328 <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 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
181 siliconforks 2
182     <p>
183 siliconforks 328 Open the generated <code>jscoverage.html</code> file
184     (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
185 siliconforks 2 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 siliconforks 197 <p><img src="screenshot.png" alt="Screenshot"></p>
197 siliconforks 2
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 siliconforks 328 entering its URL into the "URL" input field.
202 siliconforks 64 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 siliconforks 2 </p>
207    
208     <p>
209 siliconforks 328 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 siliconforks 2 </p>
212    
213     <p>
214 siliconforks 328 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 siliconforks 2 </p>
219    
220 siliconforks 197 <p><img src="screenshot2.png" alt="Screenshot"></p>
221 siliconforks 2
222     <p>
223 siliconforks 328 For this example, the JavaScript does not execute automatically:
224 siliconforks 2 you have to select one of the radio buttons to execute the code.
225     </p>
226    
227 siliconforks 197 <p><img src="screenshot3.png" alt="Screenshot"></p>
228 siliconforks 2
229 siliconforks 115 <h3>3. Generating a coverage report</h3>
230 siliconforks 2
231     <p>
232 siliconforks 328 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 siliconforks 2 </p>
235    
236 siliconforks 197 <p><img src="screenshot4.png" alt="Screenshot"></p>
237 siliconforks 2
238     <p>
239 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
240 siliconforks 2 </p>
241    
242 siliconforks 197 <p><img src="screenshot5.png" alt="Screenshot"></p>
243 siliconforks 2
244 siliconforks 41 <p>
245     You can click one of the links to get a detailed view of a JavaScript source file.
246     </p>
247    
248 siliconforks 197 <p><img src="screenshot6.png" alt="Screenshot"></p>
249 siliconforks 41
250 siliconforks 328 <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 siliconforks 14 <h2>Inverted mode</h2>
261    
262     <p>
263 siliconforks 41 In some situations it may be difficult to execute your code within the
264 siliconforks 14 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 siliconforks 41 mode</dfn>, which may be useful in this case.
268 siliconforks 14 </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 siliconforks 198 <pre class="sh_javascript">
278     window.open('path/to/jscoverage.html');
279 siliconforks 14 </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 siliconforks 198 <pre class="sh_html">
294     &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
295 siliconforks 14 </pre>
296    
297     <p>
298 siliconforks 37 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 siliconforks 14 An example is located in the <code>doc/example-inverted</code> directory.
304 siliconforks 328 You can instrument the code with the <code>jscoverage</code> program:
305 siliconforks 14 </p>
306    
307     <pre>
308     jscoverage doc/example-inverted doc/instrumented-inverted
309     </pre>
310    
311     <p>
312 siliconforks 328 You can load the page <code>doc/instrumented-inverted/index.html</code>
313     directly in your web browser.
314 siliconforks 14 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 siliconforks 273 <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 siliconforks 115 <h2><code>jscoverage</code> command line options</h2>
324 siliconforks 19
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 siliconforks 207 <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 siliconforks 19 <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 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
347 siliconforks 19 <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 siliconforks 386 <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 siliconforks 207 <dt><code>--no-highlight</code>
354     <dd>Do not perform syntax highlighting of JavaScript code.
355 siliconforks 19 <dt><code>--no-instrument=<var>PATH</var></code>
356     <dd>The command
357     <pre>
358 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
359 siliconforks 19 </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 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
364 siliconforks 19 (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 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
387 siliconforks 19 (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 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
390 siliconforks 19 </dl>
391    
392 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
393    
394     <p>
395 siliconforks 198 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 siliconforks 115 </p>
399    
400     <pre>
401     cd doc/example
402     jscoverage-server --verbose
403     </pre>
404    
405     <p>
406 siliconforks 198 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 siliconforks 115 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 siliconforks 197 <p><img src="screenshot7.png" alt="Screenshot"></p>
425 siliconforks 115
426     <p>
427 siliconforks 326 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
428 siliconforks 115 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
429 siliconforks 198 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
430 siliconforks 115 </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 siliconforks 207 <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 siliconforks 115 <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 siliconforks 386 <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 siliconforks 207 <dt><code>--no-highlight</code>
491     <dd>Do not perform syntax highlighting of JavaScript code.
492 siliconforks 115 <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 siliconforks 158 <h2>Advanced topics</h2>
515    
516 siliconforks 198 <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 siliconforks 270 if (window.jscoverage_report) {
527     jscoverage_report();
528 siliconforks 198 }
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 siliconforks 270 if (window.jscoverage_report) {
538 siliconforks 198 // 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 siliconforks 270 jscoverage_report(directory);
547 siliconforks 198 }
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 siliconforks 201 <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 siliconforks 273 <p>
564     The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
565     reports programmatically.
566     </p>
567    
568 siliconforks 240 <h3>Ignoring certain lines of code</h3>
569 siliconforks 158
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 siliconforks 198 lines should never be executed at all (they may be present only to detect
574 siliconforks 240 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 siliconforks 158 </p>
579    
580     <p>
581 siliconforks 240 These comments take the following form:
582 siliconforks 158 </p>
583    
584     <pre class="sh_javascript">
585     //#JSCOVERAGE_IF <var>CONDITION</var>
586     ...
587     //#JSCOVERAGE_ENDIF
588     </pre>
589    
590     <p>
591 siliconforks 240 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 siliconforks 158 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 siliconforks 240 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
601 siliconforks 158 included in coverage statistics; otherwise, they are excluded from coverage
602     statistics.
603     </p>
604    
605     <p>
606 siliconforks 240 For example:
607 siliconforks 158 </p>
608    
609 siliconforks 240 <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 siliconforks 158 <p>
620 siliconforks 240 You can exclude code from coverage statistics unconditionally by using
621     <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
622 siliconforks 158 </p>
623    
624     <pre class="sh_javascript">
625 siliconforks 240 function f(x) {
626     if (x === null) {
627     //#JSCOVERAGE_IF 0
628     throw 'error';
629 siliconforks 158 //#JSCOVERAGE_ENDIF
630     }
631 siliconforks 240 ...
632 siliconforks 158 </pre>
633    
634     <p>
635 siliconforks 240 There is also a short form, which must appear on the line preceding an
636     <code>if</code> statement:
637 siliconforks 158 </p>
638    
639     <pre class="sh_javascript">
640 siliconforks 240 //#JSCOVERAGE_IF
641     if (...) {
642     ...
643     }
644     else if (...) {
645     ...
646     }
647     ...
648     else {
649     ...
650     }
651 siliconforks 158 </pre>
652    
653     <p>
654 siliconforks 240
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 siliconforks 158 </p>
661    
662     <pre class="sh_javascript">
663 siliconforks 240 function log(s) {
664     //#JSCOVERAGE_IF
665     if (window.console) {
666     console.log(s);
667 siliconforks 158 }
668 siliconforks 240 else if (window.opera) {
669     opera.postError(s);
670     }
671     else {
672     throw 'no logging function available';
673     }
674 siliconforks 158 }
675     </pre>
676    
677 siliconforks 201 <p>
678 siliconforks 240 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
679 siliconforks 201 </p>
680    
681 siliconforks 2 <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 siliconforks 198 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
696 siliconforks 2 </ul>
697    
698     <address>
699 siliconforks 147 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 siliconforks 2 <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