--- trunk/doc/manual.html 2008/09/29 05:16:13 197 +++ trunk/doc/manual.html 2008/09/29 05:16:31 198 @@ -2,14 +2,18 @@ JSCoverage user manual - + + + + + - +

JSCoverage user manual

-JSCoverage is a tool used to measure code coverage in JavaScript programs. +JSCoverage is a tool that measures code coverage in JavaScript programs.

@@ -74,7 +78,7 @@

Using the jscoverage program

-Using the jscoverage program requires the following steps: +Using the jscoverage program involves the following steps:

1. Instrumenting code

@@ -268,8 +272,8 @@ you launch JSCoverage. To do this you need to add some code to your test page:

-
-window.open("path/to/jscoverage.html");
+
+window.open('path/to/jscoverage.html');
 

@@ -284,8 +288,8 @@ attach it to a button:

-
-<button onclick='window.open("path/to/jscoverage.html");'>Coverage report</button>
+
+<button onclick="window.open('path/to/jscoverage.html');">Coverage report</button>
 

@@ -371,9 +375,9 @@

Using the jscoverage-server program

-The jscoverage-server program is a simple web server which will -serve files from the current directory. You can use -jscoverage-server to serve doc/example: +The jscoverage-server program is a simple web server. You can use +jscoverage-server to serve files from the doc/example/ +directory:

@@ -382,24 +386,14 @@
 

-By default, the server runs on port 8080. URLs are mapped to files in the -doc/example directory: e.g., the URL -http://127.0.0.1:8080/index.html can be used to request -doc/example/index.html. In addition, the special URL -http://127.0.0.1:8080/jscoverage.html provides the JSCoverage web -interface. Note that it is not necessary that a file named -jscoverage.html exist; the JSCoverage web -interface is built into the server, and it will automatically be served when the special -/jscoverage.html URL is requested. -

- -

-You can use the /jscoverage.html URL in the same way as the -jscoverage.html file generated by the jscoverage -program. For example, you can visit the URL -http://127.0.0.1:8080/jscoverage.html?index.html to execute the -JavaScript associated with the index.html page. The -jscoverage-server program automatically instruments all served +Once the server is running, you can access the JSCoverage web interface by +visiting the URL http://127.0.0.1:8080/jscoverage.html, and you can +load the doc/example/index.html file by entering +index.html in the "URL" input field. (Or you can do this all in +one step by loading the URL +http://127.0.0.1:8080/jscoverage.html?index.html in your web +browser.) The +jscoverage-server program automatically instruments any served JavaScript code, so that code coverage data will be gathered as the code is executed in your browser.

@@ -415,7 +409,7 @@

When you click the "Store" button, the coverage data will be saved to a directory named jscoverage-report/. You can view this stored report at any time by opening the file jscoverage-report/jscoverage.html in -your web browser - you don't need the jscoverage-server running to see it. +your web browser - you don't need the jscoverage-server running to access it.

@@ -426,17 +420,6 @@

-You can also store data programmatically from your tests by adding the following to your -JavaScript code: -

- -
-if (top.jscoverage_report) {
-  top.jscoverage_report();
-}
-
- -

You can stop the server by running another instance of jscoverage-server with the --shutdown option:

@@ -502,12 +485,53 @@

Advanced topics

+

Storing coverage reports programmatically

+ +

+If you are executing a test suite using jscoverage-server, you can +store a coverage report programmatically by having your test suite call the +jscoverage_report function (automatically generated by +jscoverage-server) after all your tests have finished running: +

+ +
+if (top.jscoverage_report) {
+  top.jscoverage_report();
+}
+
+ +

+You can specify the name of the directory in which to store the report by +passing the name as a parameter to the jscoverage_report function: +

+ +
+if (top.jscoverage_report) {
+  // determine the directory name based on the browser
+  var directory;
+  if (/MSIE/.test(navigator.userAgent)) {
+    directory = 'IE';
+  }
+  else {
+    directory = 'other';
+  }
+  top.jscoverage_report(directory);
+}
+
+ +

+This directory will be a subdirectory under the jscoverage-report/ +directory (or whatever is specified with the --report-dir option). +Using the above example, the report would be stored to either +jscoverage-report/IE/ or jscoverage-report/other/. +

+

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 +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 @@ -596,7 +620,7 @@ statements, you may get strange results.

  • JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially those which try to access the top-level frame (window.top, target="_top", etc.). -
  • JSCoverage is alpha software. Use at your own risk. +
  • JSCoverage is distributed without any warranty. See the license for more details.