ViewVC logotype

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 64 - (show annotations)
Thu Nov 22 01:03:33 2007 UTC (15 years ago) by siliconforks
File MIME type: text/html
File size: 12812 byte(s)
Add note about accessing other servers.

1 <!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>
9 <h1>JSCoverage user manual</h1>
11 <p>
12 JSCoverage is a tool used to measure code coverage in JavaScript
13 programs.
14 </p>
16 <p>
17 JSCoverage has two components:
18 </p>
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>
26 <h2>Installing JSCoverage</h2>
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>
34 <p>
35 You can extract and compile the code with the following commands:
36 </p>
38 <pre>
39 tar jxvf jscoverage-0.3.tar.bz2
40 cd jscoverage-0.3/
41 ./configure
42 make
43 </pre>
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>
50 <pre>
51 make install
52 </pre>
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>
60 <h2>Using JSCoverage</h2>
62 <p>
63 Using JSCoverage requires three steps:
64 </p>
66 <h3>1. Instrumenting code</h3>
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>
73 <pre>
74 jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
75 </pre>
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>
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>
96 <table>
97 <tr>
98 <td><pre>
99 <var>SOURCE-DIRECTORY</var>/
100 dir/
101 index.html
102 script.js
104 </pre></td>
105 <td class="arrow">&rarr;</td>
106 <td><pre>
108 dir/
109 index.html
110 script.js [instrumented]
111 jscoverage.html
112 </pre></td>
113 </tr>
114 </table>
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>
121 <h3>2. Running instrumented code in the web application</h3>
123 <p>
124 Open <code>jscoverage.html</code> in your web browser.
125 The page contains a tabbed user interface:
126 </p>
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>
136 <img src="screenshot.png" alt="Screenshot">
138 <p>
139 The "Browser" tab contains an <code>&lt;iframe&gt;</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 You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
145 or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
146 from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
147 server, will give unexpected results.
148 </p>
150 <h3>3. Generating the coverage report</h3>
152 <p>
153 Once the JavaScript code in the page in the "Browser" tab has been executed, click on
154 the "Summary" tab. This will display the current code coverage statistics.
155 </p>
157 <p>
158 As long as you do not reload the
159 <code>jscoverage.html</code> page, the coverage report statistics are
160 cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
161 another scripted page, or by reloading the frame containing a scripted
162 page) and switch to the "Summary" tab again,
163 the coverage report will combine the statistics from the previous report with any newly generated statistics.
164 Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
165 </p>
167 <h2>Example</h2>
169 <p>
170 The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.
171 You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.
172 To instrument this program, follow these steps:
173 </p>
175 <h3>1. Instrumenting code</h3>
177 <p>
178 From the main distribution directory, execute the command:
179 </p>
181 <pre>
182 jscoverage doc/example doc/instrumented
183 </pre>
185 <p>
186 This will create the directory <code>doc/instrumented</code> and
187 place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.
188 </p>
190 <h3>2. Executing instrumented code</h3>
192 <p>
193 You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type
194 the URL for the instrumented code in the "URL" input field. Since a relative URL is accepted, you
195 can simply type <code>index.html</code> to load the page.
196 </p>
198 <p>
199 Alternatively, you can append the URL to the query string of the
200 <code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage
201 directory and the Firefox executable is in your <code>PATH</code>, you can load
202 the <code>jscoverage.html</code> frameset and the <code>index.html</code> page
203 all in one command line:
204 </p>
206 <pre>
207 firefox "doc/instrumented/jscoverage.html?index.html"
208 </pre>
210 <img src="screenshot2.png" alt="Screenshot">
212 <p>
213 For this particular page, the JavaScript does not execute automatically:
214 you have to select one of the radio buttons to execute the code.
215 </p>
217 <img src="screenshot3.png" alt="Screenshot">
219 <h3>3. Generating the coverage report</h3>
221 <p>
222 Once you have executed the JavaScript code, you are instructed to click on the
223 "Summary" tab.
224 </p>
226 <img src="screenshot4.png" alt="Screenshot">
228 <p>
229 You can click the checkbox to show a list of statements missed during execution.
230 </p>
232 <img src="screenshot5.png" alt="Screenshot">
234 <p>
235 You can click one of the links to get a detailed view of a JavaScript source file.
236 </p>
238 <img src="screenshot6.png" alt="Screenshot">
240 <h2>Inverted mode</h2>
242 <p>
243 In some situations it may be difficult to execute your code within the
244 JSCoverage "Browser" tab. For example, the code may assume that it is running in
245 the top-level browser window, generating errors if it is executed from within a
246 frame. JSCoverage has an alternative mode of operation, called <dfn>inverted
247 mode</dfn>, which may be useful in this case.
248 </p>
250 <p>
251 Normally you load <code>jscoverage.html</code> in your web browser, and in its
252 "Browser" tab you launch your test code. In inverted mode, you do the
253 opposite: you load your test page directly in your web browser, and from there
254 you launch JSCoverage. To do this you need to add some code to your test page:
255 </p>
257 <pre>
258 window.open("path/to/jscoverage.html");
259 </pre>
261 <p>
262 The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
263 location of the <code>jscoverage.html</code> file (remember, this will be in the
264 top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
265 the <code>jscoverage</code> executable).
266 </p>
268 <p>
269 You can place this code wherever you like in your page: for example, you could
270 attach it to a button:
271 </p>
273 <pre>
274 &lt;button onclick='window.open("path/to/jscoverage.html");'&gt;Coverage report&lt;/button&gt;
275 </pre>
277 <p>
278 Note that you <em>must</em> use a <code>window.open</code> call; simply making a
279 link to <code>jscoverage.html</code> is not sufficient.
280 </p>
282 <p>
283 An example is located in the <code>doc/example-inverted</code> directory.
284 You can instrument the code and launch the <code>index.html</code> page:
285 </p>
287 <pre>
288 jscoverage doc/example-inverted doc/instrumented-inverted
289 firefox "doc/instrumented-inverted/index.html"
290 </pre>
292 <p>
293 From this page, you select one of the radio buttons and then click the "Coverage
294 report" button to launch the JSCoverage report.
295 </p>
297 <h2>Command line options</h2>
299 <p>
300 The <code>jscoverage</code> program accepts the following options:
301 </p>
303 <dl>
304 <dt><code>-h</code>, <code>--help</code>
305 <dd>Display a brief help message.
306 <dt><code>-V</code>, <code>--version</code>
307 <dd>Display the version of the program.
308 <dt><code>-v</code>, <code>--verbose</code>
309 <dd>Explain what is being done.
310 <dt><code>--exclude=<var>PATH</var></code>
311 <dd>The command
312 <pre>
313 jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
314 </pre>
315 copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
316 recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
317 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
318 <var>PATH</var> can be a file or a directory (in which case the directory and
319 its entire contents are skipped). This option may be given multiple times.
320 <dt><code>--no-instrument=<var>PATH</var></code>
321 <dd>The command
322 <pre>
323 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
324 </pre>
325 copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
326 recursively, but does not instrument any JavaScript code in
327 <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
328 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
329 (JavaScript) file or a directory (in which case any JavaScript files located
330 anywhere underneath the directory are not instrumented). This option may be
331 given multiple times.
332 </dl>
334 <h2>Query string options</h2>
336 <p>
337 When accessing <code>jscoverage.html</code> in a web browser, you may provide a
338 query string consisting of options separated by ampersand (<code>&amp;</code>)
339 or semicolon (<code>;</code>). Any option not containing an equals sign
340 (<code>=</code>) is considered to be a URL which will be loaded in the "Browser"
341 tab.
342 </p>
344 <dl>
345 <dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code>
346 <dd>Load <var>URL</var> in the "Browser" tab. (This is the same as specifying
347 an option without an equals sign.)
348 <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
349 <dd>Determines whether to initially display the "Missing" column in the "Summary"
350 tab. <var>BOOLEAN</var> can be
351 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
352 (to display the "Missing" column), or
353 <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
354 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
355 </dl>
357 <h2>Caveats</h2>
359 <ul>
360 <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
361 Expect instrumented code to take at least twice as much time to run.
362 <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
363 elements in HTML files.
364 <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
365 the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
366 <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
367 that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
368 statements, you may get strange results.
369 <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
370 those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
371 <li>JSCoverage is alpha software. Use at your own risk.
372 </ul>
374 <address>
375 Copyright &copy; 2007 siliconforks.com<br>
376 Last updated August 26, 2007<br>
377 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
378 </address>
380 </body>
381 </html>

  ViewVC Help
Powered by ViewVC 1.1.24