--- trunk/doc/manual.html 2008/09/13 03:56:45 157 +++ trunk/doc/manual.html 2008/09/13 04:01:44 158 @@ -500,6 +500,88 @@
Stop a running instance of the server. +

Advanced topics

+ +

Conditional directives

+ +

+Sometimes you may wish to exclude certain lines of code from coverage +statistics. Some lines of code may be executed only in certain browsers; other +lines should never be executed at all (they may only be present to detect +programming errors). You can use specially formatted comments in your code, +called conditional directives, to tell JSCoverage when to exclude +those lines from coverage statistics. These lines will be ignored in the +JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated +with the color yellow. +

+ +

+Conditional directives take the following form: +

+ +
+//#JSCOVERAGE_IF CONDITION
+...
+//#JSCOVERAGE_ENDIF
+
+ +

+The CONDITION is an ordinary JavaScript expression; if this +expression evaluates to true, then the lines of code between the +//#JSCOVERAGE_IF and //#JSCOVERAGE_ENDIF directives are +included in coverage statistics; otherwise, they are excluded from coverage +statistics. +

+ +

+In order to be recognized as a conditional directive, the comment must be +formatted exactly as shown: it must be a line comment starting with //, +it must start in the first column, and it must be followed by #JSCOVERAGE_IF +or #JSCOVERAGE_ENDIF in uppercase letters with no intervening white space. +

+ +

+For example, if you have some code in an if statement which is +executed only in certain browsers, you can usually just repeat the condition in +a //#JSCOVERAGE_IF directive: +

+ +
+  if (window.ActiveXObject) {
+//#JSCOVERAGE_IF window.ActiveXObject
+    return new ActiveXObject('Msxml2.XMLHTTP');
+//#JSCOVERAGE_ENDIF
+  }
+
+ +

+Alternatively, it may be easier to diagnose problems if you specify exactly +which browsers you expect to execute the code in the conditional: +

+ +
+  if (window.ActiveXObject) {
+//#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent)
+    return new ActiveXObject('Msxml2.XMLHTTP');
+//#JSCOVERAGE_ENDIF
+  }
+
+ +

+To exclude code from coverage statistics unconditionally, you can use //#JSCOVERAGE_IF 0 or +//#JSCOVERAGE_IF false: +

+ +
+function f(s) {
+  if (typeof(s) !== 'string') {
+//#JSCOVERAGE_IF 0
+    throw 'function f requires a string argument';
+//#JSCOVERAGE_ENDIF
+  }
+}
+
+

Caveats