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

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 326 - (hide annotations)
Mon Oct 20 07:57:04 2008 UTC (11 years, 1 month ago) by siliconforks
File MIME type: text/html
File size: 23458 byte(s)
Update screenshots.
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     <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 siliconforks 2 </head>
11 siliconforks 198 <body onload="sh_highlightDocument();">
12 siliconforks 2
13     <h1>JSCoverage user manual</h1>
14    
15     <p>
16 siliconforks 198 JSCoverage is a tool that measures code coverage in 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 198 Using the <code>jscoverage</code> program involves the following steps:
82 siliconforks 2 </p>
83    
84     <h3>1. Instrumenting code</h3>
85    
86     <p>
87 siliconforks 115 The first step is to add instrumentation to your JavaScript code. You do this by
88     executing <code>jscoverage</code> with two arguments:
89 siliconforks 2 </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 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
140 siliconforks 2
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 siliconforks 197 <p><img src="screenshot.png" alt="Screenshot"></p>
155 siliconforks 2
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 siliconforks 64 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 siliconforks 2 </p>
167    
168 siliconforks 115 <h3>3. Generating a coverage report</h3>
169 siliconforks 2
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 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
209 siliconforks 2
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 siliconforks 197 <p><img src="screenshot2.png" alt="Screenshot"></p>
229 siliconforks 2
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 siliconforks 197 <p><img src="screenshot3.png" alt="Screenshot"></p>
236 siliconforks 2
237 siliconforks 115 <h3>3. Generating a coverage report</h3>
238 siliconforks 2
239     <p>
240 siliconforks 14 Once you have executed the JavaScript code, you are instructed to click on the
241 siliconforks 2 "Summary" tab.
242     </p>
243    
244 siliconforks 197 <p><img src="screenshot4.png" alt="Screenshot"></p>
245 siliconforks 2
246     <p>
247 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
248 siliconforks 2 </p>
249    
250 siliconforks 197 <p><img src="screenshot5.png" alt="Screenshot"></p>
251 siliconforks 2
252 siliconforks 41 <p>
253     You can click one of the links to get a detailed view of a JavaScript source file.
254     </p>
255    
256 siliconforks 197 <p><img src="screenshot6.png" alt="Screenshot"></p>
257 siliconforks 41
258 siliconforks 14 <h2>Inverted mode</h2>
259    
260     <p>
261 siliconforks 41 In some situations it may be difficult to execute your code within the
262 siliconforks 14 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 siliconforks 41 mode</dfn>, which may be useful in this case.
266 siliconforks 14 </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 siliconforks 198 <pre class="sh_javascript">
276     window.open('path/to/jscoverage.html');
277 siliconforks 14 </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 siliconforks 198 <pre class="sh_html">
292     &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
293 siliconforks 14 </pre>
294    
295     <p>
296 siliconforks 37 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 siliconforks 14 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 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 207 <dt><code>--no-highlight</code>
347     <dd>Do not perform syntax highlighting of JavaScript code.
348 siliconforks 19 <dt><code>--no-instrument=<var>PATH</var></code>
349     <dd>The command
350     <pre>
351 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
352 siliconforks 19 </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 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
357 siliconforks 19 (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 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
380 siliconforks 19 (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 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
383 siliconforks 19 </dl>
384    
385 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
386    
387     <p>
388 siliconforks 198 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 siliconforks 115 </p>
392    
393     <pre>
394     cd doc/example
395     jscoverage-server --verbose
396     </pre>
397    
398     <p>
399 siliconforks 198 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 siliconforks 115 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 siliconforks 197 <p><img src="screenshot7.png" alt="Screenshot"></p>
418 siliconforks 115
419     <p>
420 siliconforks 326 When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
421 siliconforks 115 You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
422 siliconforks 198 your web browser - you don't need the <code>jscoverage-server</code> running to access it.
423 siliconforks 115 </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 siliconforks 207 <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 siliconforks 115 <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 siliconforks 207 <dt><code>--no-highlight</code>
480     <dd>Do not perform syntax highlighting of JavaScript code.
481 siliconforks 115 <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 siliconforks 158 <h2>Advanced topics</h2>
504    
505 siliconforks 198 <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 siliconforks 270 if (window.jscoverage_report) {
516     jscoverage_report();
517 siliconforks 198 }
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 siliconforks 270 if (window.jscoverage_report) {
527 siliconforks 198 // 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 siliconforks 270 jscoverage_report(directory);
536 siliconforks 198 }
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 siliconforks 201 <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 siliconforks 273 <p>
553     The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
554     reports programmatically.
555     </p>
556    
557 siliconforks 240 <h3>Ignoring certain lines of code</h3>
558 siliconforks 158
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 siliconforks 198 lines should never be executed at all (they may be present only to detect
563 siliconforks 240 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 siliconforks 158 </p>
568    
569     <p>
570 siliconforks 240 These comments take the following form:
571 siliconforks 158 </p>
572    
573     <pre class="sh_javascript">
574     //#JSCOVERAGE_IF <var>CONDITION</var>
575     ...
576     //#JSCOVERAGE_ENDIF
577     </pre>
578    
579     <p>
580 siliconforks 240 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 siliconforks 158 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 siliconforks 240 <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
590 siliconforks 158 included in coverage statistics; otherwise, they are excluded from coverage
591     statistics.
592     </p>
593    
594     <p>
595 siliconforks 240 For example:
596 siliconforks 158 </p>
597    
598 siliconforks 240 <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 siliconforks 158 <p>
609 siliconforks 240 You can exclude code from coverage statistics unconditionally by using
610     <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
611 siliconforks 158 </p>
612    
613     <pre class="sh_javascript">
614 siliconforks 240 function f(x) {
615     if (x === null) {
616     //#JSCOVERAGE_IF 0
617     throw 'error';
618 siliconforks 158 //#JSCOVERAGE_ENDIF
619     }
620 siliconforks 240 ...
621 siliconforks 158 </pre>
622    
623     <p>
624 siliconforks 240 There is also a short form, which must appear on the line preceding an
625     <code>if</code> statement:
626 siliconforks 158 </p>
627    
628     <pre class="sh_javascript">
629 siliconforks 240 //#JSCOVERAGE_IF
630     if (...) {
631     ...
632     }
633     else if (...) {
634     ...
635     }
636     ...
637     else {
638     ...
639     }
640 siliconforks 158 </pre>
641    
642     <p>
643 siliconforks 240
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 siliconforks 158 </p>
650    
651     <pre class="sh_javascript">
652 siliconforks 240 function log(s) {
653     //#JSCOVERAGE_IF
654     if (window.console) {
655     console.log(s);
656 siliconforks 158 }
657 siliconforks 240 else if (window.opera) {
658     opera.postError(s);
659     }
660     else {
661     throw 'no logging function available';
662     }
663 siliconforks 158 }
664     </pre>
665    
666 siliconforks 201 <p>
667 siliconforks 240 Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
668 siliconforks 201 </p>
669    
670 siliconforks 2 <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 siliconforks 198 <li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details.
685 siliconforks 2 </ul>
686    
687     <address>
688 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>
689 siliconforks 2 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
690     </address>
691    
692     </body>
693     </html>

  ViewVC Help
Powered by ViewVC 1.1.24