/[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 197 by siliconforks, Mon Sep 29 05:16:13 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>
# Line 9  Line 9 
9  <h1>JSCoverage user manual</h1>  <h1>JSCoverage user manual</h1>
10    
11  <p>  <p>
12  JSCoverage is a tool used to measure code coverage in JavaScript  JSCoverage is a tool used to measure code coverage in JavaScript programs.
 programs.  
13  </p>  </p>
14    
15  <p>  <p>
16  JSCoverage has two components:  JSCoverage works by adding instrumentation to JavaScript code before it is
17    executed in a web browser.  JSCoverage provides several alternative ways of doing
18    this:
19  </p>  </p>
20    
21  <ol>  <ul>
22  <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
23  <li>A web application which is used to execute instrumented code and generate a  instrumented JavaScript files.
24  code coverage report.  </li>
25  </ol>  <li>Alternatively, you can use the <code>jscoverage-server</code> program, a simple web server that instruments
26    JavaScript code as it is served.
27    </li>
28    <li>Finally, <code>jscoverage-server</code> can be run with the <code>--proxy</code> option to
29    act as a proxy server which instruments any JavaScript code proxied through it.
30    </li>
31    </ul>
32    
33    <p>
34    The <code>jscoverage-server</code> program (with or without the <code>--proxy</code>
35    option) has the advantage of being able to store coverage reports to the filesystem.
36    </p>
37    
38  <h2>Installing JSCoverage</h2>  <h2>Installing JSCoverage</h2>
39    
# Line 36  Line 48 
48  </p>  </p>
49    
50  <pre>  <pre>
51  tar jxvf jscoverage-0.3.tar.bz2  tar jxvf jscoverage-0.4.tar.bz2
52  cd jscoverage-0.3/  cd jscoverage-0.4/
53  ./configure  ./configure
54  make  make
55  </pre>  </pre>
56    
57  <p>  <p>
58  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>
59  You can install the executable in <code>/usr/local</code> with the command:  executables (<code>jscoverage.exe</code> and <code>jscoverage-server.exe</code>
60    on Windows). You can install the executables in <code>/usr/local</code> with the
61    command:
62  </p>  </p>
63    
64  <pre>  <pre>
# Line 52  Line 66 
66  </pre>  </pre>
67    
68  <p>  <p>
69  Alternatively, since the program consists of only the single self-contained  Alternatively, you may simply copy the <code>jscoverage</code> executable and/or
70  <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
71  in your <code>PATH</code>.  <code>PATH</code>.
72  </p>  </p>
73    
74  <h2>Using JSCoverage</h2>  <h2>Using the <code>jscoverage</code> program</h2>
75    
76  <p>  <p>
77  Using JSCoverage requires three steps:  Using the <code>jscoverage</code> program requires the following steps:
78  </p>  </p>
79    
80  <h3>1. Instrumenting code</h3>  <h3>1. Instrumenting code</h3>
81    
82  <p>  <p>
83  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
84  <code>jscoverage</code> executable.  You must provide two arguments:  executing <code>jscoverage</code> with two arguments:
85  </p>  </p>
86    
87  <pre>  <pre>
# Line 118  Line 132 
132  which is used to execute the instrumented code.  which is used to execute the instrumented code.
133  </p>  </p>
134    
135  <h3>2. Running instrumented code in the web application</h3>  <h3>2. Executing the instrumented code in a web browser</h3>
136    
137  <p>  <p>
138  Open <code>jscoverage.html</code> in your web browser.  Open <code>jscoverage.html</code> in your web browser.
# Line 133  Line 147 
147  <li>The "About" tab displays information about the current version of JSCoverage.  <li>The "About" tab displays information about the current version of JSCoverage.
148  </ul>  </ul>
149    
150  <img src="screenshot.png" alt="Screenshot">  <p><img src="screenshot.png" alt="Screenshot"></p>
151    
152  <p>  <p>
153  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.
# Line 141  Line 155 
155  entering its URL into the "URL" input field.  For example, to load  entering its URL into the "URL" input field.  For example, to load
156  the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can  the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can
157  enter the relative URL <code>dir/index.html</code> into the input field.  enter the relative URL <code>dir/index.html</code> into the input field.
158    You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
159    or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
160    from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
161    server, will give unexpected results.
162  </p>  </p>
163    
164  <h3>3. Generating the coverage report</h3>  <h3>3. Generating a coverage report</h3>
165    
166  <p>  <p>
167  Once the JavaScript code in the page in the "Browser" tab has been executed, click on  Once the JavaScript code in the page in the "Browser" tab has been executed, click on
# Line 183  Line 201 
201  place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.  place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.
202  </p>  </p>
203    
204  <h3>2. Executing instrumented code</h3>  <h3>2. Executing the instrumented code in a web browser</h3>
205    
206  <p>  <p>
207  You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type  You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type
# Line 203  Line 221 
221  firefox "doc/instrumented/jscoverage.html?index.html"  firefox "doc/instrumented/jscoverage.html?index.html"
222  </pre>  </pre>
223    
224  <img src="screenshot2.png" alt="Screenshot">  <p><img src="screenshot2.png" alt="Screenshot"></p>
225    
226  <p>  <p>
227  For this particular page, the JavaScript does not execute automatically:  For this particular page, the JavaScript does not execute automatically:
228  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.
229  </p>  </p>
230    
231  <img src="screenshot3.png" alt="Screenshot">  <p><img src="screenshot3.png" alt="Screenshot"></p>
232    
233  <h3>3. Generating the coverage report</h3>  <h3>3. Generating a coverage report</h3>
234    
235  <p>  <p>
236  Once you have executed the JavaScript code, you are instructed to click on the  Once you have executed the JavaScript code, you are instructed to click on the
237  "Summary" tab.  "Summary" tab.
238  </p>  </p>
239    
240  <img src="screenshot4.png" alt="Screenshot">  <p><img src="screenshot4.png" alt="Screenshot"></p>
241    
242  <p>  <p>
243  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.
244  </p>  </p>
245    
246  <img src="screenshot5.png" alt="Screenshot">  <p><img src="screenshot5.png" alt="Screenshot"></p>
247    
248  <p>  <p>
249  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.
250  </p>  </p>
251    
252  <img src="screenshot6.png" alt="Screenshot">  <p><img src="screenshot6.png" alt="Screenshot"></p>
253    
254  <h2>Inverted mode</h2>  <h2>Inverted mode</h2>
255    
# Line 290  Line 308 
308  report" button to launch the JSCoverage report.  report" button to launch the JSCoverage report.
309  </p>  </p>
310    
311  <h2>Command line options</h2>  <h2><code>jscoverage</code> command line options</h2>
312    
313  <p>  <p>
314  The <code>jscoverage</code> program accepts the following options:  The <code>jscoverage</code> program accepts the following options:
# Line 321  Line 339 
339  copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>  copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
340  recursively, but does not instrument any JavaScript code in  recursively, but does not instrument any JavaScript code in
341  <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
342  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
343  (JavaScript) file or a directory (in which case any JavaScript files located  (JavaScript) file or a directory (in which case any JavaScript files located
344  anywhere underneath the directory are not instrumented). This option may be  anywhere underneath the directory are not instrumented). This option may be
345  given multiple times.  given multiple times.
# Line 344  Line 362 
362  <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>
363  <dd>Determines whether to initially display the "Missing" column in the "Summary"  <dd>Determines whether to initially display the "Missing" column in the "Summary"
364  tab.  <var>BOOLEAN</var> can be  tab.  <var>BOOLEAN</var> can be
365  <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>
366  (to display the "Missing" column), or  (to display the "Missing" column), or
367  <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>
368  (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.
369  </dl>  </dl>
370    
371    <h2>Using the <code>jscoverage-server</code> program</h2>
372    
373    <p>
374    The <code>jscoverage-server</code> program is a simple web server which will
375    serve files from the current directory. You can use
376    <code>jscoverage-server</code> to serve <code>doc/example</code>:
377    </p>
378    
379    <pre>
380      cd doc/example
381      jscoverage-server --verbose
382    </pre>
383    
384    <p>
385    By default, the server runs on port 8080.  URLs are mapped to files in the
386    <code>doc/example</code> directory: e.g., the URL
387    <code>http://127.0.0.1:8080/index.html</code> can be used to request
388    <code>doc/example/index.html</code>.  In addition, the special URL
389    <code>http://127.0.0.1:8080/jscoverage.html</code> provides the JSCoverage web
390    interface.  Note that it is not necessary that a file named
391    <code>jscoverage.html</code> exist; the JSCoverage web
392    interface is built into the server, and it will automatically be served when the special
393    <code>/jscoverage.html</code> URL is requested.
394    </p>
395    
396    <p>
397    You can use the <code>/jscoverage.html</code> URL in the same way as the
398    <code>jscoverage.html</code> file generated by the <code>jscoverage</code>
399    program. For example, you can visit the URL
400    <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> to execute the
401    JavaScript associated with the <code>index.html</code> page.  The
402    <code>jscoverage-server</code> program automatically instruments all served
403    JavaScript code, so that code coverage data will be gathered as the code is
404    executed in your browser.
405    </p>
406    
407    <p>
408    The web interface is slightly different from that generated by the
409    <code>jscoverage</code> program: it has a new tab named "Store".
410    To store coverage data, click the "Store" tab.
411    </p>
412    
413    <p><img src="screenshot7.png" alt="Screenshot"></p>
414    
415    <p>
416    When you click the "Store" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
417    You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
418    your web browser - you don't need the <code>jscoverage-server</code> running to see it.
419    </p>
420    
421    <p>
422    If you use the "Store" tab again to store coverage data, the new data will be merged with
423    the previous data in the <code>jscoverage-report/</code> directory.  This can be useful,
424    for instance, if you wish to run a set of tests in different browsers and generate an
425    aggregate report which combines the data for all of them.
426    </p>
427    
428    <p>
429    You can also store data programmatically from your tests by adding the following to your
430    JavaScript code:
431    </p>
432    
433    <pre>
434    if (top.jscoverage_report) {
435      top.jscoverage_report();
436    }
437    </pre>
438    
439    <p>
440    You can stop the server by running another instance of <code>jscoverage-server</code> with the
441    <code>--shutdown</code> option:
442    </p>
443    
444    <pre>
445      jscoverage-server --shutdown
446    </pre>
447    
448    <h2>Using <code>jscoverage-server --proxy</code></h2>
449    
450    <p>
451    To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
452    </p>
453    
454    <pre>
455      jscoverage-server --verbose --proxy
456    </pre>
457    
458    <p>
459    Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
460    You can then generate code coverage data for a web page on the server <code>example.com</code>
461    by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.  
462    Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
463    by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
464    </p>
465    
466    <h2><code>jscoverage-server</code> command line options</h2>
467    
468    <dl>
469    <dt><code>-h</code>, <code>--help</code>
470    <dd>Display a brief help message.
471    <dt><code>-V</code>, <code>--version</code>
472    <dd>Display the version of the program.
473    <dt><code>-v</code>, <code>--verbose</code>
474    <dd>Explain what is being done.
475    <dt><code>--document-root=<var>PATH</var></code>
476    <dd>Serve web content from the directory given by <var>PATH</var>.  The default is
477    the current directory.  This option may not be given with the <code>--proxy</code> option.
478    <dt><code>--ip-address=<var>ADDRESS</var></code>
479    <dd>Run the server on the IP address given by <var>ADDRESS</var>.  The default is <code>127.0.0.1</code>.  Specify
480    <code>0.0.0.0</code> to use any address.
481    <dt><code>--no-instrument=<var>URL</var></code>
482    <dd>Do not instrument JavaScript code from <var>URL</var>.  If you are running <code>jscoverage-server</code>
483    with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:
484    <pre>
485    jscoverage-server --proxy --no-instrument=http://example.com/scripts/
486    </pre>
487    Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
488    <pre>
489    jscoverage-server --no-instrument=/scripts/
490    </pre>
491    This option may be given multiple times.
492    <dt><code>--port=<var>PORT</var></code>
493    <dd>Run the server on the port given by <var>PORT</var>.  The default is port 8080.
494    <dt><code>--proxy</code>
495    <dd>Run as a proxy server.
496    <dt><code>--report-dir=<var>PATH</var></code>
497    <dd>Use the directory given by <var>PATH</var> for storing coverage reports.  The default is
498    <code>jscoverage-report/</code> in the current directory.
499    <dt><code>--shutdown</code>
500    <dd>Stop a running instance of the server.
501    </dl>
502    
503    <h2>Advanced topics</h2>
504    
505    <h3>Conditional directives</h3>
506    
507    <p>
508    Sometimes you may wish to exclude certain lines of code from coverage
509    statistics. Some lines of code may be executed only in certain browsers; other
510    lines should never be executed at all (they may only be present to detect
511    programming errors).  You can use specially formatted comments in your code,
512    called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude
513    those lines from coverage statistics.  These lines will be ignored in the
514    JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated
515    with the color yellow.
516    </p>
517    
518    <p>
519    Conditional directives take the following form:
520    </p>
521    
522    <pre class="sh_javascript">
523    //#JSCOVERAGE_IF <var>CONDITION</var>
524    ...
525    //#JSCOVERAGE_ENDIF
526    </pre>
527    
528    <p>
529    The <var>CONDITION</var> is an ordinary JavaScript expression; if this
530    expression evaluates to <code>true</code>, then the lines of code between the
531    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are
532    included in coverage statistics; otherwise, they are excluded from coverage
533    statistics.
534    </p>
535    
536    <p>
537    In order to be recognized as a conditional directive, the comment must be
538    formatted exactly as shown: it must be a line comment starting with <code>//</code>,
539    it must start in the first column, and it must be followed by <code>#JSCOVERAGE_IF</code>
540    or <code>#JSCOVERAGE_ENDIF</code> in uppercase letters with no intervening white space.
541    </p>
542    
543    <p>
544    For example, if you have some code in an <code>if</code> statement which is
545    executed only in certain browsers, you can usually just repeat the condition in
546    a <code>//#JSCOVERAGE_IF</code> directive:
547    </p>
548    
549    <pre class="sh_javascript">
550      if (window.ActiveXObject) {
551    //#JSCOVERAGE_IF window.ActiveXObject
552        return new ActiveXObject('Msxml2.XMLHTTP');
553    //#JSCOVERAGE_ENDIF
554      }
555    </pre>
556    
557    <p>
558    Alternatively, it may be easier to diagnose problems if you specify exactly
559    which browsers you expect to execute the code in the conditional:
560    </p>
561    
562    <pre class="sh_javascript">
563      if (window.ActiveXObject) {
564    //#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)
565        return new ActiveXObject('Msxml2.XMLHTTP');
566    //#JSCOVERAGE_ENDIF
567      }
568    </pre>
569    
570    <p>
571    To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0</code> or
572    <code>//#JSCOVERAGE_IF false</code>:
573    </p>
574    
575    <pre class="sh_javascript">
576    function f(s) {
577      if (typeof(s) !== 'string') {
578    //#JSCOVERAGE_IF 0
579        throw 'function f requires a string argument';
580    //#JSCOVERAGE_ENDIF
581      }
582    }
583    </pre>
584    
585  <h2>Caveats</h2>  <h2>Caveats</h2>
586    
587  <ul>  <ul>
# Line 368  Line 600 
600  </ul>  </ul>
601    
602  <address>  <address>
603    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>
604    Last updated August 20, 2007<br>    Last updated September 12, 2008<br>
605    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
606  </address>  </address>
607    

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

  ViewVC Help
Powered by ViewVC 1.1.24