Skip to content

Commit

Permalink
Add programmatic report storage and some re-arrangement
Browse files Browse the repository at this point in the history
  • Loading branch information
@tntim96
tntim96 committed Oct 24, 2012
1 parent f7bcaaf commit 2ef40fe
Showing 1 changed file with 90 additions and 46 deletions.
136 changes: 90 additions & 46 deletions doc/manual/manual.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,32 +18,38 @@
For an overview of the basic workings of of JSCover, see the
<a href="http://siliconforks.com/jscoverage/manual.html" target="_blank">JSCoverage documentation</a>
</text>
<text>
JSCover is a tool that measures code coverage for JavaScript programs.
It is based on the popular JSCoverage, with the C++/SpiderMonkey instrumentation replaced with Java/Rhino.
</text>
<text>
JSCover works by adding instrumentation to JavaScript code before it is executed in a web browser.
JSCover provides several alternative ways of doing this:
<ul>
<li>The simplest method is to use the file-system mode program to generate instrumented JavaScript
files.
</li>
<li>Alternatively, you can use the server mode, a simple web server that instruments JavaScript code as
it is served.
</li>
<li>Finally, server mode can be run with the --proxy option to act as a proxy server which instruments
any JavaScript code proxied through it.
</li>
</ul>
</text>
<text>
The server mode has two advantages:
<ol>
<li>can store coverage reports to the filesystem (with/without the proxy option)</li>
<li>can include unloaded/untested JavaScript (only without the proxy option)</li>
</ol>
</text>
<item>
<heading id="introduction">Introduction</heading>
<text>
JSCover is a tool that measures code coverage for JavaScript programs.
It is based on the popular JSCoverage, with the C++/SpiderMonkey instrumentation replaced with
Java/Rhino.
</text>
<text>
JSCover works by adding instrumentation to JavaScript code before it is executed in a web browser.
JSCover provides several alternative ways of doing this:
<ul>
<li>The simplest method is to use the file-system mode program to generate instrumented JavaScript
files.
</li>
<li>Alternatively, you can use the server mode, a simple web server that instruments JavaScript code
as
it is served.
</li>
<li>Finally, server mode can be run with the --proxy option to act as a proxy server which
instruments
any JavaScript code proxied through it.
</li>
</ul>
</text>
<text>
The server mode has two advantages:
<ol>
<li>can store coverage reports to the filesystem (with/without the proxy option)</li>
<li>can include unloaded/untested JavaScript (only without the proxy option)</li>
</ol>
</text>
</item>
<item>
<heading id="packaging">Packaging</heading>
<text>
Expand Down Expand Up @@ -118,9 +124,9 @@
<item>
<heading id="serverMode">Server Mode</heading>
<text>
<code>java -jar JSCover.jar -ws [OPTIONS]</code>
<code>java -jar JSCover-all.jar -ws [OPTIONS]</code>
For example:
<code>java -jar JSCover.jar -ws --port=80 --no-instrument=lib --no-instrument=test</code>
<code>java -jar JSCover-all.jar -ws --port=80 --no-instrument=lib --no-instrument=test</code>
</text>
<text>
<table>
Expand Down Expand Up @@ -181,13 +187,66 @@
</tr>
</table>
</text>
<item>
<heading id="implementationStoreReport">Storing reports</heading>
<text>
The store button triggers the POSTing of the coverage data to the server in JSON format. The following
will then occur:
<ul>
<li>If a JSON file, jscoverage.json, already exists, the coverage data will be merged</li>
<li>
If no JSON file exists, but --include-unloaded-js is present, all un-loaded JavaScript
files will be merged with the submitted JSON and saved to the report
</li>
<li>If neither of the above is true, the raw JSON is stored</li>
</ul>
</text>
</item>
<item>
<heading id="jsReportStorage">Programmatic Report Storage</heading>
<text>
If you are executing a test suite using the server-mode, you can store a coverage report
programmatically by having your test suite call the jscoverage_report function (automatically generated
by JSCover) after all your tests have finished running:

<code>if (window.jscoverage_report) {
jscoverage_report();
}</code>

You can specify the name of the directory in which to store the report by passing the name as a parameter to the
jscoverage_report function:

<code>if (window.jscoverage_report) {
// determine the directory name based on the browser
var directory;
if (/MSIE/.test(navigator.userAgent)) {
directory = 'IE';
}
else {
directory = 'other';
}
jscoverage_report(directory);
}</code>

This directory will be a subdirectory under the jscoverage-report/ directory (or whatever is specified
with the --report-dir option). Using the above example, the report would be stored to either
jscoverage-report/IE/ or jscoverage-report/other/.
</text>
<text>
It is not necessary that your test suite be executed within the jscoverage.html web interface to store a
coverage report. The URL of the test suite can simply be loaded directly in a web browser.
</text>
<text>
The example in doc/example-jsunit/ demonstrates storing coverage reports programmatically.
</text>
</item>
</item>
<item>
<heading id="fileMode">File Mode</heading>
<text>
<code>java -jar JSCover.jar -fs [OPTIONS] SOURCE-DIRECTORY DESTINATION-DIRECTORY</code>
<code>java -jar JSCover-all.jar -fs [OPTIONS] SOURCE-DIRECTORY DESTINATION-DIRECTORY</code>
For example:
<code>java -jar JSCover.jar -fs --no-instrument=lib --no-instrument=test</code>
<code>java -jar JSCover-all.jar -fs --no-instrument=lib --no-instrument=test</code>
</text>
<text>
<table>
Expand All @@ -207,7 +266,7 @@
<td>Specify URLs not to be instrumented. Can be specified multiple times.</td>
</tr>
<tr>
<td>---exclude=PATH</td>
<td>--exclude=PATH</td>
<td>None</td>
<td>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
Expand Down Expand Up @@ -458,20 +517,5 @@ alert('Hello World!');
is incremented. The header code manages the declaration of _$jscoverage.
</text>
</item>
<item>
<heading id="implementationStoreReport">Storing reports</heading>
<text>
This only works in server mode. The store button triggers the POSTing of the coverage
data to the server in JSON format. The following will then occur:
<ul>
<li>If a JSON file, jscoverage.json, already exists, the coverage data will be merged</li>
<li>
If no JSON file exists, but --include-unloaded-js is set, all un-loaded JavaScript
files will be merged with the submitted JSON and saved to the report.
</li>
<li>If neither of the above is true, the raw JSON is stored.</li>
</ul>
</text>
</item>
</item>
</document>

0 comments on commit 2ef40fe

Please sign in to comment.