/[jscoverage]/trunk/doc/manual.html
ViewVC logotype

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 139 - (hide annotations)
Thu Jun 19 06:17:24 2008 UTC (11 years, 5 months ago) by siliconforks
File MIME type: text/html
File size: 18846 byte(s)
Update copyright line.

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 siliconforks 115 JSCoverage is a tool used to measure code coverage in JavaScript programs.
13 siliconforks 2 </p>
14    
15     <p>
16 siliconforks 115 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 siliconforks 2 </p>
20    
21 siliconforks 115 <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>
32 siliconforks 2
33 siliconforks 115 <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>
37    
38 siliconforks 2 <h2>Installing JSCoverage</h2>
39    
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>
45    
46     <p>
47     You can extract and compile the code with the following commands:
48     </p>
49    
50     <pre>
51 siliconforks 115 tar jxvf jscoverage-0.4.tar.bz2
52     cd jscoverage-0.4/
53 siliconforks 2 ./configure
54     make
55     </pre>
56    
57     <p>
58 siliconforks 115 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 siliconforks 2 </p>
63    
64     <pre>
65     make install
66     </pre>
67    
68     <p>
69 siliconforks 115 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 siliconforks 2 </p>
73    
74 siliconforks 115 <h2>Using the <code>jscoverage</code> program</h2>
75 siliconforks 2
76     <p>
77 siliconforks 115 Using the <code>jscoverage</code> program requires the following steps:
78 siliconforks 2 </p>
79    
80     <h3>1. Instrumenting code</h3>
81    
82     <p>
83 siliconforks 115 The first step is to add instrumentation to your JavaScript code. You do this by
84     executing <code>jscoverage</code> with two arguments:
85 siliconforks 2 </p>
86    
87     <pre>
88     jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
89     </pre>
90    
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>
99    
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>
109    
110     <table>
111     <tr>
112     <td><pre>
113     <var>SOURCE-DIRECTORY</var>/
114     dir/
115     index.html
116     script.js
117    
118     </pre></td>
119     <td class="arrow">&rarr;</td>
120     <td><pre>
121     <var>DESTINATION-DIRECTORY</var>/
122     dir/
123     index.html
124     script.js [instrumented]
125     jscoverage.html
126     </pre></td>
127     </tr>
128     </table>
129    
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>
134    
135 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
136 siliconforks 2
137     <p>
138     Open <code>jscoverage.html</code> in your web browser.
139     The page contains a tabbed user interface:
140     </p>
141    
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>
149    
150     <img src="screenshot.png" alt="Screenshot">
151    
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 siliconforks 64 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 siliconforks 2 </p>
163    
164 siliconforks 115 <h3>3. Generating a coverage report</h3>
165 siliconforks 2
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>
170    
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>
180    
181     <h2>Example</h2>
182    
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>
188    
189     <h3>1. Instrumenting code</h3>
190    
191     <p>
192     From the main distribution directory, execute the command:
193     </p>
194    
195     <pre>
196     jscoverage doc/example doc/instrumented
197     </pre>
198    
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>
203    
204 siliconforks 115 <h3>2. Executing the instrumented code in a web browser</h3>
205 siliconforks 2
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>
211    
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>
219    
220     <pre>
221     firefox "doc/instrumented/jscoverage.html?index.html"
222     </pre>
223    
224     <img src="screenshot2.png" alt="Screenshot">
225    
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>
230    
231     <img src="screenshot3.png" alt="Screenshot">
232    
233 siliconforks 115 <h3>3. Generating a coverage report</h3>
234 siliconforks 2
235     <p>
236 siliconforks 14 Once you have executed the JavaScript code, you are instructed to click on the
237 siliconforks 2 "Summary" tab.
238     </p>
239    
240     <img src="screenshot4.png" alt="Screenshot">
241    
242     <p>
243 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
244 siliconforks 2 </p>
245    
246     <img src="screenshot5.png" alt="Screenshot">
247    
248 siliconforks 41 <p>
249     You can click one of the links to get a detailed view of a JavaScript source file.
250     </p>
251    
252     <img src="screenshot6.png" alt="Screenshot">
253    
254 siliconforks 14 <h2>Inverted mode</h2>
255    
256     <p>
257 siliconforks 41 In some situations it may be difficult to execute your code within the
258 siliconforks 14 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 siliconforks 41 mode</dfn>, which may be useful in this case.
262 siliconforks 14 </p>
263    
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>
270    
271     <pre>
272     window.open("path/to/jscoverage.html");
273     </pre>
274    
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>
281    
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>
286    
287     <pre>
288     &lt;button onclick='window.open("path/to/jscoverage.html");'&gt;Coverage report&lt;/button&gt;
289     </pre>
290    
291     <p>
292 siliconforks 37 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>
295    
296     <p>
297 siliconforks 14 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>
300    
301     <pre>
302     jscoverage doc/example-inverted doc/instrumented-inverted
303     firefox "doc/instrumented-inverted/index.html"
304     </pre>
305    
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>
310    
311 siliconforks 115 <h2><code>jscoverage</code> command line options</h2>
312 siliconforks 19
313     <p>
314     The <code>jscoverage</code> program accepts the following options:
315     </p>
316    
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 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
332 siliconforks 19 <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 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
338 siliconforks 19 </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 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
343 siliconforks 19 (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>
347    
348     <h2>Query string options</h2>
349    
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>
357    
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 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
366 siliconforks 19 (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 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
369 siliconforks 19 </dl>
370    
371 siliconforks 115 <h2>Using the <code>jscoverage-server</code> program</h2>
372    
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>
378    
379     <pre>
380     cd doc/example
381     jscoverage-server --verbose
382     </pre>
383    
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>http://127.0.0.1:8080/index.html</code> can be used to request
388     <code>doc/example/index.html</code>. In addition, the special URL
389     <code>http://127.0.0.1:8080/jscoverage.html</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>
395    
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>http://127.0.0.1:8080/jscoverage.html?index.html</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>
406    
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>
412    
413     <img src="screenshot7.png" alt="Screenshot">
414    
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>
420    
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>
427    
428     <p>
429     You can also store data programmatically from your tests by adding the following to your
430     JavaScript code:
431     </p>
432    
433     <pre>
434     if (top.jscoverage_report) {
435     top.jscoverage_report();
436     }
437     </pre>
438    
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>
443    
444     <pre>
445     jscoverage-server --shutdown
446     </pre>
447    
448     <h2>Using <code>jscoverage-server --proxy</code></h2>
449    
450     <p>
451     To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
452     </p>
453    
454     <pre>
455     jscoverage-server --verbose --proxy
456     </pre>
457    
458     <p>
459     Configure your browser to use an HTTP proxy with address 127.0.0.1 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>
465    
466     <h2><code>jscoverage-server</code> command line options</h2>
467    
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>127.0.0.1</code>. Specify
480     <code>0.0.0.0</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>
502    
503 siliconforks 2 <h2>Caveats</h2>
504    
505     <ul>
506     <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
507     Expect instrumented code to take at least twice as much time to run.
508     <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
509     elements in HTML files.
510     <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
511     the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
512     <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
513     that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
514     statements, you may get strange results.
515     <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
516     those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
517     <li>JSCoverage is alpha software. Use at your own risk.
518     </ul>
519    
520     <address>
521 siliconforks 139 Copyright &copy; 2007, 2008 <a href="http://siliconforks.com/"><img src="http://siliconforks.com/siliconforks-16x16.png" width="16" height="16" class="icon" alt="Silicon Forks"></a> <a href="http://siliconforks.com/">siliconforks.com</a><br>
522 siliconforks 115 Last updated May 21, 2008<br>
523 siliconforks 2 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
524     </address>
525    
526     </body>
527     </html>

  ViewVC Help
Powered by ViewVC 1.1.24