JSCoverage is a tool used to measure code coverage in JavaScript programs.
JSCoverage has two components:
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 requires three steps:
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.
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.
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.
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.
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 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"
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 will be instructed to press the "Coverage Report" button.
From the coverage report summary, you can click the links to get a detailed view of a JavaScript source file.
.js files; it does not instrument code in <script>
elements in HTML files.
window.top, target="_top", etc.).