ViewVC logotype

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 158 - (show annotations)
Sat Sep 13 04:01:44 2008 UTC (14 years, 2 months ago) by siliconforks
File MIME type: text/html
File size: 21335 byte(s)
Doc fixes.

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

  ViewVC Help
Powered by ViewVC 1.1.24