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.3.1.tar.bz2
cd jscoverage-0.3.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. Running instrumented code in the web application

Open jscoverage.html in your web browser. The page contains a tabbed user interface:

• The "Browser" tab is used to display pages with instrumented scripts.
• The "Summary" tab is used to display code coverage data.
• The "Source" tab is used to display JavaScript code, showing the number of times each line of code was executed.
• The "About" tab displays information about the current version of JSCoverage.

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

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

3. Generating the coverage report

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

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

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

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.

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.

Caveats

• JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed. Expect instrumented code to take at least twice as much time to run.
• JSCoverage currently instruments only .js files; it does not instrument code in <script> elements in HTML files.
• HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
• JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more 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.