/[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 198 by siliconforks, Mon Sep 29 05:16:31 2008 UTC revision 273 by siliconforks, Thu Oct 9 04:33:02 2008 UTC
# Line 39  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 312  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 325  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 335  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 458  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 495  Line 512 
512  </p>  </p>
513    
514  <pre class="sh_javascript">  <pre class="sh_javascript">
515  if (top.jscoverage_report) {  if (window.jscoverage_report) {
516    top.jscoverage_report();    jscoverage_report();
517  }  }
518  </pre>  </pre>
519    
# Line 506  Line 523 
523  </p>  </p>
524    
525  <pre class="sh_javascript">  <pre class="sh_javascript">
526  if (top.jscoverage_report) {  if (window.jscoverage_report) {
527    // determine the directory name based on the browser    // determine the directory name based on the browser
528    var directory;    var directory;
529    if (/MSIE/.test(navigator.userAgent)) {    if (/MSIE/.test(navigator.userAgent)) {
# Line 515  Line 532 
532    else {    else {
533      directory = 'other';      directory = 'other';
534    }    }
535    top.jscoverage_report(directory);    jscoverage_report(directory);
536  }  }
537  </pre>  </pre>
538    
# Line 526  Line 543 
543  <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.  <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
544  </p>  </p>
545    
546  <h3>Conditional directives</h3>  <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>  <p>
560  Sometimes you may wish to exclude certain lines of code from coverage  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  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  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,  programming errors).  You can use specially formatted comments in your code to
564  called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude  tell JSCoverage to ignore certain lines of code. These lines will not be
565  those lines from coverage statistics.  These lines will be ignored in the  included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
566  JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated  be indicated with the color yellow.
 with the color yellow.  
567  </p>  </p>
568    
569  <p>  <p>
570  Conditional directives take the following form:  These comments take the following form:
571  </p>  </p>
572    
573  <pre class="sh_javascript">  <pre class="sh_javascript">
# Line 550  Line 577 
577  </pre>  </pre>
578    
579  <p>  <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  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  expression evaluates to <code>true</code>, then the lines of code between the
589  <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are  <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
590  included in coverage statistics; otherwise, they are excluded from coverage  included in coverage statistics; otherwise, they are excluded from coverage
591  statistics.  statistics.
592  </p>  </p>
593    
594  <p>  <p>
595  In order to be recognized as a conditional directive, the comment must be  For example:
 formatted exactly as shown: it must be a line comment starting with <code>//</code>,  
 it must start in the first column, and it must be followed by <code>#JSCOVERAGE_IF</code>  
 or <code>#JSCOVERAGE_ENDIF</code> in uppercase letters with no intervening white space.  
596  </p>  </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>  <p>
609  For example, if you have some code in an <code>if</code> statement which is  You can exclude code from coverage statistics unconditionally by using
610  executed only in certain browsers, you can usually just repeat the condition in  <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
 a <code>//#JSCOVERAGE_IF</code> directive:  
611  </p>  </p>
612    
613  <pre class="sh_javascript">  <pre class="sh_javascript">
614    if (window.ActiveXObject) {  function f(x) {
615  //#JSCOVERAGE_IF window.ActiveXObject    if (x === null) {
616      return new ActiveXObject('Msxml2.XMLHTTP');  //#JSCOVERAGE_IF 0
617        throw 'error';
618  //#JSCOVERAGE_ENDIF  //#JSCOVERAGE_ENDIF
619    }    }
620      ...
621  </pre>  </pre>
622    
623  <p>  <p>
624  Alternatively, it may be easier to diagnose problems if you specify exactly  There is also a short form, which must appear on the line preceding an
625  which browsers you expect to execute the code in the conditional:  <code>if</code> statement:
626  </p>  </p>
627    
628  <pre class="sh_javascript">  <pre class="sh_javascript">
629    if (window.ActiveXObject) {  //#JSCOVERAGE_IF
630  //#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)  if (...) {
631      return new ActiveXObject('Msxml2.XMLHTTP');    ...
632  //#JSCOVERAGE_ENDIF  }
633    }  else if (...) {
634      ...
635    }
636    ...
637    else {
638      ...
639    }
640  </pre>  </pre>
641    
642  <p>  <p>
643  To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0</code> or  
644  <code>//#JSCOVERAGE_IF false</code>:  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>  </p>
650    
651  <pre class="sh_javascript">  <pre class="sh_javascript">
652  function f(s) {  function log(s) {
653    if (typeof(s) !== 'string') {  //#JSCOVERAGE_IF
654  //#JSCOVERAGE_IF 0    if (window.console) {
655      throw 'function f requires a string argument';      console.log(s);
656  //#JSCOVERAGE_ENDIF    }
657      else if (window.opera) {
658        opera.postError(s);
659      }
660      else {
661        throw 'no logging function available';
662    }    }
663  }  }
664  </pre>  </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>

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

  ViewVC Help
Powered by ViewVC 1.1.24