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

Diff of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 41 by siliconforks, Wed Aug 22 18:46:11 2007 UTC revision 328 by siliconforks, Wed Oct 22 09:40:53 2008 UTC
# Line 1  Line 1 
1  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2  <html>  <html>
3  <head>  <head>
4  <title>JSCoverage user manual</title>  <title>JSCoverage user manual</title>
5  <link type="text/css" href="doc.css" rel="stylesheet">  <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
6    <link rel="stylesheet" type="text/css" href="doc.css">
7    <script type="text/javascript" src="sh_main.min.js"></script>
8    <script type="text/javascript" src="sh_html.min.js"></script>
9    <script type="text/javascript" src="sh_javascript.min.js"></script>
10  </head>  </head>
11  <body>  <body onload="sh_highlightDocument();">
12    
13  <h1>JSCoverage user manual</h1>  <h1>JSCoverage user manual</h1>
14    
15  <p>  <p>
16  JSCoverage is a tool used to measure code coverage in JavaScript  JSCoverage is a tool that measures code coverage for JavaScript programs.
 programs.  
17  </p>  </p>
18    
19  <p>  <p>
20  JSCoverage has two components:  JSCoverage works by adding instrumentation to JavaScript code before it is
21    executed in a web browser.  JSCoverage provides several alternative ways of doing
22    this:
23  </p>  </p>
24    
25  <ol>  <ul>
26  <li>An executable program which is used to add instrumentation to JavaScript code.  <li>The simplest method is to use the <code>jscoverage</code> program to generate
27  <li>A web application which is used to execute instrumented code and generate a  instrumented JavaScript files.
28  code coverage report.  </li>
29  </ol>  <li>Alternatively, you can use the <code>jscoverage-server</code> program, a simple web server that instruments
30    JavaScript code as it is served.
31    </li>
32    <li>Finally, <code>jscoverage-server</code> can be run with the <code>--proxy</code> option to
33    act as a proxy server which instruments any JavaScript code proxied through it.
34    </li>
35    </ul>
36    
37    <p>
38    The <code>jscoverage-server</code> program (with or without the <code>--proxy</code>
39    option) has the advantage of being able to store coverage reports to the filesystem.
40    </p>
41    
42  <h2>Installing JSCoverage</h2>  <h2>Compiling JSCoverage</h2>
43    
44  <p>  <p>
45  You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On  You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On
# Line 36  Line 52 
52  </p>  </p>
53    
54  <pre>  <pre>
55  tar jxvf jscoverage-0.3.tar.bz2  tar jxvf jscoverage-0.4.tar.bz2
56  cd jscoverage-0.3/  cd jscoverage-0.4/
57  ./configure  ./configure
58  make  make
59  </pre>  </pre>
60    
61  <p>  <p>
62  This will create the <code>jscoverage</code> executable (<code>jscoverage.exe</code> on Windows).  This will create the <code>jscoverage</code> and <code>jscoverage-server</code>
63  You can install the executable in <code>/usr/local</code> with the command:  executables (<code>jscoverage.exe</code> and <code>jscoverage-server.exe</code>
64    on Windows). You can install the executables in <code>/usr/local</code> with the
65    command:
66  </p>  </p>
67    
68  <pre>  <pre>
# Line 52  Line 70 
70  </pre>  </pre>
71    
72  <p>  <p>
73  Alternatively, since the program consists of only the single self-contained  Alternatively, you may simply copy the <code>jscoverage</code> executable and/or
74  <code>jscoverage</code> executable, you may simply copy it to a suitable location  the <code>jscoverage-server</code> executable to a suitable location in your
75  in your <code>PATH</code>.  <code>PATH</code>.
76  </p>  </p>
77    
78  <h2>Using JSCoverage</h2>  <h2>Using the <code>jscoverage</code> program</h2>
79    
80    <p>
81    To demonstrate how the <code>jscoverage</code> program works, we will use the
82    trivial example JavaScript code located in the
83    <code>doc/example/</code> directory of the JSCoverage distribution.  You can run
84    this example by viewing the file <code>doc/example/index.html</code> in your web browser.
85    </p>
86    
87  <p>  <p>
88  Using JSCoverage requires three steps:  Generating code coverage statistics for this example using the
89    <code>jscoverage</code> program involves the following steps:
90  </p>  </p>
91    
92  <h3>1. Instrumenting code</h3>  <h3>1. Instrumenting code</h3>
93    
94  <p>  <p>
95  The first step is to add instrumentation to your JavaScript code.  This is the function of the  The first step is to add instrumentation to your JavaScript code.  You do this by
96  <code>jscoverage</code> executable.  You must provide two arguments:  executing <code>jscoverage</code> with two arguments:
97  </p>  </p>
98    
99  <pre>  <pre>
# Line 84  Line 110 
110  </p>  </p>
111    
112  <p>  <p>
113  For example, if you have a file  The directory structure under <var>SOURCE-DIRECTORY</var> is preserved, so that if you have a file
114  <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script  <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
115  <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then  <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
116  <code>jscoverage</code> will create a copy of the HTML file at  <code>jscoverage</code> will create a copy of the HTML file at
# Line 118  Line 144 
144  which is used to execute the instrumented code.  which is used to execute the instrumented code.
145  </p>  </p>
146    
147  <h3>2. Running instrumented code in the web application</h3>  <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    <h3>2. Executing the instrumented code in a web browser</h3>
181    
182  <p>  <p>
183  Open <code>jscoverage.html</code> in your web browser.  Open the generated <code>jscoverage.html</code> file
184    (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
185  The page contains a tabbed user interface:  The page contains a tabbed user interface:
186  </p>  </p>
187    
# Line 133  Line 193 
193  <li>The "About" tab displays information about the current version of JSCoverage.  <li>The "About" tab displays information about the current version of JSCoverage.
194  </ul>  </ul>
195    
196  <img src="screenshot.png" alt="Screenshot">  <p><img src="screenshot.png" alt="Screenshot"></p>
197    
198  <p>  <p>
199  The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.  The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
200  You can load a page into this frame by  You can load a page into this frame by
201  entering its URL into the "URL" input field.  For example, to load  entering its URL into the "URL" input field.
202  the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can  You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
203  enter the relative URL <code>dir/index.html</code> into the input field.  or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
204  </p>  from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
205    server, will give unexpected results.
 <h3>3. Generating the coverage report</h3>  
   
 <p>  
 Once the JavaScript code in the page in the "Browser" tab has been executed, click on  
 the "Summary" tab.  This will display the current code coverage statistics.  
 </p>  
   
 <p>  
 As long as you do not reload the  
 <code>jscoverage.html</code> page, the coverage report statistics are  
 cumulative.  If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to  
 another scripted page, or by reloading the frame containing a scripted  
 page) and switch to the "Summary" tab again,  
 the coverage report will combine the statistics from the previous report with any newly generated statistics.  
 Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.  
 </p>  
   
 <h2>Example</h2>  
   
 <p>  
 The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.  
 You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.  
 To instrument this program, follow these steps:  
 </p>  
   
 <h3>1. Instrumenting code</h3>  
   
 <p>  
 From the main distribution directory, execute the command:  
 </p>  
   
 <pre>  
 jscoverage doc/example doc/instrumented  
 </pre>  
   
 <p>  
 This will create the directory <code>doc/instrumented</code> and  
 place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.  
206  </p>  </p>
207    
 <h3>2. Executing instrumented code</h3>  
   
208  <p>  <p>
209  You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type  For example, you can load the file <code>doc/instrumented/index.html</code> by typing
210  the URL for the instrumented code in the "URL" input field.  Since a relative URL is accepted, you  <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
 can simply type <code>index.html</code> to load the page.  
211  </p>  </p>
212    
213  <p>  <p>
214  Alternatively, you can append the URL to the query string of the  Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
215  <code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage  appending the page URL to the query string of the <code>jscoverage.html</code> URL.
216  directory and the Firefox executable is in your <code>PATH</code>, you can load  For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
217  the <code>jscoverage.html</code> frameset and the <code>index.html</code> page  will cause the <code>index.html</code> file to be loaded automatically.
 all in one command line:  
218  </p>  </p>
219    
220  <pre>  <p><img src="screenshot2.png" alt="Screenshot"></p>
 firefox "doc/instrumented/jscoverage.html?index.html"  
 </pre>  
   
 <img src="screenshot2.png" alt="Screenshot">  
221    
222  <p>  <p>
223  For this particular page, the JavaScript does not execute automatically:  For this example, the JavaScript does not execute automatically:
224  you have to select one of the radio buttons to execute the code.  you have to select one of the radio buttons to execute the code.
225  </p>  </p>
226    
227  <img src="screenshot3.png" alt="Screenshot">  <p><img src="screenshot3.png" alt="Screenshot"></p>
228    
229  <h3>3. Generating the coverage report</h3>  <h3>3. Generating a coverage report</h3>
230    
231  <p>  <p>
232  Once you have executed the JavaScript code, you are instructed to click on the  Once the JavaScript code in the page in the "Browser" tab has been executed, click on
233  "Summary" tab.  the "Summary" tab.  This will display the current code coverage statistics.
234  </p>  </p>
235    
236  <img src="screenshot4.png" alt="Screenshot">  <p><img src="screenshot4.png" alt="Screenshot"></p>
237    
238  <p>  <p>
239  You can click the checkbox to show a list of statements missed during execution.  You can click the checkbox to show a list of statements missed during execution.
240  </p>  </p>
241    
242  <img src="screenshot5.png" alt="Screenshot">  <p><img src="screenshot5.png" alt="Screenshot"></p>
243    
244  <p>  <p>
245  You can click one of the links to get a detailed view of a JavaScript source file.  You can click one of the links to get a detailed view of a JavaScript source file.
246  </p>  </p>
247    
248  <img src="screenshot6.png" alt="Screenshot">  <p><img src="screenshot6.png" alt="Screenshot"></p>
249    
250    <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  <h2>Inverted mode</h2>  <h2>Inverted mode</h2>
261    
# Line 250  Line 274 
274  you launch JSCoverage. To do this you need to add some code to your test page:  you launch JSCoverage. To do this you need to add some code to your test page:
275  </p>  </p>
276    
277  <pre>  <pre class="sh_javascript">
278  window.open("path/to/jscoverage.html");  window.open('path/to/jscoverage.html');
279  </pre>  </pre>
280    
281  <p>  <p>
# Line 266  Line 290 
290  attach it to a button:  attach it to a button:
291  </p>  </p>
292    
293  <pre>  <pre class="sh_html">
294  &lt;button onclick='window.open("path/to/jscoverage.html");'&gt;Coverage report&lt;/button&gt;  &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
295  </pre>  </pre>
296    
297  <p>  <p>
# Line 277  Line 301 
301    
302  <p>  <p>
303  An example is located in the <code>doc/example-inverted</code> directory.  An example is located in the <code>doc/example-inverted</code> directory.
304  You can instrument the code and launch the <code>index.html</code> page:  You can instrument the code with the <code>jscoverage</code> program:
305  </p>  </p>
306    
307  <pre>  <pre>
308  jscoverage doc/example-inverted doc/instrumented-inverted  jscoverage doc/example-inverted doc/instrumented-inverted
 firefox "doc/instrumented-inverted/index.html"  
309  </pre>  </pre>
310    
311  <p>  <p>
312    You can load the page <code>doc/instrumented-inverted/index.html</code>
313    directly in your web browser.
314  From this page, you select one of the radio buttons and then click the "Coverage  From this page, you select one of the radio buttons and then click the "Coverage
315  report" button to launch the JSCoverage report.  report" button to launch the JSCoverage report.
316  </p>  </p>
317    
318  <h2>Command line options</h2>  <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    <h2><code>jscoverage</code> command line options</h2>
324    
325  <p>  <p>
326  The <code>jscoverage</code> program accepts the following options:  The <code>jscoverage</code> program accepts the following options:
# Line 303  Line 333 
333  <dd>Display the version of the program.  <dd>Display the version of the program.
334  <dt><code>-v</code>, <code>--verbose</code>  <dt><code>-v</code>, <code>--verbose</code>
335  <dd>Explain what is being done.  <dd>Explain what is being done.
336    <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  <dt><code>--exclude=<var>PATH</var></code>  <dt><code>--exclude=<var>PATH</var></code>
340  <dd>The command  <dd>The command
341  <pre>  <pre>
# Line 313  Line 346 
346  <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.  <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
347  <var>PATH</var> can be a file or a directory (in which case the directory and  <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.  its entire contents are skipped). This option may be given multiple times.
349    <dt><code>--no-highlight</code>
350    <dd>Do not perform syntax highlighting of JavaScript code.
351  <dt><code>--no-instrument=<var>PATH</var></code>  <dt><code>--no-instrument=<var>PATH</var></code>
352  <dd>The command  <dd>The command
353  <pre>  <pre>
# Line 321  Line 356 
356  copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>  copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
357  recursively, but does not instrument any JavaScript code in  recursively, but does not instrument any JavaScript code in
358  <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete  <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
359  path relative to <var>SOURCE-DIRECTORY</var> <var>PATH</var> can be a  path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
360  (JavaScript) file or a directory (in which case any JavaScript files located  (JavaScript) file or a directory (in which case any JavaScript files located
361  anywhere underneath the directory are not instrumented). This option may be  anywhere underneath the directory are not instrumented). This option may be
362  given multiple times.  given multiple times.
# Line 344  Line 379 
379  <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>  <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
380  <dd>Determines whether to initially display the "Missing" column in the "Summary"  <dd>Determines whether to initially display the "Missing" column in the "Summary"
381  tab.  <var>BOOLEAN</var> can be  tab.  <var>BOOLEAN</var> can be
382  <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code> <code>on</code>, <code>1</code>  <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
383  (to display the "Missing" column), or  (to display the "Missing" column), or
384  <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>  <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
385  (to hide the "Missing" column).  By default, the "Missing" column is not displayed.  (to hide the "Missing" column).  By default, the "Missing" column is not displayed.
386  </dl>  </dl>
387    
388    <h2>Using the <code>jscoverage-server</code> program</h2>
389    
390    <p>
391    The <code>jscoverage-server</code> program is a simple web server. You can use
392    <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
393    directory:
394    </p>
395    
396    <pre>
397      cd doc/example
398      jscoverage-server --verbose
399    </pre>
400    
401    <p>
402    Once the server is running, you can access the JSCoverage web interface by
403    visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
404    load the <code>doc/example/index.html</code> file by entering
405    <code>index.html</code> in the "URL" input field.  (Or you can do this all in
406    one step by loading the URL
407    <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
408    browser.)  The
409    <code>jscoverage-server</code> program automatically instruments any served
410    JavaScript code, so that code coverage data will be gathered as the code is
411    executed in your browser.
412    </p>
413    
414    <p>
415    The web interface is slightly different from that generated by the
416    <code>jscoverage</code> program: it has a new tab named "Store".
417    To store coverage data, click the "Store" tab.
418    </p>
419    
420    <p><img src="screenshot7.png" alt="Screenshot"></p>
421    
422    <p>
423    When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
424    You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
425    your web browser - you don't need the <code>jscoverage-server</code> running to access it.
426    </p>
427    
428    <p>
429    If you use the "Store" tab again to store coverage data, the new data will be merged with
430    the previous data in the <code>jscoverage-report/</code> directory.  This can be useful,
431    for instance, if you wish to run a set of tests in different browsers and generate an
432    aggregate report which combines the data for all of them.
433    </p>
434    
435    <p>
436    You can stop the server by running another instance of <code>jscoverage-server</code> with the
437    <code>--shutdown</code> option:
438    </p>
439    
440    <pre>
441      jscoverage-server --shutdown
442    </pre>
443    
444    <h2>Using <code>jscoverage-server --proxy</code></h2>
445    
446    <p>
447    To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
448    </p>
449    
450    <pre>
451      jscoverage-server --verbose --proxy
452    </pre>
453    
454    <p>
455    Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
456    You can then generate code coverage data for a web page on the server <code>example.com</code>
457    by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.  
458    Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
459    by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
460    </p>
461    
462    <h2><code>jscoverage-server</code> command line options</h2>
463    
464    <dl>
465    <dt><code>-h</code>, <code>--help</code>
466    <dd>Display a brief help message.
467    <dt><code>-V</code>, <code>--version</code>
468    <dd>Display the version of the program.
469    <dt><code>-v</code>, <code>--verbose</code>
470    <dd>Explain what is being done.
471    <dt><code>--document-root=<var>PATH</var></code>
472    <dd>Serve web content from the directory given by <var>PATH</var>.  The default is
473    the current directory.  This option may not be given with the <code>--proxy</code> option.
474    <dt><code>--encoding=<var>ENCODING</var></code>
475    <dd>Assume that all JavaScript files use the given character encoding.  The
476    default is ISO-8859-1.  Note that if you use the <code>--proxy</code> option, the
477    character encoding will be determined from the <code>charset</code> parameter in
478    the <code>Content-Type</code> HTTP header.
479    <dt><code>--ip-address=<var>ADDRESS</var></code>
480    <dd>Run the server on the IP address given by <var>ADDRESS</var>.  The default is <code>127.0.0.1</code>.  Specify
481    <code>0.0.0.0</code> to use any address.
482    <dt><code>--no-highlight</code>
483    <dd>Do not perform syntax highlighting of JavaScript code.
484    <dt><code>--no-instrument=<var>URL</var></code>
485    <dd>Do not instrument JavaScript code from <var>URL</var>.  If you are running <code>jscoverage-server</code>
486    with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:
487    <pre>
488    jscoverage-server --proxy --no-instrument=http://example.com/scripts/
489    </pre>
490    Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
491    <pre>
492    jscoverage-server --no-instrument=/scripts/
493    </pre>
494    This option may be given multiple times.
495    <dt><code>--port=<var>PORT</var></code>
496    <dd>Run the server on the port given by <var>PORT</var>.  The default is port 8080.
497    <dt><code>--proxy</code>
498    <dd>Run as a proxy server.
499    <dt><code>--report-dir=<var>PATH</var></code>
500    <dd>Use the directory given by <var>PATH</var> for storing coverage reports.  The default is
501    <code>jscoverage-report/</code> in the current directory.
502    <dt><code>--shutdown</code>
503    <dd>Stop a running instance of the server.
504    </dl>
505    
506    <h2>Advanced topics</h2>
507    
508    <h3>Storing coverage reports programmatically</h3>
509    
510    <p>
511    If you are executing a test suite using <code>jscoverage-server</code>, you can
512    store a coverage report programmatically by having your test suite call the
513    <code>jscoverage_report</code> function (automatically generated by
514    <code>jscoverage-server</code>) after all your tests have finished running:
515    </p>
516    
517    <pre class="sh_javascript">
518    if (window.jscoverage_report) {
519      jscoverage_report();
520    }
521    </pre>
522    
523    <p>
524    You can specify the name of the directory in which to store the report by
525    passing the name as a parameter to the <code>jscoverage_report</code> function:
526    </p>
527    
528    <pre class="sh_javascript">
529    if (window.jscoverage_report) {
530      // determine the directory name based on the browser
531      var directory;
532      if (/MSIE/.test(navigator.userAgent)) {
533        directory = 'IE';
534      }
535      else {
536        directory = 'other';
537      }
538      jscoverage_report(directory);
539    }
540    </pre>
541    
542    <p>
543    This directory will be a subdirectory under the <code>jscoverage-report/</code>
544    directory (or whatever is specified with the <code>--report-dir</code> option).
545    Using the above example, the report would be stored to either
546    <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
547    </p>
548    
549    <p>
550    It is not necessary that your test suite be executed within the
551    <code>jscoverage.html</code> web interface to store a coverage report.  The URL
552    of the test suite can simply be loaded directly in a web browser.
553    </p>
554    
555    <p>
556    The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
557    reports programmatically.
558    </p>
559    
560    <h3>Ignoring certain lines of code</h3>
561    
562    <p>
563    Sometimes you may wish to exclude certain lines of code from coverage
564    statistics. Some lines of code may be executed only in certain browsers; other
565    lines should never be executed at all (they may be present only to detect
566    programming errors).  You can use specially formatted comments in your code to
567    tell JSCoverage to ignore certain lines of code. These lines will not be
568    included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
569    be indicated with the color yellow.
570    </p>
571    
572    <p>
573    These comments take the following form:
574    </p>
575    
576    <pre class="sh_javascript">
577    //#JSCOVERAGE_IF <var>CONDITION</var>
578    ...
579    //#JSCOVERAGE_ENDIF
580    </pre>
581    
582    <p>
583    The comment must be formatted exactly as shown: it must be a line comment
584    starting with <code>//</code>, it must start in the first column, and it must be
585    followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
586    uppercase letters with no intervening white space.
587    </p>
588    
589    <p>
590    The <var>CONDITION</var> is an ordinary JavaScript expression; if this
591    expression evaluates to <code>true</code>, then the lines of code between the
592    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
593    included in coverage statistics; otherwise, they are excluded from coverage
594    statistics.
595    </p>
596    
597    <p>
598    For example:
599    </p>
600    
601    <pre class="sh_javascript">
602    function log(s) {
603      if (window.console) {
604    //#JSCOVERAGE_IF window.console
605        console.log(s);
606    //#JSCOVERAGE_ENDIF
607      }
608    }
609    </pre>
610    
611    <p>
612    You can exclude code from coverage statistics unconditionally by using
613    <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
614    </p>
615    
616    <pre class="sh_javascript">
617    function f(x) {
618      if (x === null) {
619    //#JSCOVERAGE_IF 0
620        throw 'error';
621    //#JSCOVERAGE_ENDIF
622      }
623      ...
624    </pre>
625    
626    <p>
627    There is also a short form, which must appear on the line preceding an
628    <code>if</code> statement:
629    </p>
630    
631    <pre class="sh_javascript">
632    //#JSCOVERAGE_IF
633    if (...) {
634      ...
635    }
636    else if (...) {
637      ...
638    }
639    ...
640    else {
641      ...
642    }
643    </pre>
644    
645    <p>
646    
647    In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
648    and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
649    that you expect only one branch of the <code>if</code> statement to be executed;
650    coverage statistics will not be collected for the other branch(es).  For
651    example:
652    </p>
653    
654    <pre class="sh_javascript">
655    function log(s) {
656    //#JSCOVERAGE_IF
657      if (window.console) {
658        console.log(s);
659      }
660      else if (window.opera) {
661        opera.postError(s);
662      }
663      else {
664        throw 'no logging function available';
665      }
666    }
667    </pre>
668    
669    <p>
670    Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
671    </p>
672    
673  <h2>Caveats</h2>  <h2>Caveats</h2>
674    
675  <ul>  <ul>
# Line 364  Line 684 
684  statements, you may get strange results.  statements, you may get strange results.
685  <li>JSCoverage uses frames.  Some web pages that use frames may not function properly when run under JSCoverage, especially  <li>JSCoverage uses frames.  Some web pages that use frames may not function properly when run under JSCoverage, especially
686  those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).  those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
687  <li>JSCoverage is alpha software.  Use at your own risk.  <li>JSCoverage is distributed without any warranty.  See the <a href="license.html">license</a> for more details.
688  </ul>  </ul>
689    
690  <address>  <address>
691    Copyright &copy; 2007 siliconforks.com<br>    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>
   Last updated August 20, 2007<br>  
692    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
693  </address>  </address>
694    

Legend:
Removed from v.41  
changed lines
  Added in v.328

  ViewVC Help
Powered by ViewVC 1.1.24