JSCoverage user manual

JSCoverage is a tool used to measure code coverage in JavaScript programs.

JSCoverage has two components:

  1. An executable program which is used to add instrumentation to JavaScript code.
  2. A web application which is used to execute instrumented code and generate a code coverage report.

Installing JSCoverage

You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On Windows you will require Cygwin or MinGW/MSYS.

You can extract and compile the code with the following commands:

tar jxvf jscoverage-0.1.tar.bz2
cd jscoverage-0.1
./configure
make

This will create the jscoverage executable (jscoverage.exe on Windows). You can install the executable in /usr/local with the command:

make install

Alternatively, since the program consists of only the single self-contained jscoverage executable, you may simply copy it to a suitable location in your PATH.

Using JSCoverage

Using JSCoverage requires three steps:

1. Instrumenting code

The first step is to add instrumentation to your JavaScript code. This is the function of the jscoverage executable. You must provide two arguments:

jscoverage SOURCE-DIRECTORY DESTINATION-DIRECTORY

SOURCE-DIRECTORY is the directory containing the JavaScript code to be instrumented, and DESTINATION-DIRECTORY is the name of the directory to which jscoverage should output the instrumented code. The jscoverage program will create DESTINATION-DIRECTORY if necessary and (recursively) copy SOURCE-DIRECTORY to DESTINATION-DIRECTORY, instrumenting any files ending with a .js extension.

For example, 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 DESTINATION-DIRECTORY/dir/index.html and an instrumented version of the script at DESTINATION-DIRECTORY/dir/script.js.

SOURCE-DIRECTORY/
  dir/
    index.html
    script.js

DESTINATION-DIRECTORY/
  dir/
    index.html
    script.js [instrumented]
  jscoverage.html

In addition, jscoverage creates a file called jscoverage.html which is used to execute the instrumented code.

2. Executing instrumented code

Open jscoverage.html in your web browser. The page contains two frames: the upper frame is used to display code coverage data, while the lower frame is used to display pages with instrumented scripts.

Screenshot

Initially the lower frame will be empty. You can load a page into this frame by entering its URL into the input field in the upper frame. For example, to load the file DESTINATION-DIRECTORY/dir/index.html, you can enter the relative URL dir/index.html into the input field.

3. Generating the coverage report

Once the JavaScript code in the page in the lower frame has been executed, push the "Coverage Report" button in the upper frame. This will generate the code coverage report.

As long as you do not reload the top-level frameset (the jscoverage.html page), the coverage report statistics are cumulative. If you execute more JavaScript (e.g., by clicking on a link to another scripted page, or by reloading the lower frame containing a scripted page) and press "Coverage Report" button again, a new report will be generated which combines the statistics from the previous report with any newly generated statistics. Reloading the top-level frameset resets all code coverage statistics to zero.

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 instrumented code

You can load the file doc/instrumented/jscoverage.html in your web browser and then type the URL for the instrumented code in the input field in the top frame. 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: you have to select one of the radio buttons to execute the code.

Screenshot

3. Generating the coverage report

Once you have executed the JavaScript code, you will be instructed to press the "Coverage Report" button.

Screenshot

From the coverage report summary, you can click the links to get a detailed view of a JavaScript source file.

Screenshot

Caveats

Copyright © 2007 siliconforks.com
Last updated May 26, 2007
jscoverage@siliconforks.com