1 |
siliconforks |
197 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
2 |
siliconforks |
2 |
<html> |
3 |
|
|
<head> |
4 |
|
|
<title>JSCoverage user manual</title> |
5 |
siliconforks |
198 |
<link rel="stylesheet" type="text/css" href="sh_nedit.min.css"> |
6 |
|
|
<script src="sh_main.min.js"></script> |
7 |
|
|
<script src="sh_html.min.js"></script> |
8 |
|
|
<script src="sh_javascript.min.js"></script> |
9 |
|
|
<link rel="stylesheet" type="text/css" href="doc.css"> |
10 |
siliconforks |
2 |
</head> |
11 |
siliconforks |
198 |
<body onload="sh_highlightDocument();"> |
12 |
siliconforks |
2 |
|
13 |
|
|
<h1>JSCoverage user manual</h1> |
14 |
|
|
|
15 |
|
|
<p> |
16 |
siliconforks |
198 |
JSCoverage is a tool that measures code coverage in JavaScript programs. |
17 |
siliconforks |
2 |
</p> |
18 |
|
|
|
19 |
|
|
<p> |
20 |
siliconforks |
115 |
JSCoverage works by adding instrumentation to JavaScript code before it is |
21 |
|
|
executed in a web browser. JSCoverage provides several alternative ways of doing |
22 |
|
|
this: |
23 |
siliconforks |
2 |
</p> |
24 |
|
|
|
25 |
siliconforks |
115 |
<ul> |
26 |
|
|
<li>The simplest method is to use the <code>jscoverage</code> program to generate |
27 |
|
|
instrumented JavaScript files. |
28 |
|
|
</li> |
29 |
|
|
<li>Alternatively, you can use the <code>jscoverage-server</code> program, a simple web server that instruments |
30 |
|
|
JavaScript code as it is served. |
31 |
|
|
</li> |
32 |
|
|
<li>Finally, <code>jscoverage-server</code> can be run with the <code>--proxy</code> option to |
33 |
|
|
act as a proxy server which instruments any JavaScript code proxied through it. |
34 |
|
|
</li> |
35 |
|
|
</ul> |
36 |
siliconforks |
2 |
|
37 |
siliconforks |
115 |
<p> |
38 |
|
|
The <code>jscoverage-server</code> program (with or without the <code>--proxy</code> |
39 |
|
|
option) has the advantage of being able to store coverage reports to the filesystem. |
40 |
|
|
</p> |
41 |
|
|
|
42 |
siliconforks |
2 |
<h2>Installing JSCoverage</h2> |
43 |
|
|
|
44 |
|
|
<p> |
45 |
|
|
You can compile JSCoverage on GNU/Linux or Microsoft Windows, using GCC. On |
46 |
|
|
Windows you will require <a href="http://cygwin.com/">Cygwin</a> or <a |
47 |
|
|
href="http://mingw.org/">MinGW/MSYS</a>. |
48 |
|
|
</p> |
49 |
|
|
|
50 |
|
|
<p> |
51 |
|
|
You can extract and compile the code with the following commands: |
52 |
|
|
</p> |
53 |
|
|
|
54 |
|
|
<pre> |
55 |
siliconforks |
115 |
tar jxvf jscoverage-0.4.tar.bz2 |
56 |
|
|
cd jscoverage-0.4/ |
57 |
siliconforks |
2 |
./configure |
58 |
|
|
make |
59 |
|
|
</pre> |
60 |
|
|
|
61 |
|
|
<p> |
62 |
siliconforks |
115 |
This will create the <code>jscoverage</code> and <code>jscoverage-server</code> |
63 |
|
|
executables (<code>jscoverage.exe</code> and <code>jscoverage-server.exe</code> |
64 |
|
|
on Windows). You can install the executables in <code>/usr/local</code> with the |
65 |
|
|
command: |
66 |
siliconforks |
2 |
</p> |
67 |
|
|
|
68 |
|
|
<pre> |
69 |
|
|
make install |
70 |
|
|
</pre> |
71 |
|
|
|
72 |
|
|
<p> |
73 |
siliconforks |
115 |
Alternatively, you may simply copy the <code>jscoverage</code> executable and/or |
74 |
|
|
the <code>jscoverage-server</code> executable to a suitable location in your |
75 |
|
|
<code>PATH</code>. |
76 |
siliconforks |
2 |
</p> |
77 |
|
|
|
78 |
siliconforks |
115 |
<h2>Using the <code>jscoverage</code> program</h2> |
79 |
siliconforks |
2 |
|
80 |
|
|
<p> |
81 |
siliconforks |
198 |
Using the <code>jscoverage</code> program involves the following steps: |
82 |
siliconforks |
2 |
</p> |
83 |
|
|
|
84 |
|
|
<h3>1. Instrumenting code</h3> |
85 |
|
|
|
86 |
|
|
<p> |
87 |
siliconforks |
115 |
The first step is to add instrumentation to your JavaScript code. You do this by |
88 |
|
|
executing <code>jscoverage</code> with two arguments: |
89 |
siliconforks |
2 |
</p> |
90 |
|
|
|
91 |
|
|
<pre> |
92 |
|
|
jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var> |
93 |
|
|
</pre> |
94 |
|
|
|
95 |
|
|
<p> |
96 |
|
|
<var>SOURCE-DIRECTORY</var> is the directory containing the JavaScript code to be instrumented, |
97 |
|
|
and <var>DESTINATION-DIRECTORY</var> is the name of the |
98 |
|
|
directory to which <code>jscoverage</code> should output the instrumented code. |
99 |
|
|
The <code>jscoverage</code> program will create <var>DESTINATION-DIRECTORY</var> if necessary and (recursively) copy |
100 |
|
|
<var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>, instrumenting |
101 |
|
|
any files ending with a <code>.js</code> extension. |
102 |
|
|
</p> |
103 |
|
|
|
104 |
|
|
<p> |
105 |
|
|
For example, if you have a file |
106 |
|
|
<code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script |
107 |
|
|
<code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then |
108 |
|
|
<code>jscoverage</code> will create a copy of the HTML file at |
109 |
|
|
<code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code> and an instrumented |
110 |
|
|
version of the script at |
111 |
|
|
<code><var>DESTINATION-DIRECTORY</var>/dir/script.js</code>. |
112 |
|
|
</p> |
113 |
|
|
|
114 |
|
|
<table> |
115 |
|
|
<tr> |
116 |
|
|
<td><pre> |
117 |
|
|
<var>SOURCE-DIRECTORY</var>/ |
118 |
|
|
dir/ |
119 |
|
|
index.html |
120 |
|
|
script.js |
121 |
|
|
|
122 |
|
|
</pre></td> |
123 |
|
|
<td class="arrow">→</td> |
124 |
|
|
<td><pre> |
125 |
|
|
<var>DESTINATION-DIRECTORY</var>/ |
126 |
|
|
dir/ |
127 |
|
|
index.html |
128 |
|
|
script.js [instrumented] |
129 |
|
|
jscoverage.html |
130 |
|
|
</pre></td> |
131 |
|
|
</tr> |
132 |
|
|
</table> |
133 |
|
|
|
134 |
|
|
<p> |
135 |
|
|
In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code> |
136 |
|
|
which is used to execute the instrumented code. |
137 |
|
|
</p> |
138 |
|
|
|
139 |
siliconforks |
115 |
<h3>2. Executing the instrumented code in a web browser</h3> |
140 |
siliconforks |
2 |
|
141 |
|
|
<p> |
142 |
|
|
Open <code>jscoverage.html</code> in your web browser. |
143 |
|
|
The page contains a tabbed user interface: |
144 |
|
|
</p> |
145 |
|
|
|
146 |
|
|
<ul> |
147 |
|
|
<li>The "Browser" tab is used to display pages with instrumented scripts. |
148 |
|
|
<li>The "Summary" tab is used to display code coverage data. |
149 |
|
|
<li>The "Source" tab is used to display JavaScript code, showing the number of times |
150 |
|
|
each line of code was executed. |
151 |
|
|
<li>The "About" tab displays information about the current version of JSCoverage. |
152 |
|
|
</ul> |
153 |
|
|
|
154 |
siliconforks |
197 |
<p><img src="screenshot.png" alt="Screenshot"></p> |
155 |
siliconforks |
2 |
|
156 |
|
|
<p> |
157 |
|
|
The "Browser" tab contains an <code><iframe></code>, which is initially empty. |
158 |
|
|
You can load a page into this frame by |
159 |
|
|
entering its URL into the "URL" input field. For example, to load |
160 |
|
|
the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can |
161 |
|
|
enter the relative URL <code>dir/index.html</code> into the input field. |
162 |
siliconforks |
64 |
You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code> |
163 |
|
|
or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page |
164 |
|
|
from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web |
165 |
|
|
server, will give unexpected results. |
166 |
siliconforks |
2 |
</p> |
167 |
|
|
|
168 |
siliconforks |
115 |
<h3>3. Generating a coverage report</h3> |
169 |
siliconforks |
2 |
|
170 |
|
|
<p> |
171 |
|
|
Once the JavaScript code in the page in the "Browser" tab has been executed, click on |
172 |
|
|
the "Summary" tab. This will display the current code coverage statistics. |
173 |
|
|
</p> |
174 |
|
|
|
175 |
|
|
<p> |
176 |
|
|
As long as you do not reload the |
177 |
|
|
<code>jscoverage.html</code> page, the coverage report statistics are |
178 |
|
|
cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to |
179 |
|
|
another scripted page, or by reloading the frame containing a scripted |
180 |
|
|
page) and switch to the "Summary" tab again, |
181 |
|
|
the coverage report will combine the statistics from the previous report with any newly generated statistics. |
182 |
|
|
Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero. |
183 |
|
|
</p> |
184 |
|
|
|
185 |
|
|
<h2>Example</h2> |
186 |
|
|
|
187 |
|
|
<p> |
188 |
|
|
The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory. |
189 |
|
|
You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program. |
190 |
|
|
To instrument this program, follow these steps: |
191 |
|
|
</p> |
192 |
|
|
|
193 |
|
|
<h3>1. Instrumenting code</h3> |
194 |
|
|
|
195 |
|
|
<p> |
196 |
|
|
From the main distribution directory, execute the command: |
197 |
|
|
</p> |
198 |
|
|
|
199 |
|
|
<pre> |
200 |
|
|
jscoverage doc/example doc/instrumented |
201 |
|
|
</pre> |
202 |
|
|
|
203 |
|
|
<p> |
204 |
|
|
This will create the directory <code>doc/instrumented</code> and |
205 |
|
|
place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>. |
206 |
|
|
</p> |
207 |
|
|
|
208 |
siliconforks |
115 |
<h3>2. Executing the instrumented code in a web browser</h3> |
209 |
siliconforks |
2 |
|
210 |
|
|
<p> |
211 |
|
|
You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type |
212 |
|
|
the URL for the instrumented code in the "URL" input field. Since a relative URL is accepted, you |
213 |
|
|
can simply type <code>index.html</code> to load the page. |
214 |
|
|
</p> |
215 |
|
|
|
216 |
|
|
<p> |
217 |
|
|
Alternatively, you can append the URL to the query string of the |
218 |
|
|
<code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage |
219 |
|
|
directory and the Firefox executable is in your <code>PATH</code>, you can load |
220 |
|
|
the <code>jscoverage.html</code> frameset and the <code>index.html</code> page |
221 |
|
|
all in one command line: |
222 |
|
|
</p> |
223 |
|
|
|
224 |
|
|
<pre> |
225 |
|
|
firefox "doc/instrumented/jscoverage.html?index.html" |
226 |
|
|
</pre> |
227 |
|
|
|
228 |
siliconforks |
197 |
<p><img src="screenshot2.png" alt="Screenshot"></p> |
229 |
siliconforks |
2 |
|
230 |
|
|
<p> |
231 |
|
|
For this particular page, the JavaScript does not execute automatically: |
232 |
|
|
you have to select one of the radio buttons to execute the code. |
233 |
|
|
</p> |
234 |
|
|
|
235 |
siliconforks |
197 |
<p><img src="screenshot3.png" alt="Screenshot"></p> |
236 |
siliconforks |
2 |
|
237 |
siliconforks |
115 |
<h3>3. Generating a coverage report</h3> |
238 |
siliconforks |
2 |
|
239 |
|
|
<p> |
240 |
siliconforks |
14 |
Once you have executed the JavaScript code, you are instructed to click on the |
241 |
siliconforks |
2 |
"Summary" tab. |
242 |
|
|
</p> |
243 |
|
|
|
244 |
siliconforks |
197 |
<p><img src="screenshot4.png" alt="Screenshot"></p> |
245 |
siliconforks |
2 |
|
246 |
|
|
<p> |
247 |
siliconforks |
41 |
You can click the checkbox to show a list of statements missed during execution. |
248 |
siliconforks |
2 |
</p> |
249 |
|
|
|
250 |
siliconforks |
197 |
<p><img src="screenshot5.png" alt="Screenshot"></p> |
251 |
siliconforks |
2 |
|
252 |
siliconforks |
41 |
<p> |
253 |
|
|
You can click one of the links to get a detailed view of a JavaScript source file. |
254 |
|
|
</p> |
255 |
|
|
|
256 |
siliconforks |
197 |
<p><img src="screenshot6.png" alt="Screenshot"></p> |
257 |
siliconforks |
41 |
|
258 |
siliconforks |
14 |
<h2>Inverted mode</h2> |
259 |
|
|
|
260 |
|
|
<p> |
261 |
siliconforks |
41 |
In some situations it may be difficult to execute your code within the |
262 |
siliconforks |
14 |
JSCoverage "Browser" tab. For example, the code may assume that it is running in |
263 |
|
|
the top-level browser window, generating errors if it is executed from within a |
264 |
|
|
frame. JSCoverage has an alternative mode of operation, called <dfn>inverted |
265 |
siliconforks |
41 |
mode</dfn>, which may be useful in this case. |
266 |
siliconforks |
14 |
</p> |
267 |
|
|
|
268 |
|
|
<p> |
269 |
|
|
Normally you load <code>jscoverage.html</code> in your web browser, and in its |
270 |
|
|
"Browser" tab you launch your test code. In inverted mode, you do the |
271 |
|
|
opposite: you load your test page directly in your web browser, and from there |
272 |
|
|
you launch JSCoverage. To do this you need to add some code to your test page: |
273 |
|
|
</p> |
274 |
|
|
|
275 |
siliconforks |
198 |
<pre class="sh_javascript"> |
276 |
|
|
window.open('path/to/jscoverage.html'); |
277 |
siliconforks |
14 |
</pre> |
278 |
|
|
|
279 |
|
|
<p> |
280 |
|
|
The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the |
281 |
|
|
location of the <code>jscoverage.html</code> file (remember, this will be in the |
282 |
|
|
top level of the <var>DESTINATION-DIRECTORY</var> you specified when running |
283 |
|
|
the <code>jscoverage</code> executable). |
284 |
|
|
</p> |
285 |
|
|
|
286 |
|
|
<p> |
287 |
|
|
You can place this code wherever you like in your page: for example, you could |
288 |
|
|
attach it to a button: |
289 |
|
|
</p> |
290 |
|
|
|
291 |
siliconforks |
198 |
<pre class="sh_html"> |
292 |
|
|
<button onclick="window.open('path/to/jscoverage.html');">Coverage report</button> |
293 |
siliconforks |
14 |
</pre> |
294 |
|
|
|
295 |
|
|
<p> |
296 |
siliconforks |
37 |
Note that you <em>must</em> use a <code>window.open</code> call; simply making a |
297 |
|
|
link to <code>jscoverage.html</code> is not sufficient. |
298 |
|
|
</p> |
299 |
|
|
|
300 |
|
|
<p> |
301 |
siliconforks |
14 |
An example is located in the <code>doc/example-inverted</code> directory. |
302 |
|
|
You can instrument the code and launch the <code>index.html</code> page: |
303 |
|
|
</p> |
304 |
|
|
|
305 |
|
|
<pre> |
306 |
|
|
jscoverage doc/example-inverted doc/instrumented-inverted |
307 |
|
|
firefox "doc/instrumented-inverted/index.html" |
308 |
|
|
</pre> |
309 |
|
|
|
310 |
|
|
<p> |
311 |
|
|
From this page, you select one of the radio buttons and then click the "Coverage |
312 |
|
|
report" button to launch the JSCoverage report. |
313 |
|
|
</p> |
314 |
|
|
|
315 |
siliconforks |
115 |
<h2><code>jscoverage</code> command line options</h2> |
316 |
siliconforks |
19 |
|
317 |
|
|
<p> |
318 |
|
|
The <code>jscoverage</code> program accepts the following options: |
319 |
|
|
</p> |
320 |
|
|
|
321 |
|
|
<dl> |
322 |
|
|
<dt><code>-h</code>, <code>--help</code> |
323 |
|
|
<dd>Display a brief help message. |
324 |
|
|
<dt><code>-V</code>, <code>--version</code> |
325 |
|
|
<dd>Display the version of the program. |
326 |
|
|
<dt><code>-v</code>, <code>--verbose</code> |
327 |
|
|
<dd>Explain what is being done. |
328 |
siliconforks |
207 |
<dt><code>--encoding=<var>ENCODING</var></code> |
329 |
|
|
<dd>Assume that all JavaScript files use the given character encoding. The |
330 |
|
|
default is ISO-8859-1. |
331 |
siliconforks |
19 |
<dt><code>--exclude=<var>PATH</var></code> |
332 |
|
|
<dd>The command |
333 |
|
|
<pre> |
334 |
|
|
jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var> |
335 |
|
|
</pre> |
336 |
|
|
copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var> |
337 |
|
|
recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. |
338 |
siliconforks |
41 |
<var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>. |
339 |
siliconforks |
19 |
<var>PATH</var> can be a file or a directory (in which case the directory and |
340 |
|
|
its entire contents are skipped). This option may be given multiple times. |
341 |
siliconforks |
207 |
<dt><code>--no-highlight</code> |
342 |
|
|
<dd>Do not perform syntax highlighting of JavaScript code. |
343 |
siliconforks |
19 |
<dt><code>--no-instrument=<var>PATH</var></code> |
344 |
|
|
<dd>The command |
345 |
|
|
<pre> |
346 |
siliconforks |
41 |
jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var> |
347 |
siliconforks |
19 |
</pre> |
348 |
|
|
copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var> |
349 |
|
|
recursively, but does not instrument any JavaScript code in |
350 |
|
|
<var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete |
351 |
siliconforks |
59 |
path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a |
352 |
siliconforks |
19 |
(JavaScript) file or a directory (in which case any JavaScript files located |
353 |
|
|
anywhere underneath the directory are not instrumented). This option may be |
354 |
|
|
given multiple times. |
355 |
|
|
</dl> |
356 |
|
|
|
357 |
|
|
<h2>Query string options</h2> |
358 |
|
|
|
359 |
|
|
<p> |
360 |
|
|
When accessing <code>jscoverage.html</code> in a web browser, you may provide a |
361 |
|
|
query string consisting of options separated by ampersand (<code>&</code>) |
362 |
|
|
or semicolon (<code>;</code>). Any option not containing an equals sign |
363 |
|
|
(<code>=</code>) is considered to be a URL which will be loaded in the "Browser" |
364 |
|
|
tab. |
365 |
|
|
</p> |
366 |
|
|
|
367 |
|
|
<dl> |
368 |
|
|
<dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code> |
369 |
|
|
<dd>Load <var>URL</var> in the "Browser" tab. (This is the same as specifying |
370 |
|
|
an option without an equals sign.) |
371 |
|
|
<dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code> |
372 |
|
|
<dd>Determines whether to initially display the "Missing" column in the "Summary" |
373 |
|
|
tab. <var>BOOLEAN</var> can be |
374 |
siliconforks |
59 |
<code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code> |
375 |
siliconforks |
19 |
(to display the "Missing" column), or |
376 |
|
|
<code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code> |
377 |
siliconforks |
41 |
(to hide the "Missing" column). By default, the "Missing" column is not displayed. |
378 |
siliconforks |
19 |
</dl> |
379 |
|
|
|
380 |
siliconforks |
115 |
<h2>Using the <code>jscoverage-server</code> program</h2> |
381 |
|
|
|
382 |
|
|
<p> |
383 |
siliconforks |
198 |
The <code>jscoverage-server</code> program is a simple web server. You can use |
384 |
|
|
<code>jscoverage-server</code> to serve files from the <code>doc/example/</code> |
385 |
|
|
directory: |
386 |
siliconforks |
115 |
</p> |
387 |
|
|
|
388 |
|
|
<pre> |
389 |
|
|
cd doc/example |
390 |
|
|
jscoverage-server --verbose |
391 |
|
|
</pre> |
392 |
|
|
|
393 |
|
|
<p> |
394 |
siliconforks |
198 |
Once the server is running, you can access the JSCoverage web interface by |
395 |
|
|
visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can |
396 |
|
|
load the <code>doc/example/index.html</code> file by entering |
397 |
|
|
<code>index.html</code> in the "URL" input field. (Or you can do this all in |
398 |
|
|
one step by loading the URL |
399 |
|
|
<code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web |
400 |
|
|
browser.) The |
401 |
|
|
<code>jscoverage-server</code> program automatically instruments any served |
402 |
siliconforks |
115 |
JavaScript code, so that code coverage data will be gathered as the code is |
403 |
|
|
executed in your browser. |
404 |
|
|
</p> |
405 |
|
|
|
406 |
|
|
<p> |
407 |
|
|
The web interface is slightly different from that generated by the |
408 |
|
|
<code>jscoverage</code> program: it has a new tab named "Store". |
409 |
|
|
To store coverage data, click the "Store" tab. |
410 |
|
|
</p> |
411 |
|
|
|
412 |
siliconforks |
197 |
<p><img src="screenshot7.png" alt="Screenshot"></p> |
413 |
siliconforks |
115 |
|
414 |
|
|
<p> |
415 |
|
|
When you click the "Store" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>. |
416 |
|
|
You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in |
417 |
siliconforks |
198 |
your web browser - you don't need the <code>jscoverage-server</code> running to access it. |
418 |
siliconforks |
115 |
</p> |
419 |
|
|
|
420 |
|
|
<p> |
421 |
|
|
If you use the "Store" tab again to store coverage data, the new data will be merged with |
422 |
|
|
the previous data in the <code>jscoverage-report/</code> directory. This can be useful, |
423 |
|
|
for instance, if you wish to run a set of tests in different browsers and generate an |
424 |
|
|
aggregate report which combines the data for all of them. |
425 |
|
|
</p> |
426 |
|
|
|
427 |
|
|
<p> |
428 |
|
|
You can stop the server by running another instance of <code>jscoverage-server</code> with the |
429 |
|
|
<code>--shutdown</code> option: |
430 |
|
|
</p> |
431 |
|
|
|
432 |
|
|
<pre> |
433 |
|
|
jscoverage-server --shutdown |
434 |
|
|
</pre> |
435 |
|
|
|
436 |
|
|
<h2>Using <code>jscoverage-server --proxy</code></h2> |
437 |
|
|
|
438 |
|
|
<p> |
439 |
|
|
To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option: |
440 |
|
|
</p> |
441 |
|
|
|
442 |
|
|
<pre> |
443 |
|
|
jscoverage-server --verbose --proxy |
444 |
|
|
</pre> |
445 |
|
|
|
446 |
|
|
<p> |
447 |
|
|
Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080. |
448 |
|
|
You can then generate code coverage data for a web page on the server <code>example.com</code> |
449 |
|
|
by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>. |
450 |
|
|
Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated |
451 |
|
|
by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested. |
452 |
|
|
</p> |
453 |
|
|
|
454 |
|
|
<h2><code>jscoverage-server</code> command line options</h2> |
455 |
|
|
|
456 |
|
|
<dl> |
457 |
|
|
<dt><code>-h</code>, <code>--help</code> |
458 |
|
|
<dd>Display a brief help message. |
459 |
|
|
<dt><code>-V</code>, <code>--version</code> |
460 |
|
|
<dd>Display the version of the program. |
461 |
|
|
<dt><code>-v</code>, <code>--verbose</code> |
462 |
|
|
<dd>Explain what is being done. |
463 |
|
|
<dt><code>--document-root=<var>PATH</var></code> |
464 |
|
|
<dd>Serve web content from the directory given by <var>PATH</var>. The default is |
465 |
|
|
the current directory. This option may not be given with the <code>--proxy</code> option. |
466 |
siliconforks |
207 |
<dt><code>--encoding=<var>ENCODING</var></code> |
467 |
|
|
<dd>Assume that all JavaScript files use the given character encoding. The |
468 |
|
|
default is ISO-8859-1. Note that if you use the <code>--proxy</code> option, the |
469 |
|
|
character encoding will be determined from the <code>charset</code> parameter in |
470 |
|
|
the <code>Content-Type</code> HTTP header. |
471 |
siliconforks |
115 |
<dt><code>--ip-address=<var>ADDRESS</var></code> |
472 |
|
|
<dd>Run the server on the IP address given by <var>ADDRESS</var>. The default is <code>127.0.0.1</code>. Specify |
473 |
|
|
<code>0.0.0.0</code> to use any address. |
474 |
siliconforks |
207 |
<dt><code>--no-highlight</code> |
475 |
|
|
<dd>Do not perform syntax highlighting of JavaScript code. |
476 |
siliconforks |
115 |
<dt><code>--no-instrument=<var>URL</var></code> |
477 |
|
|
<dd>Do not instrument JavaScript code from <var>URL</var>. If you are running <code>jscoverage-server</code> |
478 |
|
|
with the <code>--proxy</code> option, <var>URL</var> should be a full URL. For example: |
479 |
|
|
<pre> |
480 |
|
|
jscoverage-server --proxy --no-instrument=http://example.com/scripts/ |
481 |
|
|
</pre> |
482 |
|
|
Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL: |
483 |
|
|
<pre> |
484 |
|
|
jscoverage-server --no-instrument=/scripts/ |
485 |
|
|
</pre> |
486 |
|
|
This option may be given multiple times. |
487 |
|
|
<dt><code>--port=<var>PORT</var></code> |
488 |
|
|
<dd>Run the server on the port given by <var>PORT</var>. The default is port 8080. |
489 |
|
|
<dt><code>--proxy</code> |
490 |
|
|
<dd>Run as a proxy server. |
491 |
|
|
<dt><code>--report-dir=<var>PATH</var></code> |
492 |
|
|
<dd>Use the directory given by <var>PATH</var> for storing coverage reports. The default is |
493 |
|
|
<code>jscoverage-report/</code> in the current directory. |
494 |
|
|
<dt><code>--shutdown</code> |
495 |
|
|
<dd>Stop a running instance of the server. |
496 |
|
|
</dl> |
497 |
|
|
|
498 |
siliconforks |
158 |
<h2>Advanced topics</h2> |
499 |
|
|
|
500 |
siliconforks |
198 |
<h3>Storing coverage reports programmatically</h3> |
501 |
|
|
|
502 |
|
|
<p> |
503 |
|
|
If you are executing a test suite using <code>jscoverage-server</code>, you can |
504 |
|
|
store a coverage report programmatically by having your test suite call the |
505 |
|
|
<code>jscoverage_report</code> function (automatically generated by |
506 |
|
|
<code>jscoverage-server</code>) after all your tests have finished running: |
507 |
|
|
</p> |
508 |
|
|
|
509 |
|
|
<pre class="sh_javascript"> |
510 |
|
|
if (top.jscoverage_report) { |
511 |
|
|
top.jscoverage_report(); |
512 |
|
|
} |
513 |
|
|
</pre> |
514 |
|
|
|
515 |
|
|
<p> |
516 |
|
|
You can specify the name of the directory in which to store the report by |
517 |
|
|
passing the name as a parameter to the <code>jscoverage_report</code> function: |
518 |
|
|
</p> |
519 |
|
|
|
520 |
|
|
<pre class="sh_javascript"> |
521 |
|
|
if (top.jscoverage_report) { |
522 |
|
|
// determine the directory name based on the browser |
523 |
|
|
var directory; |
524 |
|
|
if (/MSIE/.test(navigator.userAgent)) { |
525 |
|
|
directory = 'IE'; |
526 |
|
|
} |
527 |
|
|
else { |
528 |
|
|
directory = 'other'; |
529 |
|
|
} |
530 |
|
|
top.jscoverage_report(directory); |
531 |
|
|
} |
532 |
|
|
</pre> |
533 |
|
|
|
534 |
|
|
<p> |
535 |
|
|
This directory will be a subdirectory under the <code>jscoverage-report/</code> |
536 |
|
|
directory (or whatever is specified with the <code>--report-dir</code> option). |
537 |
|
|
Using the above example, the report would be stored to either |
538 |
|
|
<code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>. |
539 |
|
|
</p> |
540 |
|
|
|
541 |
siliconforks |
201 |
<p> |
542 |
|
|
It is not necessary that your test suite be executed within the |
543 |
|
|
<code>jscoverage.html</code> web interface to store a coverage report. The URL |
544 |
|
|
of the test suite can simply be loaded directly in a web browser. |
545 |
|
|
</p> |
546 |
|
|
|
547 |
siliconforks |
158 |
<h3>Conditional directives</h3> |
548 |
|
|
|
549 |
|
|
<p> |
550 |
|
|
Sometimes you may wish to exclude certain lines of code from coverage |
551 |
|
|
statistics. Some lines of code may be executed only in certain browsers; other |
552 |
siliconforks |
198 |
lines should never be executed at all (they may be present only to detect |
553 |
siliconforks |
158 |
programming errors). You can use specially formatted comments in your code, |
554 |
|
|
called <dfn>conditional directives</dfn>, to tell JSCoverage when to exclude |
555 |
|
|
those lines from coverage statistics. These lines will be ignored in the |
556 |
|
|
JSCoverage "Summary" tab; in the "Source" tab, these lines will be indicated |
557 |
|
|
with the color yellow. |
558 |
|
|
</p> |
559 |
|
|
|
560 |
|
|
<p> |
561 |
|
|
Conditional directives take the following form: |
562 |
|
|
</p> |
563 |
|
|
|
564 |
|
|
<pre class="sh_javascript"> |
565 |
|
|
//#JSCOVERAGE_IF <var>CONDITION</var> |
566 |
|
|
... |
567 |
|
|
//#JSCOVERAGE_ENDIF |
568 |
|
|
</pre> |
569 |
|
|
|
570 |
|
|
<p> |
571 |
|
|
The <var>CONDITION</var> is an ordinary JavaScript expression; if this |
572 |
|
|
expression evaluates to <code>true</code>, then the lines of code between the |
573 |
|
|
<code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> directives are |
574 |
|
|
included in coverage statistics; otherwise, they are excluded from coverage |
575 |
|
|
statistics. |
576 |
|
|
</p> |
577 |
|
|
|
578 |
|
|
<p> |
579 |
|
|
In order to be recognized as a conditional directive, the comment must be |
580 |
|
|
formatted exactly as shown: it must be a line comment starting with <code>//</code>, |
581 |
|
|
it must start in the first column, and it must be followed by <code>#JSCOVERAGE_IF</code> |
582 |
|
|
or <code>#JSCOVERAGE_ENDIF</code> in uppercase letters with no intervening white space. |
583 |
|
|
</p> |
584 |
|
|
|
585 |
|
|
<p> |
586 |
|
|
For example, if you have some code in an <code>if</code> statement which is |
587 |
|
|
executed only in certain browsers, you can usually just repeat the condition in |
588 |
|
|
a <code>//#JSCOVERAGE_IF</code> directive: |
589 |
|
|
</p> |
590 |
|
|
|
591 |
|
|
<pre class="sh_javascript"> |
592 |
|
|
if (window.ActiveXObject) { |
593 |
|
|
//#JSCOVERAGE_IF window.ActiveXObject |
594 |
|
|
return new ActiveXObject('Msxml2.XMLHTTP'); |
595 |
|
|
//#JSCOVERAGE_ENDIF |
596 |
|
|
} |
597 |
|
|
</pre> |
598 |
|
|
|
599 |
|
|
<p> |
600 |
|
|
Alternatively, it may be easier to diagnose problems if you specify exactly |
601 |
|
|
which browsers you expect to execute the code in the conditional: |
602 |
|
|
</p> |
603 |
|
|
|
604 |
|
|
<pre class="sh_javascript"> |
605 |
|
|
if (window.ActiveXObject) { |
606 |
|
|
//#JSCOVERAGE_IF /MSIE/.test(navigator.userAgent) |
607 |
|
|
return new ActiveXObject('Msxml2.XMLHTTP'); |
608 |
|
|
//#JSCOVERAGE_ENDIF |
609 |
|
|
} |
610 |
|
|
</pre> |
611 |
|
|
|
612 |
|
|
<p> |
613 |
siliconforks |
196 |
To exclude code from coverage statistics unconditionally, you can use <code>//#JSCOVERAGE_IF 0</code> or |
614 |
|
|
<code>//#JSCOVERAGE_IF false</code>: |
615 |
siliconforks |
158 |
</p> |
616 |
|
|
|
617 |
|
|
<pre class="sh_javascript"> |
618 |
|
|
function f(s) { |
619 |
|
|
if (typeof(s) !== 'string') { |
620 |
|
|
//#JSCOVERAGE_IF 0 |
621 |
|
|
throw 'function f requires a string argument'; |
622 |
|
|
//#JSCOVERAGE_ENDIF |
623 |
|
|
} |
624 |
|
|
} |
625 |
|
|
</pre> |
626 |
|
|
|
627 |
siliconforks |
201 |
<p> |
628 |
|
|
Currently, conditional directives are ignored in stored coverage reports. |
629 |
|
|
</p> |
630 |
|
|
|
631 |
siliconforks |
2 |
<h2>Caveats</h2> |
632 |
|
|
|
633 |
|
|
<ul> |
634 |
|
|
<li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed. |
635 |
|
|
Expect instrumented code to take at least twice as much time to run. |
636 |
|
|
<li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code><script></code> |
637 |
|
|
elements in HTML files. |
638 |
|
|
<li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference |
639 |
|
|
the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected. |
640 |
|
|
<li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code |
641 |
|
|
that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more |
642 |
|
|
statements, you may get strange results. |
643 |
|
|
<li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially |
644 |
|
|
those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.). |
645 |
siliconforks |
198 |
<li>JSCoverage is distributed without any warranty. See the <a href="license.html">license</a> for more details. |
646 |
siliconforks |
2 |
</ul> |
647 |
|
|
|
648 |
|
|
<address> |
649 |
siliconforks |
147 |
Copyright © 2007, 2008 <a href="http://siliconforks.com/"><img src="siliconforks-16x16.png" width="16" height="16" class="icon" alt="Silicon Forks"></a> <a href="http://siliconforks.com/">siliconforks.com</a><br> |
650 |
siliconforks |
158 |
Last updated September 12, 2008<br> |
651 |
siliconforks |
2 |
<a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a> |
652 |
|
|
</address> |
653 |
|
|
|
654 |
|
|
</body> |
655 |
|
|
</html> |