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:
jscoverage program to generate
instrumented JavaScript files.
jscoverage-server program, a simple web server that instruments
JavaScript code as it is served.
jscoverage-server can be run with the --proxy option to
act as a proxy server which instruments any JavaScript code proxied through it.
The jscoverage-server program (with or without the --proxy
option) has the advantage of being able to store coverage reports to the filesystem.
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.
jscoverage program
Using the jscoverage program requires the following steps:
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.
Open jscoverage.html in your web browser.
The page contains a tabbed user interface:
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.
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.
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:
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.
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.
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.
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
-V, --version
-v, --verbose
--exclude=PATH
jscoverage --exclude=PATH SOURCE-DIRECTORY DESTINATION-DIRECTORYcopies 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
jscoverage --no-instrument=PATH SOURCE-DIRECTORY DESTINATION-DIRECTORYcopies 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.
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
m=BOOLEAN, missing=BOOLEAN
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.
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.
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
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
-V, --version
-v, --verbose
--document-root=PATH
--proxy option.
--ip-address=ADDRESS
127.0.0.1. Specify
0.0.0.0 to use any address.
--no-instrument=URL
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
--proxy
--report-dir=PATH
jscoverage-report/ in the current directory.
--shutdown
.js files; it does not instrument code in <script>
elements in HTML files.
window.top, target="_top", etc.).