/[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 197 by siliconforks, Mon Sep 29 05:16:13 2008 UTC revision 225 by siliconforks, Fri Oct 3 02:28:38 2008 UTC
# Line 2  Line 2 
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    <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  </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 programs.  JSCoverage is a tool that measures code coverage in JavaScript programs.
17  </p>  </p>
18    
19  <p>  <p>
# Line 35  Line 39 
39  option) has the advantage of being able to store coverage reports to the filesystem.  option) has the advantage of being able to store coverage reports to the filesystem.
40  </p>  </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 74  Line 78 
78  <h2>Using the <code>jscoverage</code> program</h2>  <h2>Using the <code>jscoverage</code> program</h2>
79    
80  <p>  <p>
81  Using the <code>jscoverage</code> program requires the following steps:  Using the <code>jscoverage</code> program involves the following steps:
82  </p>  </p>
83    
84  <h3>1. Instrumenting code</h3>  <h3>1. Instrumenting code</h3>
# Line 268  Line 272 
272  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:
273  </p>  </p>
274    
275  <pre>  <pre class="sh_javascript">
276  window.open("path/to/jscoverage.html");  window.open('path/to/jscoverage.html');
277  </pre>  </pre>
278    
279  <p>  <p>
# Line 284  Line 288 
288  attach it to a button:  attach it to a button:
289  </p>  </p>
290    
291  <pre>  <pre class="sh_html">
292  &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;
293  </pre>  </pre>
294    
295  <p>  <p>
# Line 321  Line 325 
325  <dd>Display the version of the program.  <dd>Display the version of the program.
326  <dt><code>-v</code>, <code>--verbose</code>  <dt><code>-v</code>, <code>--verbose</code>
327  <dd>Explain what is being done.  <dd>Explain what is being done.
328    <dt><code>--encoding=<var>ENCODING</var></code>
329    <dd>Assume that all JavaScript files use the given character encoding.  The
330    default is ISO-8859-1.
331  <dt><code>--exclude=<var>PATH</var></code>  <dt><code>--exclude=<var>PATH</var></code>
332  <dd>The command  <dd>The command
333  <pre>  <pre>
# Line 331  Line 338 
338  <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>.
339  <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
340  its entire contents are skipped). This option may be given multiple times.  its entire contents are skipped). This option may be given multiple times.
341    <dt><code>--no-highlight</code>
342    <dd>Do not perform syntax highlighting of JavaScript code.
343  <dt><code>--no-instrument=<var>PATH</var></code>  <dt><code>--no-instrument=<var>PATH</var></code>
344  <dd>The command  <dd>The command
345  <pre>  <pre>
# Line 371  Line 380 
380  <h2>Using the <code>jscoverage-server</code> program</h2>  <h2>Using the <code>jscoverage-server</code> program</h2>
381    
382  <p>  <p>
383  The <code>jscoverage-server</code> program is a simple web server which will  The <code>jscoverage-server</code> program is a simple web server. You can use
384  serve files from the current directory. You can use  <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
385  <code>jscoverage-server</code> to serve <code>doc/example</code>:  directory:
386  </p>  </p>
387    
388  <pre>  <pre>
# Line 382  Line 391 
391  </pre>  </pre>
392    
393  <p>  <p>
394  By default, the server runs on port 8080.  URLs are mapped to files in the  Once the server is running, you can access the JSCoverage web interface by
395  <code>doc/example</code> directory: e.g., the URL  visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
396  <code>http://127.0.0.1:8080/index.html</code> can be used to request  load the <code>doc/example/index.html</code> file by entering
397  <code>doc/example/index.html</code>.  In addition, the special URL  <code>index.html</code> in the "URL" input field.  (Or you can do this all in
398  <code>http://127.0.0.1:8080/jscoverage.html</code> provides the JSCoverage web  one step by loading the URL
399  interface.  Note that it is not necessary that a file named  <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
400  <code>jscoverage.html</code> exist; the JSCoverage web  browser.)  The
401  interface is built into the server, and it will automatically be served when the special  <code>jscoverage-server</code> program automatically instruments any served
 <code>/jscoverage.html</code> URL is requested.  
 </p>  
   
 <p>  
 You can use the <code>/jscoverage.html</code> URL in the same way as the  
 <code>jscoverage.html</code> file generated by the <code>jscoverage</code>  
 program. For example, you can visit the URL  
 <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> to execute the  
 JavaScript associated with the <code>index.html</code> page.  The  
 <code>jscoverage-server</code> program automatically instruments all served  
402  JavaScript code, so that code coverage data will be gathered as the code is  JavaScript code, so that code coverage data will be gathered as the code is
403  executed in your browser.  executed in your browser.
404  </p>  </p>
# Line 415  Line 414 
414  <p>  <p>
415  When you click the "Store" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.  When you click the "Store" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
416  You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in  You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
417  your web browser - you don't need the <code>jscoverage-server</code> running to see it.  your web browser - you don't need the <code>jscoverage-server</code> running to access it.
418  </p>  </p>
419    
420  <p>  <p>
# Line 426  Line 425 
425  </p>  </p>
426    
427  <p>  <p>
 You can also store data programmatically from your tests by adding the following to your  
 JavaScript code:  
 </p>  
   
 <pre>  
 if (top.jscoverage_report) {  
   top.jscoverage_report();  
 }  
 </pre>  
   
 <p>  
428  You can stop the server by running another instance of <code>jscoverage-server</code> with the  You can stop the server by running another instance of <code>jscoverage-server</code> with the
429  <code>--shutdown</code> option:  <code>--shutdown</code> option:
430  </p>  </p>
# Line 475  Line 463 
463  <dt><code>--document-root=<var>PATH</var></code>  <dt><code>--document-root=<var>PATH</var></code>
464  <dd>Serve web content from the directory given by <var>PATH</var>.  The default is  <dd>Serve web content from the directory given by <var>PATH</var>.  The default is
465  the current directory.  This option may not be given with the <code>--proxy</code> option.  the current directory.  This option may not be given with the <code>--proxy</code> option.
466    <dt><code>--encoding=<var>ENCODING</var></code>
467    <dd>Assume that all JavaScript files use the given character encoding.  The
468    default is ISO-8859-1.  Note that if you use the <code>--proxy</code> option, the
469    character encoding will be determined from the <code>charset</code> parameter in
470    the <code>Content-Type</code> HTTP header.
471  <dt><code>--ip-address=<var>ADDRESS</var></code>  <dt><code>--ip-address=<var>ADDRESS</var></code>
472  <dd>Run the server on the IP address given by <var>ADDRESS</var>.  The default is <code>127.0.0.1</code>.  Specify  <dd>Run the server on the IP address given by <var>ADDRESS</var>.  The default is <code>127.0.0.1</code>.  Specify
473  <code>0.0.0.0</code> to use any address.  <code>0.0.0.0</code> to use any address.
474    <dt><code>--no-highlight</code>
475    <dd>Do not perform syntax highlighting of JavaScript code.
476  <dt><code>--no-instrument=<var>URL</var></code>  <dt><code>--no-instrument=<var>URL</var></code>
477  <dd>Do not instrument JavaScript code from <var>URL</var>.  If you are running <code>jscoverage-server</code>  <dd>Do not instrument JavaScript code from <var>URL</var>.  If you are running <code>jscoverage-server</code>
478  with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:  with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:
# Line 502  Line 497 
497    
498  <h2>Advanced topics</h2>  <h2>Advanced topics</h2>
499    
500    <h3>Storing coverage reports programmatically</h3>
501    
502    <p>
503    If you are executing a test suite using <code>jscoverage-server</code>, you can
504    store a coverage report programmatically by having your test suite call the
505    <code>jscoverage_report</code> function (automatically generated by
506    <code>jscoverage-server</code>) after all your tests have finished running:
507    </p>
508    
509    <pre class="sh_javascript">
510    if (top.jscoverage_report) {
511      top.jscoverage_report();
512    }
513    </pre>
514    
515    <p>
516    You can specify the name of the directory in which to store the report by
517    passing the name as a parameter to the <code>jscoverage_report</code> function:
518    </p>
519    
520    <pre class="sh_javascript">
521    if (top.jscoverage_report) {
522      // determine the directory name based on the browser
523      var directory;
524      if (/MSIE/.test(navigator.userAgent)) {
525        directory = 'IE';
526      }
527      else {
528        directory = 'other';
529      }
530      top.jscoverage_report(directory);
531    }
532    </pre>
533    
534    <p>
535    This directory will be a subdirectory under the <code>jscoverage-report/</code>
536    directory (or whatever is specified with the <code>--report-dir</code> option).
537    Using the above example, the report would be stored to either
538    <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
539    </p>
540    
541    <p>
542    It is not necessary that your test suite be executed within the
543    <code>jscoverage.html</code> web interface to store a coverage report.  The URL
544    of the test suite can simply be loaded directly in a web browser.
545    </p>
546    
547  <h3>Conditional directives</h3>  <h3>Conditional directives</h3>
548    
549  <p>  <p>
550  Sometimes you may wish to exclude certain lines of code from coverage  Sometimes you may wish to exclude certain lines of code from coverage
551  statistics. Some lines of code may be executed only in certain browsers; other  statistics. Some lines of code may be executed only in certain browsers; other
552  lines should never be executed at all (they may only be present to detect  lines should never be executed at all (they may be present only to detect
553  programming errors).  You can use specially formatted comments in your code,  programming errors).  You can use specially formatted comments in your code,
554  called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude  called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude
555  those lines from coverage statistics.  These lines will be ignored in the  those lines from coverage statistics.  These lines will be ignored in the
# Line 582  Line 624 
624  }  }
625  </pre>  </pre>
626    
627    <p>
628    Currently, conditional directives are ignored in stored coverage reports.
629    </p>
630    
631  <h2>Caveats</h2>  <h2>Caveats</h2>
632    
633  <ul>  <ul>
# Line 596  Line 642 
642  statements, you may get strange results.  statements, you may get strange results.
643  <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
644  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.).
645  <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.
646  </ul>  </ul>
647    
648  <address>  <address>

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

  ViewVC Help
Powered by ViewVC 1.1.24