JSCoverage user manual

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

JSCoverage works by adding instrumentation to JavaScript code before it is executed in a web browser. JSCoverage provides several alternative ways of doing this:

The jscoverage-server program (with or without the --proxy option) has the advantage of being able to store coverage reports to the filesystem.

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.4.tar.bz2
cd jscoverage-0.4/
./configure
make

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

make install

Alternatively, you may simply copy the jscoverage executable and/or the jscoverage-server executable to a suitable location in your PATH.

Using the jscoverage program

Using the jscoverage program requires the following steps:

1. Instrumenting code

The first step is to add instrumentation to your JavaScript code. You do this by executing jscoverage with 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 the instrumented code in a web browser

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

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 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: you have to select one of the radio buttons to execute the code.

Screenshot

3. Generating a coverage report

Once you have executed the JavaScript code, you are instructed to click on the "Summary" tab.

Screenshot

You can click the checkbox to show a list of statements missed during execution.

Screenshot

You can click one of the links to get a detailed view of a JavaScript source file.

Screenshot

Inverted mode

In some situations it may be difficult to execute your code within the JSCoverage "Browser" tab. For example, the code may assume that it is running in the top-level browser window, generating errors if it is executed from within a frame. JSCoverage has an alternative mode of operation, called inverted mode, which may be useful in this case.

Normally you load jscoverage.html in your web browser, and in its "Browser" tab you launch your test code. In inverted mode, you do the opposite: you load your test page directly in your web browser, and from there you launch JSCoverage. To do this you need to add some code to your test page:

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

The "path/to/jscoverage.html" should be a URL pointing to the location of the jscoverage.html file (remember, this will be in the top level of the DESTINATION-DIRECTORY you specified when running the jscoverage executable).

You can place this code wherever you like in your page: for example, you could attach it to a button:

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

Note that you must use a window.open call; simply making a link to jscoverage.html is not sufficient.

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

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

From this page, you select one of the radio buttons and then click the "Coverage report" button to launch the JSCoverage report.

jscoverage command line options

The jscoverage program accepts the following options:

-h, --help
Display a brief help message.
-V, --version
Display the version of the program.
-v, --verbose
Explain what is being done.
--exclude=PATH
The command
jscoverage --exclude=PATH SOURCE-DIRECTORY DESTINATION-DIRECTORY
copies SOURCE-DIRECTORY to DESTINATION-DIRECTORY recursively, but does not copy SOURCE-DIRECTORY/PATH. PATH must be a complete path relative to SOURCE-DIRECTORY. PATH can be a file or a directory (in which case the directory and its entire contents are skipped). This option may be given multiple times.
--no-instrument=PATH
The command
jscoverage --no-instrument=PATH SOURCE-DIRECTORY DESTINATION-DIRECTORY
copies SOURCE-DIRECTORY to DESTINATION-DIRECTORY recursively, but does not instrument any JavaScript code in SOURCE-DIRECTORY/PATH. PATH must be a complete path relative to SOURCE-DIRECTORY. PATH can be a (JavaScript) file or a directory (in which case any JavaScript files located anywhere underneath the directory are not instrumented). This option may be given multiple times.

Query string options

When accessing jscoverage.html in a web browser, you may provide a query string consisting of options separated by ampersand (&) or semicolon (;). Any option not containing an equals sign (=) is considered to be a URL which will be loaded in the "Browser" tab.

u=URL, url=URL
Load URL in the "Browser" tab. (This is the same as specifying an option without an equals sign.)
m=BOOLEAN, missing=BOOLEAN
Determines whether to initially display the "Missing" column in the "Summary" tab. BOOLEAN can be true, t, yes, y, on, 1 (to display the "Missing" column), or false, f, no, n, off, 0 (to hide the "Missing" column). By default, the "Missing" column is not displayed.

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:

  cd doc/example
  jscoverage-server --verbose

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 JavaScript code, so that code coverage data will be gathered as the code is executed in your browser.

The web interface is slightly different from that generated by the jscoverage program: it has a new tab named "Store". To store coverage data, click the "Store" tab.

Screenshot

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.

If you use the "Store" tab again to store coverage data, the new data will be merged with the previous data in the jscoverage-report/ directory. This can be useful, for instance, if you wish to run a set of tests in different browsers and generate an aggregate report which combines the data for all of them.

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:

  jscoverage-server --shutdown

Using jscoverage-server --proxy

To use jscoverage-server as a proxy server, use the --proxy option:

  jscoverage-server --verbose --proxy

Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080. You can then generate code coverage data for a web page on the server example.com by accessing the JSCoverage web interface at the special URL http://example.com/jscoverage.html. Note that this URL is not provided by the example.com server; it is automatically generated by the proxy server whenever a URL with path /jscoverage.html is requested.

jscoverage-server command line options

-h, --help
Display a brief help message.
-V, --version
Display the version of the program.
-v, --verbose
Explain what is being done.
--document-root=PATH
Serve web content from the directory given by PATH. The default is the current directory. This option may not be given with the --proxy option.
--ip-address=ADDRESS
Run the server on the IP address given by ADDRESS. The default is 127.0.0.1. Specify 0.0.0.0 to use any address.
--no-instrument=URL
Do not instrument JavaScript code from URL. If you are running jscoverage-server with the --proxy option, URL should be a full URL. For example:
jscoverage-server --proxy --no-instrument=http://example.com/scripts/
Without --proxy, URL should be only the path portion of a URL:
jscoverage-server --no-instrument=/scripts/
This option may be given multiple times.
--port=PORT
Run the server on the port given by PORT. The default is port 8080.
--proxy
Run as a proxy server.
--report-dir=PATH
Use the directory given by PATH for storing coverage reports. The default is jscoverage-report/ in the current directory.
--shutdown
Stop a running instance of the server.

Caveats

Copyright © 2007, 2008 Silicon Forks siliconforks.com
Last updated May 21, 2008
jscoverage@siliconforks.com