trunk/doc/manual.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>JSCoverage user manual</title>
<link type="text/css" href="doc.css" rel="stylesheet">
</head>
<body>

<h1>JSCoverage user manual</h1>

<p>
JSCoverage is a tool used to measure code coverage in JavaScript
programs.
</p>

<p>
JSCoverage has two components:
</p>

<ol>
<li>An executable program which is used to add instrumentation to JavaScript code.
<li>A web application which is used to execute instrumented code and generate a
code coverage report.
</ol>

<h2>Installing JSCoverage</h2>

<p>
You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On
Windows you will require <a href="http://cygwin.com/">Cygwin</a> or <a
href="http://mingw.org/">MinGW/MSYS</a>.
</p>

<p>
You can extract and compile the code with the following commands:
</p>

<pre>
tar jxvf jscoverage-0.1.tar.bz2
cd jscoverage-0.1
./configure
make
</pre>

<p>
This will create the <code>jscoverage</code> executable (<code>jscoverage.exe</code> on Windows).
You can install the executable in <code>/usr/local</code> with the command:
</p>

<pre>
make install
</pre>

<p>
Alternatively, since the program consists of only the single self-contained
<code>jscoverage</code> executable, you may simply copy it to a suitable location
in your <code>PATH</code>.
</p>

<h2>Using JSCoverage</h2>

<p>
Using JSCoverage requires three steps:
</p>

<h3>1. Instrumenting code</h3>

<p>
The first step is to add instrumentation to your JavaScript code.  This is the function of the
<code>jscoverage</code> executable.  You must provide two arguments:
</p>

<pre>
jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
</pre>

<p>
<var>SOURCE-DIRECTORY</var> is the directory containing the JavaScript code to be instrumented,
and <var>DESTINATION-DIRECTORY</var> is the name of the
directory to which <code>jscoverage</code> should output the instrumented code.
The <code>jscoverage</code> program will create <var>DESTINATION-DIRECTORY</var> if necessary and (recursively) copy
<var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>, instrumenting
any files ending with a <code>.js</code> extension.
</p>

<p>
For example, if you have a file
<code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
<code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
<code>jscoverage</code> will create a copy of the HTML file at
<code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code> and an instrumented
version of the script at
<code><var>DESTINATION-DIRECTORY</var>/dir/script.js</code>.
</p>

<table>
<tr>
<td><pre>
<var>SOURCE-DIRECTORY</var>/
  dir/
    index.html
    script.js

</pre></td>
<td class="arrow">&rarr;</td>
<td><pre>
<var>DESTINATION-DIRECTORY</var>/
  dir/
    index.html
    script.js [instrumented]
  jscoverage.html
</pre></td>
</tr>
</table>

<p>
In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
which is used to execute the instrumented code.
</p>

<h3>2. Running instrumented code in the web application</h3>

<p>
Open <code>jscoverage.html</code> in your web browser.
The page contains a tabbed user interface:
</p>

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

<img src="screenshot.png" alt="Screenshot">

<p>
The "Browser" tab contains an <code>&lt;iframe&gt;</code>, 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 <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can
enter the relative URL <code>dir/index.html</code> into the input field.
</p>

<h3>3. Generating the coverage report</h3>

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

<p>
As long as you do not reload the
<code>jscoverage.html</code> 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 <code>jscoverage.html</code> resets all code coverage statistics to zero.
</p>

<h2>Example</h2>

<p>
The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.
You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.
To instrument this program, follow these steps:
</p>

<h3>1. Instrumenting code</h3>

<p>
From the main distribution directory, execute the command:
</p>

<pre>
jscoverage doc/example doc/instrumented
</pre>

<p>
This will create the directory <code>doc/instrumented</code> and
place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.
</p>

<h3>2. Executing instrumented code</h3>

<p>
You can load the file <code>doc/instrumented/jscoverage.html</code> 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 <code>index.html</code> to load the page.
</p>

<p>
Alternatively, you can append the URL to the query string of the
<code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage
directory and the Firefox executable is in your <code>PATH</code>, you can load
the <code>jscoverage.html</code> frameset and the <code>index.html</code> page
all in one command line:
</p>

<pre>
firefox "doc/instrumented/jscoverage.html?index.html"
</pre>

<img src="screenshot2.png" alt="Screenshot">

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

<img src="screenshot3.png" alt="Screenshot">

<h3>3. Generating the coverage report</h3>

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

<img src="screenshot4.png" alt="Screenshot">

<p>
From the "Summary" tab, you can click the links to get a detailed view of a JavaScript source file.
</p>

<img src="screenshot5.png" alt="Screenshot">

<h2>Inverted mode</h2>

<p>
In some circumstances 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 <dfn>inverted
mode</dfn>, which may be useful in this situation.
</p>

<p>
Normally you load <code>jscoverage.html</code> 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:
</p>

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

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

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

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

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

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

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

<h2>Caveats</h2>

<ul>
<li>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.
<li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
elements in HTML files.
<li>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.
<li>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.
<li>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 (<code>window.top</code>, <code>target="_top"</code>, etc.).
<li>JSCoverage is alpha software.  Use at your own risk.
</ul>

<address>
  Copyright &copy; 2007 siliconforks.com<br>
  Last updated July 8, 2007<br>
  <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
</address>

</body>
</html>
1	siliconforks	2	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2			<html>
3			<head>
4			<title>JSCoverage user manual</title>
5			<link type="text/css" href="doc.css" rel="stylesheet">
6			</head>
7			<body>
8
9			<h1>JSCoverage user manual</h1>
10
11			<p>
12			JSCoverage is a tool used to measure code coverage in JavaScript
13			programs.
14			</p>
15
16			<p>
17			JSCoverage has two components:
18			</p>
19
20			<ol>
21			<li>An executable program which is used to add instrumentation to JavaScript code.
22			<li>A web application which is used to execute instrumented code and generate a
23			code coverage report.
24			</ol>
25
26			<h2>Installing JSCoverage</h2>
27
28			<p>
29			You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On
30			Windows you will require <a href="http://cygwin.com/">Cygwin</a> or <a
31			href="http://mingw.org/">MinGW/MSYS</a>.
32			</p>
33
34			<p>
35			You can extract and compile the code with the following commands:
36			</p>
37
38			<pre>
39			tar jxvf jscoverage-0.1.tar.bz2
40			cd jscoverage-0.1
41			./configure
42			make
43			</pre>
44
45			<p>
46			This will create the <code>jscoverage</code> executable (<code>jscoverage.exe</code> on Windows).
47			You can install the executable in <code>/usr/local</code> with the command:
48			</p>
49
50			<pre>
51			make install
52			</pre>
53
54			<p>
55			Alternatively, since the program consists of only the single self-contained
56			<code>jscoverage</code> executable, you may simply copy it to a suitable location
57			in your <code>PATH</code>.
58			</p>
59
60			<h2>Using JSCoverage</h2>
61
62			<p>
63			Using JSCoverage requires three steps:
64			</p>
65
66			<h3>1. Instrumenting code</h3>
67
68			<p>
69			The first step is to add instrumentation to your JavaScript code. This is the function of the
70			<code>jscoverage</code> executable. You must provide two arguments:
71			</p>
72
73			<pre>
74			jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
75			</pre>
76
77			<p>
78			<var>SOURCE-DIRECTORY</var> is the directory containing the JavaScript code to be instrumented,
79			and <var>DESTINATION-DIRECTORY</var> is the name of the
80			directory to which <code>jscoverage</code> should output the instrumented code.
81			The <code>jscoverage</code> program will create <var>DESTINATION-DIRECTORY</var> if necessary and (recursively) copy
82			<var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>, instrumenting
83			any files ending with a <code>.js</code> extension.
84			</p>
85
86			<p>
87			For example, if you have a file
88			<code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
89			<code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
90			<code>jscoverage</code> will create a copy of the HTML file at
91			<code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code> and an instrumented
92			version of the script at
93			<code><var>DESTINATION-DIRECTORY</var>/dir/script.js</code>.
94			</p>
95
96			<table>
97			<tr>
98			<td><pre>
99			<var>SOURCE-DIRECTORY</var>/
100			dir/
101			index.html
102			script.js
103
104			</pre></td>
105			<td class="arrow">→</td>
106			<td><pre>
107			<var>DESTINATION-DIRECTORY</var>/
108			dir/
109			index.html
110			script.js [instrumented]
111			jscoverage.html
112			</pre></td>
113			</tr>
114			</table>
115
116			<p>
117			In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
118			which is used to execute the instrumented code.
119			</p>
120
121	siliconforks	14	<h3>2. Running instrumented code in the web application</h3>
122	siliconforks	2
123			<p>
124			Open <code>jscoverage.html</code> in your web browser.
125			The page contains a tabbed user interface:
126			</p>
127
128			<ul>
129			<li>The "Browser" tab is used to display pages with instrumented scripts.
130			<li>The "Summary" tab is used to display code coverage data.
131			<li>The "Source" tab is used to display JavaScript code, showing the number of times
132			each line of code was executed.
133			<li>The "About" tab displays information about the current version of JSCoverage.
134			</ul>
135
136			<img src="screenshot.png" alt="Screenshot">
137
138			<p>
139			The "Browser" tab contains an <code><iframe></code>, which is initially empty.
140			You can load a page into this frame by
141			entering its URL into the "URL" input field. For example, to load
142			the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can
143			enter the relative URL <code>dir/index.html</code> into the input field.
144			</p>
145
146			<h3>3. Generating the coverage report</h3>
147
148			<p>
149			Once the JavaScript code in the page in the "Browser" tab has been executed, click on
150			the "Summary" tab. This will display the current code coverage statistics.
151			</p>
152
153			<p>
154			As long as you do not reload the
155			<code>jscoverage.html</code> page, the coverage report statistics are
156			cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
157			another scripted page, or by reloading the frame containing a scripted
158			page) and switch to the "Summary" tab again,
159			the coverage report will combine the statistics from the previous report with any newly generated statistics.
160			Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
161			</p>
162
163			<h2>Example</h2>
164
165			<p>
166			The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.
167			You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.
168			To instrument this program, follow these steps:
169			</p>
170
171			<h3>1. Instrumenting code</h3>
172
173			<p>
174			From the main distribution directory, execute the command:
175			</p>
176
177			<pre>
178			jscoverage doc/example doc/instrumented
179			</pre>
180
181			<p>
182			This will create the directory <code>doc/instrumented</code> and
183			place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.
184			</p>
185
186			<h3>2. Executing instrumented code</h3>
187
188			<p>
189			You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type
190			the URL for the instrumented code in the "URL" input field. Since a relative URL is accepted, you
191			can simply type <code>index.html</code> to load the page.
192			</p>
193
194			<p>
195			Alternatively, you can append the URL to the query string of the
196			<code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage
197			directory and the Firefox executable is in your <code>PATH</code>, you can load
198			the <code>jscoverage.html</code> frameset and the <code>index.html</code> page
199			all in one command line:
200			</p>
201
202			<pre>
203			firefox "doc/instrumented/jscoverage.html?index.html"
204			</pre>
205
206			<img src="screenshot2.png" alt="Screenshot">
207
208			<p>
209			For this particular page, the JavaScript does not execute automatically:
210			you have to select one of the radio buttons to execute the code.
211			</p>
212
213			<img src="screenshot3.png" alt="Screenshot">
214
215			<h3>3. Generating the coverage report</h3>
216
217			<p>
218	siliconforks	14	Once you have executed the JavaScript code, you are instructed to click on the
219	siliconforks	2	"Summary" tab.
220			</p>
221
222			<img src="screenshot4.png" alt="Screenshot">
223
224			<p>
225			From the "Summary" tab, you can click the links to get a detailed view of a JavaScript source file.
226			</p>
227
228			<img src="screenshot5.png" alt="Screenshot">
229
230	siliconforks	14	<h2>Inverted mode</h2>
231
232			<p>
233			In some circumstances it may be difficult to execute your code within the
234			JSCoverage "Browser" tab. For example, the code may assume that it is running in
235			the top-level browser window, generating errors if it is executed from within a
236			frame. JSCoverage has an alternative mode of operation, called <dfn>inverted
237			mode</dfn>, which may be useful in this situation.
238			</p>
239
240			<p>
241			Normally you load <code>jscoverage.html</code> in your web browser, and in its
242			"Browser" tab you launch your test code. In inverted mode, you do the
243			opposite: you load your test page directly in your web browser, and from there
244			you launch JSCoverage. To do this you need to add some code to your test page:
245			</p>
246
247			<pre>
248			window.open("path/to/jscoverage.html");
249			</pre>
250
251			<p>
252			The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
253			location of the <code>jscoverage.html</code> file (remember, this will be in the
254			top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
255			the <code>jscoverage</code> executable).
256			</p>
257
258			<p>
259			You can place this code wherever you like in your page: for example, you could
260			attach it to a button:
261			</p>
262
263			<pre>
264			<button onclick='window.open("path/to/jscoverage.html");'>Coverage report</button>
265			</pre>
266
267			<p>
268			An example is located in the <code>doc/example-inverted</code> directory.
269			You can instrument the code and launch the <code>index.html</code> page:
270			</p>
271
272			<pre>
273			jscoverage doc/example-inverted doc/instrumented-inverted
274			firefox "doc/instrumented-inverted/index.html"
275			</pre>
276
277			<p>
278			From this page, you select one of the radio buttons and then click the "Coverage
279			report" button to launch the JSCoverage report.
280			</p>
281
282	siliconforks	2	<h2>Caveats</h2>
283
284			<ul>
285			<li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
286			Expect instrumented code to take at least twice as much time to run.
287			<li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code><script></code>
288			elements in HTML files.
289			<li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
290			the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
291			<li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
292			that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
293			statements, you may get strange results.
294			<li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
295			those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
296			<li>JSCoverage is alpha software. Use at your own risk.
297			</ul>
298
299			<address>
300			Copyright © 2007 siliconforks.com<br>
301			Last updated July 8, 2007<br>
302			<a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
303			</address>
304
305			</body>
306			</html>