/[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 158 by siliconforks, Sat Sep 13 04:01:44 2008 UTC
# 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>Conditional directives</h3>
506    
507    <p>
508    Sometimes you may wish to exclude certain lines of code from coverage
509    statistics. Some lines of code may be executed only in certain browsers; other
510    lines should never be executed at all (they may only be present to detect
511    programming errors).  You can use specially formatted comments in your code,
512    called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude
513    those lines from coverage statistics.  These lines will be ignored in the
514    JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated
515    with the color yellow.
516    </p>
517    
518    <p>
519    Conditional directives take the following form:
520    </p>
521    
522    <pre class="sh_javascript">
523    //#JSCOVERAGE_IF <var>CONDITION</var>
524    ...
525    //#JSCOVERAGE_ENDIF
526    </pre>
527    
528    <p>
529    The <var>CONDITION</var> is an ordinary JavaScript expression; if this
530    expression evaluates to <code>true</code>, then the lines of code between the
531    <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are
532    included in coverage statistics; otherwise, they are excluded from coverage
533    statistics.
534    </p>
535    
536    <p>
537    In order to be recognized as a conditional directive, the comment must be
538    formatted exactly as shown: it must be a line comment starting with <code>//</code>,
539    it must start in the first column, and it must be followed by <code>#JSCOVERAGE_IF</code>
540    or <code>#JSCOVERAGE_ENDIF</code> in uppercase letters with no intervening white space.
541    </p>
542    
543    <p>
544    For example, if you have some code in an <code>if</code> statement which is
545    executed only in certain browsers, you can usually just repeat the condition in
546    a <code>//#JSCOVERAGE_IF</code> directive:
547    </p>
548    
549    <pre class="sh_javascript">
550      if (window.ActiveXObject) {
551    //#JSCOVERAGE_IF window.ActiveXObject
552        return new ActiveXObject('Msxml2.XMLHTTP');
553    //#JSCOVERAGE_ENDIF
554      }
555    </pre>
556    
557    <p>
558    Alternatively, it may be easier to diagnose problems if you specify exactly
559    which browsers you expect to execute the code in the conditional:
560    </p>
561    
562    <pre class="sh_javascript">
563      if (window.ActiveXObject) {
564    //#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)
565        return new ActiveXObject('Msxml2.XMLHTTP');
566    //#JSCOVERAGE_ENDIF
567      }
568    </pre>
569    
570    <p>
571    To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0<code> or
572    <code>//#JSCOVERAGE_IF false<code>:
573    </p>
574    
575    <pre class="sh_javascript">
576    function f(s) {
577      if (typeof(s) !== 'string') {
578    //#JSCOVERAGE_IF 0
579        throw 'function f requires a string argument';
580    //#JSCOVERAGE_ENDIF
581      }
582    }
583    </pre>
584    
585  <h2>Caveats</h2>  <h2>Caveats</h2>
586    
587  <ul>  <ul>
# Line 519  Line 601 
601    
602  <address>  <address>
603    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>
604    Last updated May 21, 2008<br>    Last updated September 12, 2008<br>
605    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
606  </address>  </address>
607    

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

  ViewVC Help
Powered by ViewVC 1.1.24