/[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 225 by siliconforks, Fri Oct 3 02:28:38 2008 UTC revision 240 by siliconforks, Fri Oct 3 23:51:32 2008 UTC
# Line 544  Line 544 
544  of the test suite can simply be loaded directly in a web browser.  of the test suite can simply be loaded directly in a web browser.
545  </p>  </p>
546    
547  <h3>Conditional directives</h3>  <h3>Ignoring certain lines of code</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 be present only 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 to
554  called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude  tell JSCoverage to ignore certain lines of code. These lines will not be
555  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
556  JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated  be indicated with the color yellow.
 with the color yellow.  
557  </p>  </p>
558    
559  <p>  <p>
560  Conditional directives take the following form:  These comments take the following form:
561  </p>  </p>
562    
563  <pre class="sh_javascript">  <pre class="sh_javascript">
# Line 568  Line 567 
567  </pre>  </pre>
568    
569  <p>  <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  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  expression evaluates to <code>true</code>, then the lines of code between the
579  <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are  <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
580  included in coverage statistics; otherwise, they are excluded from coverage  included in coverage statistics; otherwise, they are excluded from coverage
581  statistics.  statistics.
582  </p>  </p>
583    
584  <p>  <p>
585  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.  
586  </p>  </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>  <p>
599  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
600  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:  
601  </p>  </p>
602    
603  <pre class="sh_javascript">  <pre class="sh_javascript">
604    if (window.ActiveXObject) {  function f(x) {
605  //#JSCOVERAGE_IF window.ActiveXObject    if (x === null) {
606      return new ActiveXObject('Msxml2.XMLHTTP');  //#JSCOVERAGE_IF 0
607        throw 'error';
608  //#JSCOVERAGE_ENDIF  //#JSCOVERAGE_ENDIF
609    }    }
610      ...
611  </pre>  </pre>
612    
613  <p>  <p>
614  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
615  which browsers you expect to execute the code in the conditional:  <code>if</code> statement:
616  </p>  </p>
617    
618  <pre class="sh_javascript">  <pre class="sh_javascript">
619    if (window.ActiveXObject) {  //#JSCOVERAGE_IF
620  //#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)  if (...) {
621      return new ActiveXObject('Msxml2.XMLHTTP');    ...
622  //#JSCOVERAGE_ENDIF  }
623    }  else if (...) {
624      ...
625    }
626    ...
627    else {
628      ...
629    }
630  </pre>  </pre>
631    
632  <p>  <p>
633  To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0</code> or  
634  <code>//#JSCOVERAGE_IF false</code>:  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>  </p>
640    
641  <pre class="sh_javascript">  <pre class="sh_javascript">
642  function f(s) {  function log(s) {
643    if (typeof(s) !== 'string') {  //#JSCOVERAGE_IF
644  //#JSCOVERAGE_IF 0    if (window.console) {
645      throw 'function f requires a string argument';      console.log(s);
646  //#JSCOVERAGE_ENDIF    }
647      else if (window.opera) {
648        opera.postError(s);
649      }
650      else {
651        throw 'no logging function available';
652    }    }
653  }  }
654  </pre>  </pre>
655    
656  <p>  <p>
657  Currently, conditional directives are ignored in stored coverage reports.  Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
658  </p>  </p>
659    
660  <h2>Caveats</h2>  <h2>Caveats</h2>
Legend:
Removed from v.225  
changed lines
  Added in v.240
  ViewVC Help
Powered by ViewVC 1.1.24