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 a tabbed user interface:

Screenshot

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.

3. Generating the 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.

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.

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 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: 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 click on the "Summary" tab.

Screenshot

From the "Summary" tab, you can click the links to get a detailed view of a JavaScript source file.

Screenshot

Caveats

Copyright © 2007 siliconforks.com
Last updated July 8, 2007
jscoverage@siliconforks.com