/[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 72 by siliconforks, Thu Nov 22 03:04:55 2007 UTC revision 139 by siliconforks, Thu Jun 19 06:17:24 2008 UTC
# 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.1.tar.bz2  tar jxvf jscoverage-0.4.tar.bz2
52  cd jscoverage-0.3.1/  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 147  Line 161 
161  server, will give unexpected results.  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 187  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 216  Line 230 
230    
231  <img src="screenshot3.png" alt="Screenshot">  <img src="screenshot3.png" alt="Screenshot">
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
# Line 294  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 354  Line 368 
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    <img src="screenshot7.png" alt="Screenshot">
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>Caveats</h2>  <h2>Caveats</h2>
504    
505  <ul>  <ul>
# Line 372  Line 518 
518  </ul>  </ul>
519    
520  <address>  <address>
521    Copyright &copy; 2007 siliconforks.com<br>    Copyright &copy; 2007, 2008 <a href="http://siliconforks.com/"><img src="http://siliconforks.com/siliconforks-16x16.png" width="16" height="16" class="icon" alt="Silicon Forks"></a> <a href="http://siliconforks.com/">siliconforks.com</a><br>
522    Last updated August 26, 2007<br>    Last updated May 21, 2008<br>
523    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
524  </address>  </address>
525    
Legend:
Removed from v.72  
changed lines
  Added in v.139
  ViewVC Help
Powered by ViewVC 1.1.24