--- trunk/doc/manual.html 2008/10/03 23:50:45 239 +++ trunk/doc/manual.html 2008/10/03 23:51:32 240 @@ -544,21 +544,20 @@ of the test suite can simply be loaded directly in a web browser.

-

Conditional directives

+

Ignoring certain lines of code

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 be present only 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. +programming errors). You can use specially formatted comments in your code to +tell JSCoverage to ignore certain lines of code. These lines will not be +included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will +be indicated with the color yellow.

-Conditional directives take the following form: +These comments take the following form:

@@ -568,64 +567,94 @@
 

+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. +

+ +

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 +//#JSCOVERAGE_IF and //#JSCOVERAGE_ENDIF comments 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:

+
+function log(s) {
+  if (window.console) {
+//#JSCOVERAGE_IF window.console
+    console.log(s);
+//#JSCOVERAGE_ENDIF
+  }
+}
+
+

-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: +You can exclude code from coverage statistics unconditionally by using +#JSCOVERAGE_IF 0 or #JSCOVERAGE_IF false:

-  if (window.ActiveXObject) {
-//#JSCOVERAGE_IF window.ActiveXObject
-    return new ActiveXObject('Msxml2.XMLHTTP');
+function f(x) {
+  if (x === null) {
+//#JSCOVERAGE_IF 0
+    throw 'error';
 //#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: +There is also a short form, which must appear on the line preceding an +if statement:

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

-To exclude code from coverage statistics unconditionally, you can use //#JSCOVERAGE_IF 0 or -//#JSCOVERAGE_IF false: + +In this form, there is no condition on the //#JSCOVERAGE_IF line +and no //#JSCOVERAGE_ENDIF. You use this form to tell JSCoverage +that you expect only one branch of the if statement to be executed; +coverage statistics will not be collected for the other branch(es). For +example:

-function f(s) {
-  if (typeof(s) !== 'string') {
-//#JSCOVERAGE_IF 0
-    throw 'function f requires a string argument';
-//#JSCOVERAGE_ENDIF
+function log(s) {
+//#JSCOVERAGE_IF
+  if (window.console) {
+    console.log(s);
+  }
+  else if (window.opera) {
+    opera.postError(s);
+  }
+  else {
+    throw 'no logging function available';
   }
 }
 

-Currently, conditional directives are ignored in stored coverage reports. +Currently, //#JSCOVERAGE_IF comments are not recorded in stored coverage reports.

Caveats