/[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 139 by siliconforks, Thu Jun 19 06:17:24 2008 UTC revision 240 by siliconforks, Fri Oct 3 23:51:32 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 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 410  Line 409 
409  To store coverage data, click the "Store" tab.  To store coverage data, click the "Store" tab.
410  </p>  </p>
411    
412  <img src="screenshot7.png" alt="Screenshot">  <p><img src="screenshot7.png" alt="Screenshot"></p>
413    
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 500  Line 495 
495  <dd>Stop a running instance of the server.  <dd>Stop a running instance of the server.
496  </dl>  </dl>
497    
498    <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>Ignoring certain lines of code</h3>
548    
549    <p>
550    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
552    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 to
554    tell JSCoverage to ignore certain lines of code. These lines will not be
555    included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
556    be indicated with the color yellow.
557    </p>
558    
559    <p>
560    These comments take the following form:
561    </p>
562    
563    <pre class="sh_javascript">
564    //#JSCOVERAGE_IF <var>CONDITION</var>
565    ...
566    //#JSCOVERAGE_ENDIF
567    </pre>
568    
569    <p>
570    The comment must be formatted exactly as shown: it must be a line comment
571    starting with <code>//</code>, it must start in the first column, and it must be
572    followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
573    uppercase letters with no intervening white space.
574    </p>
575    
576    <p>
577    The <var>CONDITION</var> is an ordinary JavaScript expression; if this
578    expression evaluates to <code>true</code>, then the lines of code between the
579    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
580    included in coverage statistics; otherwise, they are excluded from coverage
581    statistics.
582    </p>
583    
584    <p>
585    For example:
586    </p>
587    
588    <pre class="sh_javascript">
589    function log(s) {
590      if (window.console) {
591    //#JSCOVERAGE_IF window.console
592        console.log(s);
593    //#JSCOVERAGE_ENDIF
594      }
595    }
596    </pre>
597    
598    <p>
599    You can exclude code from coverage statistics unconditionally by using
600    <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
601    </p>
602    
603    <pre class="sh_javascript">
604    function f(x) {
605      if (x === null) {
606    //#JSCOVERAGE_IF 0
607        throw 'error';
608    //#JSCOVERAGE_ENDIF
609      }
610      ...
611    </pre>
612    
613    <p>
614    There is also a short form, which must appear on the line preceding an
615    <code>if</code> statement:
616    </p>
617    
618    <pre class="sh_javascript">
619    //#JSCOVERAGE_IF
620    if (...) {
621      ...
622    }
623    else if (...) {
624      ...
625    }
626    ...
627    else {
628      ...
629    }
630    </pre>
631    
632    <p>
633    
634    In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
635    and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
636    that you expect only one branch of the <code>if</code> statement to be executed;
637    coverage statistics will not be collected for the other branch(es).  For
638    example:
639    </p>
640    
641    <pre class="sh_javascript">
642    function log(s) {
643    //#JSCOVERAGE_IF
644      if (window.console) {
645        console.log(s);
646      }
647      else if (window.opera) {
648        opera.postError(s);
649      }
650      else {
651        throw 'no logging function available';
652      }
653    }
654    </pre>
655    
656    <p>
657    Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
658    </p>
659    
660  <h2>Caveats</h2>  <h2>Caveats</h2>
661    
662  <ul>  <ul>
# Line 514  Line 671 
671  statements, you may get strange results.  statements, you may get strange results.
672  <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
673  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.).
674  <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.
675  </ul>  </ul>
676    
677  <address>  <address>
678    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>    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>
679    Last updated May 21, 2008<br>    Last updated September 12, 2008<br>
680    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
681  </address>  </address>
682    

Legend:
Removed from v.139  
changed lines
  Added in v.240

  ViewVC Help
Powered by ViewVC 1.1.24