/[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 147 by siliconforks, Fri Jun 20 02:19:40 2008 UTC revision 273 by siliconforks, Thu Oct 9 04:33:02 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    <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 147  Line 151 
151  <li>The "About" tab displays information about the current version of JSCoverage.  <li>The "About" tab displays information about the current version of JSCoverage.
152  </ul>  </ul>
153    
154  <img src="screenshot.png" alt="Screenshot">  <p><img src="screenshot.png" alt="Screenshot"></p>
155    
156  <p>  <p>
157  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 221  Line 225 
225  firefox "doc/instrumented/jscoverage.html?index.html"  firefox "doc/instrumented/jscoverage.html?index.html"
226  </pre>  </pre>
227    
228  <img src="screenshot2.png" alt="Screenshot">  <p><img src="screenshot2.png" alt="Screenshot"></p>
229    
230  <p>  <p>
231  For this particular page, the JavaScript does not execute automatically:  For this particular page, the JavaScript does not execute automatically:
232  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.
233  </p>  </p>
234    
235  <img src="screenshot3.png" alt="Screenshot">  <p><img src="screenshot3.png" alt="Screenshot"></p>
236    
237  <h3>3. Generating a coverage report</h3>  <h3>3. Generating a coverage report</h3>
238    
# Line 237  Line 241 
241  "Summary" tab.  "Summary" tab.
242  </p>  </p>
243    
244  <img src="screenshot4.png" alt="Screenshot">  <p><img src="screenshot4.png" alt="Screenshot"></p>
245    
246  <p>  <p>
247  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.
248  </p>  </p>
249    
250  <img src="screenshot5.png" alt="Screenshot">  <p><img src="screenshot5.png" alt="Screenshot"></p>
251    
252  <p>  <p>
253  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.
254  </p>  </p>
255    
256  <img src="screenshot6.png" alt="Screenshot">  <p><img src="screenshot6.png" alt="Screenshot"></p>
257    
258  <h2>Inverted mode</h2>  <h2>Inverted mode</h2>
259    
# 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 308  Line 312 
312  report" button to launch the JSCoverage report.  report" button to launch the JSCoverage report.
313  </p>  </p>
314    
315    <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  <h2><code>jscoverage</code> command line options</h2>  <h2><code>jscoverage</code> command line options</h2>
321    
322  <p>  <p>
# Line 321  Line 330 
330  <dd>Display the version of the program.  <dd>Display the version of the program.
331  <dt><code>-v</code>, <code>--verbose</code>  <dt><code>-v</code>, <code>--verbose</code>
332  <dd>Explain what is being done.  <dd>Explain what is being done.
333    <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  <dt><code>--exclude=<var>PATH</var></code>  <dt><code>--exclude=<var>PATH</var></code>
337  <dd>The command  <dd>The command
338  <pre>  <pre>
# Line 331  Line 343 
343  <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>.
344  <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
345  its entire contents are skipped). This option may be given multiple times.  its entire contents are skipped). This option may be given multiple times.
346    <dt><code>--no-highlight</code>
347    <dd>Do not perform syntax highlighting of JavaScript code.
348  <dt><code>--no-instrument=<var>PATH</var></code>  <dt><code>--no-instrument=<var>PATH</var></code>
349  <dd>The command  <dd>The command
350  <pre>  <pre>
# Line 371  Line 385 
385  <h2>Using the <code>jscoverage-server</code> program</h2>  <h2>Using the <code>jscoverage-server</code> program</h2>
386    
387  <p>  <p>
388  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
389  serve files from the current directory. You can use  <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
390  <code>jscoverage-server</code> to serve <code>doc/example</code>:  directory:
391  </p>  </p>
392    
393  <pre>  <pre>
# Line 382  Line 396 
396  </pre>  </pre>
397    
398  <p>  <p>
399  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
400  <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
401  <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
402  <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
403  <code>http://127.0.0.1:8080/jscoverage.html</code> provides the JSCoverage web  one step by loading the URL
404  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
405  <code>jscoverage.html</code> exist; the JSCoverage web  browser.)  The
406  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  
407  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
408  executed in your browser.  executed in your browser.
409  </p>  </p>
# Line 410  Line 414 
414  To store coverage data, click the "Store" tab.  To store coverage data, click the "Store" tab.
415  </p>  </p>
416    
417  <img src="screenshot7.png" alt="Screenshot">  <p><img src="screenshot7.png" alt="Screenshot"></p>
418    
419  <p>  <p>
420  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>.
421  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
422  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.
423  </p>  </p>
424    
425  <p>  <p>
# Line 426  Line 430 
430  </p>  </p>
431    
432  <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>  
433  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
434  <code>--shutdown</code> option:  <code>--shutdown</code> option:
435  </p>  </p>
# Line 475  Line 468 
468  <dt><code>--document-root=<var>PATH</var></code>  <dt><code>--document-root=<var>PATH</var></code>
469  <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
470  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.
471    <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  <dt><code>--ip-address=<var>ADDRESS</var></code>  <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  <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.  <code>0.0.0.0</code> to use any address.
479    <dt><code>--no-highlight</code>
480    <dd>Do not perform syntax highlighting of JavaScript code.
481  <dt><code>--no-instrument=<var>URL</var></code>  <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>  <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:  with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:
# Line 500  Line 500 
500  <dd>Stop a running instance of the server.  <dd>Stop a running instance of the server.
501  </dl>  </dl>
502    
503    <h2>Advanced topics</h2>
504    
505    <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    if (window.jscoverage_report) {
516      jscoverage_report();
517    }
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    if (window.jscoverage_report) {
527      // 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      jscoverage_report(directory);
536    }
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    <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    <p>
553    The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
554    reports programmatically.
555    </p>
556    
557    <h3>Ignoring certain lines of code</h3>
558    
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    lines should never be executed at all (they may be present only to detect
563    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    </p>
568    
569    <p>
570    These comments take the following form:
571    </p>
572    
573    <pre class="sh_javascript">
574    //#JSCOVERAGE_IF <var>CONDITION</var>
575    ...
576    //#JSCOVERAGE_ENDIF
577    </pre>
578    
579    <p>
580    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    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    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
590    included in coverage statistics; otherwise, they are excluded from coverage
591    statistics.
592    </p>
593    
594    <p>
595    For example:
596    </p>
597    
598    <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    <p>
609    You can exclude code from coverage statistics unconditionally by using
610    <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
611    </p>
612    
613    <pre class="sh_javascript">
614    function f(x) {
615      if (x === null) {
616    //#JSCOVERAGE_IF 0
617        throw 'error';
618    //#JSCOVERAGE_ENDIF
619      }
620      ...
621    </pre>
622    
623    <p>
624    There is also a short form, which must appear on the line preceding an
625    <code>if</code> statement:
626    </p>
627    
628    <pre class="sh_javascript">
629    //#JSCOVERAGE_IF
630    if (...) {
631      ...
632    }
633    else if (...) {
634      ...
635    }
636    ...
637    else {
638      ...
639    }
640    </pre>
641    
642    <p>
643    
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    </p>
650    
651    <pre class="sh_javascript">
652    function log(s) {
653    //#JSCOVERAGE_IF
654      if (window.console) {
655        console.log(s);
656      }
657      else if (window.opera) {
658        opera.postError(s);
659      }
660      else {
661        throw 'no logging function available';
662      }
663    }
664    </pre>
665    
666    <p>
667    Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
668    </p>
669    
670  <h2>Caveats</h2>  <h2>Caveats</h2>
671    
672  <ul>  <ul>
# Line 514  Line 681 
681  statements, you may get strange results.  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  <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.).  those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
684  <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.
685  </ul>  </ul>
686    
687  <address>  <address>
688    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>    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    Last updated May 21, 2008<br>    Last updated September 12, 2008<br>
690    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
691  </address>  </address>
692    

Legend:
Removed from v.147  
changed lines
  Added in v.273

  ViewVC Help
Powered by ViewVC 1.1.24