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

Annotation of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 74 - (hide annotations)
Thu Nov 22 15:24:39 2007 UTC (12 years ago) by siliconforks
File MIME type: text/html
File size: 12818 byte(s)
Fix `last updated' dates.

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     JSCoverage is a tool used to measure code coverage in JavaScript
13     programs.
14     </p>
15    
16     <p>
17     JSCoverage has two components:
18     </p>
19    
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>
25    
26     <h2>Installing JSCoverage</h2>
27    
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>
33    
34     <p>
35     You can extract and compile the code with the following commands:
36     </p>
37    
38     <pre>
39 siliconforks 72 tar jxvf jscoverage-0.3.1.tar.bz2
40     cd jscoverage-0.3.1/
41 siliconforks 2 ./configure
42     make
43     </pre>
44    
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>
49    
50     <pre>
51     make install
52     </pre>
53    
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>
59    
60     <h2>Using JSCoverage</h2>
61    
62     <p>
63     Using JSCoverage requires three steps:
64     </p>
65    
66     <h3>1. Instrumenting code</h3>
67    
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>
72    
73     <pre>
74     jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
75     </pre>
76    
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>
85    
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>
95    
96     <table>
97     <tr>
98     <td><pre>
99     <var>SOURCE-DIRECTORY</var>/
100     dir/
101     index.html
102     script.js
103    
104     </pre></td>
105     <td class="arrow">&rarr;</td>
106     <td><pre>
107     <var>DESTINATION-DIRECTORY</var>/
108     dir/
109     index.html
110     script.js [instrumented]
111     jscoverage.html
112     </pre></td>
113     </tr>
114     </table>
115    
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>
120    
121 siliconforks 14 <h3>2. Running instrumented code in the web application</h3>
122 siliconforks 2
123     <p>
124     Open <code>jscoverage.html</code> in your web browser.
125     The page contains a tabbed user interface:
126     </p>
127    
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>
135    
136     <img src="screenshot.png" alt="Screenshot">
137    
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 siliconforks 64 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 siliconforks 2 </p>
149    
150     <h3>3. Generating the coverage report</h3>
151    
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>
156    
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>
166    
167     <h2>Example</h2>
168    
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>
174    
175     <h3>1. Instrumenting code</h3>
176    
177     <p>
178     From the main distribution directory, execute the command:
179     </p>
180    
181     <pre>
182     jscoverage doc/example doc/instrumented
183     </pre>
184    
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>
189    
190     <h3>2. Executing instrumented code</h3>
191    
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>
197    
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>
205    
206     <pre>
207     firefox "doc/instrumented/jscoverage.html?index.html"
208     </pre>
209    
210     <img src="screenshot2.png" alt="Screenshot">
211    
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>
216    
217     <img src="screenshot3.png" alt="Screenshot">
218    
219     <h3>3. Generating the coverage report</h3>
220    
221     <p>
222 siliconforks 14 Once you have executed the JavaScript code, you are instructed to click on the
223 siliconforks 2 "Summary" tab.
224     </p>
225    
226     <img src="screenshot4.png" alt="Screenshot">
227    
228     <p>
229 siliconforks 41 You can click the checkbox to show a list of statements missed during execution.
230 siliconforks 2 </p>
231    
232     <img src="screenshot5.png" alt="Screenshot">
233    
234 siliconforks 41 <p>
235     You can click one of the links to get a detailed view of a JavaScript source file.
236     </p>
237    
238     <img src="screenshot6.png" alt="Screenshot">
239    
240 siliconforks 14 <h2>Inverted mode</h2>
241    
242     <p>
243 siliconforks 41 In some situations it may be difficult to execute your code within the
244 siliconforks 14 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 siliconforks 41 mode</dfn>, which may be useful in this case.
248 siliconforks 14 </p>
249    
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>
256    
257     <pre>
258     window.open("path/to/jscoverage.html");
259     </pre>
260    
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>
267    
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>
272    
273     <pre>
274     &lt;button onclick='window.open("path/to/jscoverage.html");'&gt;Coverage report&lt;/button&gt;
275     </pre>
276    
277     <p>
278 siliconforks 37 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>
281    
282     <p>
283 siliconforks 14 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>
286    
287     <pre>
288     jscoverage doc/example-inverted doc/instrumented-inverted
289     firefox "doc/instrumented-inverted/index.html"
290     </pre>
291    
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>
296    
297 siliconforks 19 <h2>Command line options</h2>
298    
299     <p>
300     The <code>jscoverage</code> program accepts the following options:
301     </p>
302    
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 siliconforks 41 <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
318 siliconforks 19 <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 siliconforks 41 jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
324 siliconforks 19 </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 siliconforks 59 path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
329 siliconforks 19 (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>
333    
334     <h2>Query string options</h2>
335    
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>
343    
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 siliconforks 59 <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
352 siliconforks 19 (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 siliconforks 41 (to hide the "Missing" column). By default, the "Missing" column is not displayed.
355 siliconforks 19 </dl>
356    
357 siliconforks 2 <h2>Caveats</h2>
358    
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>
373    
374     <address>
375     Copyright &copy; 2007 siliconforks.com<br>
376 siliconforks 74 Last updated November 22, 2007<br>
377 siliconforks 2 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
378     </address>
379    
380     </body>
381     </html>

  ViewVC Help
Powered by ViewVC 1.1.24