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

Diff of /trunk/doc/manual.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2 by siliconforks, Wed Aug 1 13:51:53 2007 UTC revision 72 by siliconforks, Thu Nov 22 03:04:55 2007 UTC
# Line 36  Line 36 
36  </p>  </p>
37    
38  <pre>  <pre>
39  tar jxvf jscoverage-0.1.tar.bz2  tar jxvf jscoverage-0.3.1.tar.bz2
40  cd jscoverage-0.1  cd jscoverage-0.3.1/
41  ./configure  ./configure
42  make  make
43  </pre>  </pre>
# Line 118  Line 118 
118  which is used to execute the instrumented code.  which is used to execute the instrumented code.
119  </p>  </p>
120    
121  <h3>2. Executing instrumented code</h3>  <h3>2. Running instrumented code in the web application</h3>
122    
123  <p>  <p>
124  Open <code>jscoverage.html</code> in your web browser.  Open <code>jscoverage.html</code> in your web browser.
# Line 141  Line 141 
141  entering its URL into the "URL" input field.  For example, to load  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  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.  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>  </p>
149    
150  <h3>3. Generating the coverage report</h3>  <h3>3. Generating the coverage report</h3>
# Line 215  Line 219 
219  <h3>3. Generating the coverage report</h3>  <h3>3. Generating the coverage report</h3>
220    
221  <p>  <p>
222  Once you have executed the JavaScript code, you will be instructed to click on the  Once you have executed the JavaScript code, you are instructed to click on the
223  "Summary" tab.  "Summary" tab.
224  </p>  </p>
225    
226  <img src="screenshot4.png" alt="Screenshot">  <img src="screenshot4.png" alt="Screenshot">
227    
228  <p>  <p>
229  From the "Summary" tab, you can click the links to get a detailed view of a JavaScript source file.  You can click the checkbox to show a list of statements missed during execution.
230  </p>  </p>
231    
232  <img src="screenshot5.png" alt="Screenshot">  <img src="screenshot5.png" alt="Screenshot">
233    
234    <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    <h2>Inverted mode</h2>
241    
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>
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    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    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    <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    <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>
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    <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>
356    
357  <h2>Caveats</h2>  <h2>Caveats</h2>
358    
359  <ul>  <ul>
# Line 246  Line 373 
373    
374  <address>  <address>
375    Copyright &copy; 2007 siliconforks.com<br>    Copyright &copy; 2007 siliconforks.com<br>
376    Last updated July 8, 2007<br>    Last updated August 26, 2007<br>
377    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>    <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
378  </address>  </address>
379    

Legend:
Removed from v.2  
changed lines
  Added in v.72

  ViewVC Help
Powered by ViewVC 1.1.24