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

Contents of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2 - (show annotations)
Wed Aug 1 13:51:53 2007 UTC (11 years, 9 months ago) by siliconforks
File MIME type: text/html
File size: 7936 byte(s)
Initial import.

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>
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 tar jxvf jscoverage-0.1.tar.bz2
40 cd jscoverage-0.1
41 ./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 <h3>2. Executing instrumented code</h3>
122
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 </p>
145
146 <h3>3. Generating the coverage report</h3>
147
148 <p>
149 Once the JavaScript code in the page in the "Browser" tab has been executed, click on
150 the "Summary" tab. This will display the current code coverage statistics.
151 </p>
152
153 <p>
154 As long as you do not reload the
155 <code>jscoverage.html</code> page, the coverage report statistics are
156 cumulative. If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
157 another scripted page, or by reloading the frame containing a scripted
158 page) and switch to the "Summary" tab again,
159 the coverage report will combine the statistics from the previous report with any newly generated statistics.
160 Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
161 </p>
162
163 <h2>Example</h2>
164
165 <p>
166 The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.
167 You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.
168 To instrument this program, follow these steps:
169 </p>
170
171 <h3>1. Instrumenting code</h3>
172
173 <p>
174 From the main distribution directory, execute the command:
175 </p>
176
177 <pre>
178 jscoverage doc/example doc/instrumented
179 </pre>
180
181 <p>
182 This will create the directory <code>doc/instrumented</code> and
183 place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.
184 </p>
185
186 <h3>2. Executing instrumented code</h3>
187
188 <p>
189 You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type
190 the URL for the instrumented code in the "URL" input field. Since a relative URL is accepted, you
191 can simply type <code>index.html</code> to load the page.
192 </p>
193
194 <p>
195 Alternatively, you can append the URL to the query string of the
196 <code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage
197 directory and the Firefox executable is in your <code>PATH</code>, you can load
198 the <code>jscoverage.html</code> frameset and the <code>index.html</code> page
199 all in one command line:
200 </p>
201
202 <pre>
203 firefox "doc/instrumented/jscoverage.html?index.html"
204 </pre>
205
206 <img src="screenshot2.png" alt="Screenshot">
207
208 <p>
209 For this particular page, the JavaScript does not execute automatically:
210 you have to select one of the radio buttons to execute the code.
211 </p>
212
213 <img src="screenshot3.png" alt="Screenshot">
214
215 <h3>3. Generating the coverage report</h3>
216
217 <p>
218 Once you have executed the JavaScript code, you will be instructed to click on the
219 "Summary" tab.
220 </p>
221
222 <img src="screenshot4.png" alt="Screenshot">
223
224 <p>
225 From the "Summary" tab, you can click the links to get a detailed view of a JavaScript source file.
226 </p>
227
228 <img src="screenshot5.png" alt="Screenshot">
229
230 <h2>Caveats</h2>
231
232 <ul>
233 <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
234 Expect instrumented code to take at least twice as much time to run.
235 <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
236 elements in HTML files.
237 <li>HTML files must use relative URLs to reference scripts. If you use an absolute URL, your page will reference
238 the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
239 <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
240 that has exactly one statement per line. If you put multiple statements on a line, or split a line across two or more
241 statements, you may get strange results.
242 <li>JSCoverage uses frames. Some web pages that use frames may not function properly when run under JSCoverage, especially
243 those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
244 <li>JSCoverage is alpha software. Use at your own risk.
245 </ul>
246
247 <address>
248 Copyright &copy; 2007 siliconforks.com<br>
249 Last updated July 8, 2007<br>
250 <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
251 </address>
252
253 </body>
254 </html>

  ViewVC Help
Powered by ViewVC 1.1.24