/[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 201 by siliconforks, Mon Sep 29 05:17:21 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 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 371  Line 375 
375  <h2>Using the <code>jscoverage-server</code> program</h2>  <h2>Using the <code>jscoverage-server</code> program</h2>
376    
377  <p>  <p>
378  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
379  serve files from the current directory. You can use  <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
380  <code>jscoverage-server</code> to serve <code>doc/example</code>:  directory:
381  </p>  </p>
382    
383  <pre>  <pre>
# Line 382  Line 386 
386  </pre>  </pre>
387    
388  <p>  <p>
389  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
390  <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
391  <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
392  <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
393  <code>http://127.0.0.1:8080/jscoverage.html</code> provides the JSCoverage web  one step by loading the URL
394  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
395  <code>jscoverage.html</code> exist; the JSCoverage web  browser.)  The
396  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  
397  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
398  executed in your browser.  executed in your browser.
399  </p>  </p>
# Line 410  Line 404 
404  To store coverage data, click the "Store" tab.  To store coverage data, click the "Store" tab.
405  </p>  </p>
406    
407  <img src="screenshot7.png" alt="Screenshot">  <p><img src="screenshot7.png" alt="Screenshot"></p>
408    
409  <p>  <p>
410  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>.
411  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
412  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.
413  </p>  </p>
414    
415  <p>  <p>
# Line 426  Line 420 
420  </p>  </p>
421    
422  <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>  
423  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
424  <code>--shutdown</code> option:  <code>--shutdown</code> option:
425  </p>  </p>
# Line 500  Line 483 
483  <dd>Stop a running instance of the server.  <dd>Stop a running instance of the server.
484  </dl>  </dl>
485    
486    <h2>Advanced topics</h2>
487    
488    <h3>Storing coverage reports programmatically</h3>
489    
490    <p>
491    If you are executing a test suite using <code>jscoverage-server</code>, you can
492    store a coverage report programmatically by having your test suite call the
493    <code>jscoverage_report</code> function (automatically generated by
494    <code>jscoverage-server</code>) after all your tests have finished running:
495    </p>
496    
497    <pre class="sh_javascript">
498    if (top.jscoverage_report) {
499      top.jscoverage_report();
500    }
501    </pre>
502    
503    <p>
504    You can specify the name of the directory in which to store the report by
505    passing the name as a parameter to the <code>jscoverage_report</code> function:
506    </p>
507    
508    <pre class="sh_javascript">
509    if (top.jscoverage_report) {
510      // determine the directory name based on the browser
511      var directory;
512      if (/MSIE/.test(navigator.userAgent)) {
513        directory = 'IE';
514      }
515      else {
516        directory = 'other';
517      }
518      top.jscoverage_report(directory);
519    }
520    </pre>
521    
522    <p>
523    This directory will be a subdirectory under the <code>jscoverage-report/</code>
524    directory (or whatever is specified with the <code>--report-dir</code> option).
525    Using the above example, the report would be stored to either
526    <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
527    </p>
528    
529    <p>
530    It is not necessary that your test suite be executed within the
531    <code>jscoverage.html</code> web interface to store a coverage report.  The URL
532    of the test suite can simply be loaded directly in a web browser.
533    </p>
534    
535    <h3>Conditional directives</h3>
536    
537    <p>
538    Sometimes you may wish to exclude certain lines of code from coverage
539    statistics. Some lines of code may be executed only in certain browsers; other
540    lines should never be executed at all (they may be present only to detect
541    programming errors).  You can use specially formatted comments in your code,
542    called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude
543    those lines from coverage statistics.  These lines will be ignored in the
544    JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated
545    with the color yellow.
546    </p>
547    
548    <p>
549    Conditional directives take the following form:
550    </p>
551    
552    <pre class="sh_javascript">
553    //#JSCOVERAGE_IF <var>CONDITION</var>
554    ...
555    //#JSCOVERAGE_ENDIF
556    </pre>
557    
558    <p>
559    The <var>CONDITION</var> is an ordinary JavaScript expression; if this
560    expression evaluates to <code>true</code>, then the lines of code between the
561    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are
562    included in coverage statistics; otherwise, they are excluded from coverage
563    statistics.
564    </p>
565    
566    <p>
567    In order to be recognized as a conditional directive, the comment must be
568    formatted exactly as shown: it must be a line comment starting with <code>//</code>,
569    it must start in the first column, and it must be followed by <code>#JSCOVERAGE_IF</code>
570    or <code>#JSCOVERAGE_ENDIF</code> in uppercase letters with no intervening white space.
571    </p>
572    
573    <p>
574    For example, if you have some code in an <code>if</code> statement which is
575    executed only in certain browsers, you can usually just repeat the condition in
576    a <code>//#JSCOVERAGE_IF</code> directive:
577    </p>
578    
579    <pre class="sh_javascript">
580      if (window.ActiveXObject) {
581    //#JSCOVERAGE_IF window.ActiveXObject
582        return new ActiveXObject('Msxml2.XMLHTTP');
583    //#JSCOVERAGE_ENDIF
584      }
585    </pre>
586    
587    <p>
588    Alternatively, it may be easier to diagnose problems if you specify exactly
589    which browsers you expect to execute the code in the conditional:
590    </p>
591    
592    <pre class="sh_javascript">
593      if (window.ActiveXObject) {
594    //#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)
595        return new ActiveXObject('Msxml2.XMLHTTP');
596    //#JSCOVERAGE_ENDIF
597      }
598    </pre>
599    
600    <p>
601    To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0</code> or
602    <code>//#JSCOVERAGE_IF false</code>:
603    </p>
604    
605    <pre class="sh_javascript">
606    function f(s) {
607      if (typeof(s) !== 'string') {
608    //#JSCOVERAGE_IF 0
609        throw 'function f requires a string argument';
610    //#JSCOVERAGE_ENDIF
611      }
612    }
613    </pre>
614    
615    <p>
616    Currently, conditional directives are ignored in stored coverage reports.
617    </p>
618    
619  <h2>Caveats</h2>  <h2>Caveats</h2>
620    
621  <ul>  <ul>
# Line 514  Line 630 
630  statements, you may get strange results.  statements, you may get strange results.
631  <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
632  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.).
633  <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.
634  </ul>  </ul>
635    
636  <address>  <address>
637    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>
638    Last updated May 21, 2008<br>    Last updated September 12, 2008<br>
639    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
640  </address>  </address>
641    

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

  ViewVC Help
Powered by ViewVC 1.1.24