1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
|
<!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.3.1.tar.bz2
cd jscoverage-0.3.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">→</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><iframe></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.
You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
server, will give unexpected results.
</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>
You can click the checkbox to show a list of statements missed during execution.
</p>
<img src="screenshot5.png" alt="Screenshot">
<p>
You can click one of the links to get a detailed view of a JavaScript source file.
</p>
<img src="screenshot6.png" alt="Screenshot">
<h2>Inverted mode</h2>
<p>
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 <dfn>inverted
mode</dfn>, which may be useful in this case.
</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>
<button onclick='window.open("path/to/jscoverage.html");'>Coverage report</button>
</pre>
<p>
Note that you <em>must</em> use a <code>window.open</code> call; simply making a
link to <code>jscoverage.html</code> is not sufficient.
</p>
<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>Command line options</h2>
<p>
The <code>jscoverage</code> program accepts the following options:
</p>
<dl>
<dt><code>-h</code>, <code>--help</code>
<dd>Display a brief help message.
<dt><code>-V</code>, <code>--version</code>
<dd>Display the version of the program.
<dt><code>-v</code>, <code>--verbose</code>
<dd>Explain what is being done.
<dt><code>--exclude=<var>PATH</var></code>
<dd>The command
<pre>
jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
</pre>
copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
<var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
<var>PATH</var> 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.
<dt><code>--no-instrument=<var>PATH</var></code>
<dd>The command
<pre>
jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
</pre>
copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
recursively, but does not instrument any JavaScript code in
<var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> 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.
</dl>
<h2>Query string options</h2>
<p>
When accessing <code>jscoverage.html</code> in a web browser, you may provide a
query string consisting of options separated by ampersand (<code>&</code>)
or semicolon (<code>;</code>). Any option not containing an equals sign
(<code>=</code>) is considered to be a URL which will be loaded in the "Browser"
tab.
</p>
<dl>
<dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code>
<dd>Load <var>URL</var> in the "Browser" tab. (This is the same as specifying
an option without an equals sign.)
<dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
<dd>Determines whether to initially display the "Missing" column in the "Summary"
tab. <var>BOOLEAN</var> can be
<code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
(to display the "Missing" column), or
<code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
(to hide the "Missing" column). By default, the "Missing" column is not displayed.
</dl>
<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><script></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 © 2007 siliconforks.com<br>
Last updated November 22, 2007<br>
<a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
</address>
</body>
</html>
|
