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

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 427 - (hide annotations)
Wed Feb 18 16:08:33 2009 UTC (10 years, 9 months ago) by siliconforks
File MIME type: text/html
File size: 24041 byte(s)
Update Copyright year.
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 siliconforks 393 You can compile JSCoverage on GNU/Linux or Microsoft Windows, using the GCC C++ compiler (<code>g++</code>). On
46 siliconforks 2 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 siliconforks 414 In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
121     which is used to execute the instrumented code.
122 siliconforks 2 </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 siliconforks 414 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 siliconforks 2 </p>
148    
149 siliconforks 328 <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 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
178 siliconforks 2
179     <p>
180 siliconforks 328 Open the generated <code>jscoverage.html</code> file
181     (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
182 siliconforks 2 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 siliconforks 197 <p><img src="screenshot.png" alt="Screenshot"></p>
194 siliconforks 2
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 siliconforks 328 entering its URL into the "URL" input field.
199 siliconforks 64 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 siliconforks 2 </p>
204    
205     <p>
206 siliconforks 328 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 siliconforks 2 </p>
209    
210     <p>
211 siliconforks 328 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 siliconforks 2 </p>
216    
217 siliconforks 197 <p><img src="screenshot2.png" alt="Screenshot"></p>
218 siliconforks 2
219     <p>
220 siliconforks 328 For this example, the JavaScript does not execute automatically:
221 siliconforks 2 you have to select one of the radio buttons to execute the code.
222     </p>
223    
224 siliconforks 197 <p><img src="screenshot3.png" alt="Screenshot"></p>
225 siliconforks 2
226 siliconforks 115 <h3>3. Generating a coverage report</h3>
227 siliconforks 2
228     <p>
229 siliconforks 328 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 siliconforks 2 </p>
232    
233 siliconforks 197 <p><img src="screenshot4.png" alt="Screenshot"></p>
234 siliconforks 2
235     <p>
236 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
237 siliconforks 2 </p>
238    
239 siliconforks 197 <p><img src="screenshot5.png" alt="Screenshot"></p>
240 siliconforks 2
241 siliconforks 41 <p>
242     You can click one of the links to get a detailed view of a JavaScript source file.
243     </p>
244    
245 siliconforks 197 <p><img src="screenshot6.png" alt="Screenshot"></p>
246 siliconforks 41
247 siliconforks 328 <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 siliconforks 14 <h2>Inverted mode</h2>
258    
259     <p>
260 siliconforks 41 In some situations it may be difficult to execute your code within the
261 siliconforks 14 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 siliconforks 41 mode</dfn>, which may be useful in this case.
265 siliconforks 14 </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 siliconforks 198 <pre class="sh_javascript">
275     window.open('path/to/jscoverage.html');
276 siliconforks 14 </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 siliconforks 198 <pre class="sh_html">
291     &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
292 siliconforks 14 </pre>
293    
294     <p>
295 siliconforks 37 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 siliconforks 14 An example is located in the <code>doc/example-inverted</code> directory.
301 siliconforks 328 You can instrument the code with the <code>jscoverage</code> program:
302 siliconforks 14 </p>
303    
304     <pre>
305     jscoverage doc/example-inverted doc/instrumented-inverted
306     </pre>
307    
308     <p>
309 siliconforks 328 You can load the page <code>doc/instrumented-inverted/index.html</code>
310     directly in your web browser.
311 siliconforks 14 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 siliconforks 273 <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 siliconforks 115 <h2><code>jscoverage</code> command line options</h2>
321 siliconforks 19
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 siliconforks 207 <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 siliconforks 19 <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 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
344 siliconforks 19 <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 siliconforks 386 <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 siliconforks 207 <dt><code>--no-highlight</code>
351     <dd>Do not perform syntax highlighting of JavaScript code.
352 siliconforks 19 <dt><code>--no-instrument=<var>PATH</var></code>
353     <dd>The command
354     <pre>
355 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
356 siliconforks 19 </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 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
361 siliconforks 19 (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 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
384 siliconforks 19 (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 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
387 siliconforks 19 </dl>
388    
389 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
390    
391     <p>
392 siliconforks 198 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 siliconforks 115 </p>
396    
397     <pre>
398     cd doc/example
399     jscoverage-server --verbose
400     </pre>
401    
402     <p>
403 siliconforks 198 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 siliconforks 115 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 siliconforks 197 <p><img src="screenshot7.png" alt="Screenshot"></p>
422 siliconforks 115
423     <p>
424 siliconforks 326 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
425 siliconforks 115 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
426 siliconforks 198 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
427 siliconforks 115 </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 siliconforks 207 <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 siliconforks 115 <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 siliconforks 386 <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 siliconforks 207 <dt><code>--no-highlight</code>
488     <dd>Do not perform syntax highlighting of JavaScript code.
489 siliconforks 115 <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 siliconforks 158 <h2>Advanced topics</h2>
512    
513 siliconforks 198 <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 siliconforks 270 if (window.jscoverage_report) {
524     jscoverage_report();
525 siliconforks 198 }
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 siliconforks 270 if (window.jscoverage_report) {
535 siliconforks 198 // 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 siliconforks 270 jscoverage_report(directory);
544 siliconforks 198 }
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 siliconforks 201 <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 siliconforks 273 <p>
561     The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
562     reports programmatically.
563     </p>
564    
565 siliconforks 240 <h3>Ignoring certain lines of code</h3>
566 siliconforks 158
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 siliconforks 198 lines should never be executed at all (they may be present only to detect
571 siliconforks 240 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 siliconforks 158 </p>
576    
577     <p>
578 siliconforks 240 These comments take the following form:
579 siliconforks 158 </p>
580    
581     <pre class="sh_javascript">
582     //#JSCOVERAGE_IF <var>CONDITION</var>
583     ...
584     //#JSCOVERAGE_ENDIF
585     </pre>
586    
587     <p>
588 siliconforks 240 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 siliconforks 158 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 siliconforks 240 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
598 siliconforks 158 included in coverage statistics; otherwise, they are excluded from coverage
599     statistics.
600     </p>
601    
602     <p>
603 siliconforks 240 For example:
604 siliconforks 158 </p>
605    
606 siliconforks 240 <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 siliconforks 158 <p>
617 siliconforks 240 You can exclude code from coverage statistics unconditionally by using
618     <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
619 siliconforks 158 </p>
620    
621     <pre class="sh_javascript">
622 siliconforks 240 function f(x) {
623     if (x === null) {
624     //#JSCOVERAGE_IF 0
625     throw 'error';
626 siliconforks 158 //#JSCOVERAGE_ENDIF
627     }
628 siliconforks 240 ...
629 siliconforks 158 </pre>
630    
631     <p>
632 siliconforks 240 There is also a short form, which must appear on the line preceding an
633     <code>if</code> statement:
634 siliconforks 158 </p>
635    
636     <pre class="sh_javascript">
637 siliconforks 240 //#JSCOVERAGE_IF
638     if (...) {
639     ...
640     }
641     else if (...) {
642     ...
643     }
644     ...
645     else {
646     ...
647     }
648 siliconforks 158 </pre>
649    
650     <p>
651 siliconforks 240
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 siliconforks 158 </p>
658    
659     <pre class="sh_javascript">
660 siliconforks 240 function log(s) {
661     //#JSCOVERAGE_IF
662     if (window.console) {
663     console.log(s);
664 siliconforks 158 }
665 siliconforks 240 else if (window.opera) {
666     opera.postError(s);
667     }
668     else {
669     throw 'no logging function available';
670     }
671 siliconforks 158 }
672     </pre>
673    
674 siliconforks 201 <p>
675 siliconforks 240 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
676 siliconforks 201 </p>
677    
678 siliconforks 2 <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 siliconforks 198 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
693 siliconforks 2 </ul>
694    
695     <address>
696 siliconforks 427 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 siliconforks 2 <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