--- trunk/doc/manual.html 2008/10/20 07:57:04 326 +++ trunk/doc/manual.html 2008/10/22 09:40:53 328 @@ -3,17 +3,17 @@ JSCoverage user manual - - - + + +

JSCoverage user manual

-JSCoverage is a tool that measures code coverage in JavaScript programs. +JSCoverage is a tool that measures code coverage for JavaScript programs.

@@ -78,7 +78,15 @@

Using the jscoverage program

-Using the jscoverage program involves the following steps: +To demonstrate how the jscoverage program works, we will use the +trivial example JavaScript code located in the +doc/example/ directory of the JSCoverage distribution. You can run +this example by viewing the file doc/example/index.html in your web browser. +

+ +

+Generating code coverage statistics for this example using the +jscoverage program involves the following steps:

1. Instrumenting code

@@ -102,7 +110,7 @@

-For example, if you have a file +The directory structure under SOURCE-DIRECTORY is preserved, so that if you have a file SOURCE-DIRECTORY/dir/index.html referencing the script SOURCE-DIRECTORY/dir/script.js, then jscoverage will create a copy of the HTML file at @@ -136,10 +144,44 @@ which is used to execute the instrumented code.

+

+To instrument the code in the doc/example/ directory, execute the +following command from the top-level directory of the JSCoverage distribution: +

+ +
+jscoverage doc/example doc/instrumented
+
+ +

+This will create the directory doc/instrumented/ and place an +instrumented copy of the code from doc/example/ in +doc/instrumented/. +

+ + + + + + + +
+doc/example/
+  index.html
+  script.js
+
+
+doc/instrumented/
+  index.html
+  script.js [instrumented]
+  jscoverage.html
+
+

2. Executing the instrumented code in a web browser

-Open jscoverage.html in your web browser. +Open the generated jscoverage.html file +(doc/instrumented/jscoverage.html) in your web browser. The page contains a tabbed user interface:

@@ -156,79 +198,29 @@

The "Browser" tab contains an <iframe>, which is initially empty. You can load a page into this frame by -entering its URL into the "URL" input field. For example, to load -the file DESTINATION-DIRECTORY/dir/index.html, you can -enter the relative URL dir/index.html into the input field. +entering its URL into the "URL" input field. You can load any page located in DESTINATION-DIRECTORY/ or a subdirectory underneath DESTINATION-DIRECTORY/; loading a page from outside DESTINATION-DIRECTORY/, or from a foreign web server, will give unexpected results.

-

3. Generating a coverage report

-

-Once the JavaScript code in the page in the "Browser" tab has been executed, click on -the "Summary" tab. This will display the current code coverage statistics. +For example, you can load the file doc/instrumented/index.html by typing +index.html in the "URL" input field (relative URLs are acceptable).

-As long as you do not reload the -jscoverage.html page, the coverage report statistics are -cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to -another scripted page, or by reloading the frame containing a scripted -page) and switch to the "Summary" tab again, -the coverage report will combine the statistics from the previous report with any newly generated statistics. -Reloading jscoverage.html resets all code coverage statistics to zero. +Alternatively, you can load a page into the <iframe> by +appending the page URL to the query string of the jscoverage.html URL. +For example, appending ?index.html to the jscoverage.html URL +will cause the index.html file to be loaded automatically.

-

Example

- -

-The JSCoverage distribution comes with a trivial example program in the doc/example directory. -You can view the file doc/example/index.html in your web browser to run the (uninstrumented) program. -To instrument this program, follow these steps: -

- -

1. Instrumenting code

- -

-From the main distribution directory, execute the command: -

- -
-jscoverage doc/example doc/instrumented
-
- -

-This will create the directory doc/instrumented and -place an instrumented copy of the code from doc/example in doc/instrumented. -

- -

2. Executing the instrumented code in a web browser

- -

-You can load the file doc/instrumented/jscoverage.html in your web browser and type -the URL for the instrumented code in the "URL" input field. Since a relative URL is accepted, you -can simply type index.html to load the page. -

- -

-Alternatively, you can append the URL to the query string of the -jscoverage.html URL; for example, if you are in the main JSCoverage -directory and the Firefox executable is in your PATH, you can load -the jscoverage.html frameset and the index.html page -all in one command line: -

- -
-firefox "doc/instrumented/jscoverage.html?index.html"
-
-

Screenshot

-For this particular page, the JavaScript does not execute automatically: +For this example, the JavaScript does not execute automatically: you have to select one of the radio buttons to execute the code.

@@ -237,8 +229,8 @@

3. Generating a coverage report

-Once you have executed the JavaScript code, you are instructed to click on the -"Summary" tab. +Once the JavaScript code in the page in the "Browser" tab has been executed, click on +the "Summary" tab. This will display the current code coverage statistics.

Screenshot

@@ -255,6 +247,16 @@

Screenshot

+

+As long as you do not reload the +jscoverage.html page, the coverage report statistics are +cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to +another scripted page, or by reloading the frame containing a scripted +page) and switch to the "Summary" tab again, +the coverage report will combine the statistics from the previous report with any newly generated statistics. +Reloading jscoverage.html resets all code coverage statistics to zero. +

+

Inverted mode

@@ -299,15 +301,16 @@

An example is located in the doc/example-inverted directory. -You can instrument the code and launch the index.html page: +You can instrument the code with the jscoverage program:

 jscoverage doc/example-inverted doc/instrumented-inverted
-firefox "doc/instrumented-inverted/index.html"
 

+You can load the page doc/instrumented-inverted/index.html +directly in your web browser. From this page, you select one of the radio buttons and then click the "Coverage report" button to launch the JSCoverage report.