/[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 326 by siliconforks, Mon Oct 20 07:57:04 2008 UTC revision 328 by siliconforks, Wed Oct 22 09:40:53 2008 UTC
# Line 3  Line 3 
3  <head>  <head>
4  <title>JSCoverage user manual</title>  <title>JSCoverage user manual</title>
5  <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">  <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
 <script src="sh_main.min.js"></script>  
 <script src="sh_html.min.js"></script>  
 <script src="sh_javascript.min.js"></script>  
6  <link rel="stylesheet" type="text/css" href="doc.css">  <link rel="stylesheet" type="text/css" href="doc.css">
7    <script type="text/javascript" src="sh_main.min.js"></script>
8    <script type="text/javascript" src="sh_html.min.js"></script>
9    <script type="text/javascript" src="sh_javascript.min.js"></script>
10  </head>  </head>
11  <body onload="sh_highlightDocument();">  <body onload="sh_highlightDocument();">
12    
13  <h1>JSCoverage user manual</h1>  <h1>JSCoverage user manual</h1>
14    
15  <p>  <p>
16  JSCoverage is a tool that measures code coverage in JavaScript programs.  JSCoverage is a tool that measures code coverage for JavaScript programs.
17  </p>  </p>
18    
19  <p>  <p>
# Line 78  Line 78 
78  <h2>Using the <code>jscoverage</code> program</h2>  <h2>Using the <code>jscoverage</code> program</h2>
79    
80  <p>  <p>
81  Using the <code>jscoverage</code> program involves the following steps:  To demonstrate how the <code>jscoverage</code> program works, we will use the
82    trivial example JavaScript code located in the
83    <code>doc/example/</code> directory of the JSCoverage distribution.  You can run
84    this example by viewing the file <code>doc/example/index.html</code> in your web browser.
85    </p>
86    
87    <p>
88    Generating code coverage statistics for this example using the
89    <code>jscoverage</code> program involves the following steps:
90  </p>  </p>
91    
92  <h3>1. Instrumenting code</h3>  <h3>1. Instrumenting code</h3>
# Line 102  Line 110 
110  </p>  </p>
111    
112  <p>  <p>
113  For example, if you have a file  The directory structure under <var>SOURCE-DIRECTORY</var> is preserved, so that if you have a file
114  <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script  <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
115  <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then  <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
116  <code>jscoverage</code> will create a copy of the HTML file at  <code>jscoverage</code> will create a copy of the HTML file at
# Line 136  Line 144 
144  which is used to execute the instrumented code.  which is used to execute the instrumented code.
145  </p>  </p>
146    
147    <p>
148    To instrument the code in the <code>doc/example/</code> directory, execute the
149    following command from the top-level directory of the JSCoverage distribution:
150    </p>
151    
152    <pre>
153    jscoverage doc/example doc/instrumented
154    </pre>
155    
156    <p>
157    This will create the directory <code>doc/instrumented/</code> and place an
158    instrumented copy of the code from <code>doc/example/</code> in
159    <code>doc/instrumented/</code>.
160    </p>
161    
162    <table>
163    <tr>
164    <td><pre>
165    doc/example/
166      index.html
167      script.js
168    
169    </pre></td>
170    <td class="arrow">&rarr;</td>
171    <td><pre>
172    doc/instrumented/
173      index.html
174      script.js [instrumented]
175      jscoverage.html
176    </pre></td>
177    </tr>
178    </table>
179    
180  <h3>2. Executing the instrumented code in a web browser</h3>  <h3>2. Executing the instrumented code in a web browser</h3>
181    
182  <p>  <p>
183  Open <code>jscoverage.html</code> in your web browser.  Open the generated <code>jscoverage.html</code> file
184    (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
185  The page contains a tabbed user interface:  The page contains a tabbed user interface:
186  </p>  </p>
187    
# Line 156  Line 198 
198  <p>  <p>
199  The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.  The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
200  You can load a page into this frame by  You can load a page into this frame by
201  entering its URL into the "URL" input field.  For example, to load  entering its URL into the "URL" input field.
 the file <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code>, you can  
 enter the relative URL <code>dir/index.html</code> into the input field.  
202  You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>  You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
203  or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page  or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
204  from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web  from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
205  server, will give unexpected results.  server, will give unexpected results.
206  </p>  </p>
207    
 <h3>3. Generating a coverage report</h3>  
   
208  <p>  <p>
209  Once the JavaScript code in the page in the "Browser" tab has been executed, click on  For example, you can load the file <code>doc/instrumented/index.html</code> by typing
210  the "Summary" tab.  This will display the current code coverage statistics.  <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
211  </p>  </p>
212    
213  <p>  <p>
214  As long as you do not reload the  Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
215  <code>jscoverage.html</code> page, the coverage report statistics are  appending the page URL to the query string of the <code>jscoverage.html</code> URL.
216  cumulative.  If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to  For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
217  another scripted page, or by reloading the frame containing a scripted  will cause the <code>index.html</code> file to be loaded automatically.
 page) and switch to the "Summary" tab again,  
 the coverage report will combine the statistics from the previous report with any newly generated statistics.  
 Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.  
218  </p>  </p>
219    
 <h2>Example</h2>  
   
 <p>  
 The JSCoverage distribution comes with a trivial example program in the <code>doc/example</code> directory.  
 You can view the file <code>doc/example/index.html</code> in your web browser to run the (uninstrumented) program.  
 To instrument this program, follow these steps:  
 </p>  
   
 <h3>1. Instrumenting code</h3>  
   
 <p>  
 From the main distribution directory, execute the command:  
 </p>  
   
 <pre>  
 jscoverage doc/example doc/instrumented  
 </pre>  
   
 <p>  
 This will create the directory <code>doc/instrumented</code> and  
 place an instrumented copy of the code from <code>doc/example</code> in <code>doc/instrumented</code>.  
 </p>  
   
 <h3>2. Executing the instrumented code in a web browser</h3>  
   
 <p>  
 You can load the file <code>doc/instrumented/jscoverage.html</code> in your web browser and type  
 the URL for the instrumented code in the "URL" input field.  Since a relative URL is accepted, you  
 can simply type <code>index.html</code> to load the page.  
 </p>  
   
 <p>  
 Alternatively, you can append the URL to the query string of the  
 <code>jscoverage.html</code> URL; for example, if you are in the main JSCoverage  
 directory and the Firefox executable is in your <code>PATH</code>, you can load  
 the <code>jscoverage.html</code> frameset and the <code>index.html</code> page  
 all in one command line:  
 </p>  
   
 <pre>  
 firefox "doc/instrumented/jscoverage.html?index.html"  
 </pre>  
   
220  <p><img src="screenshot2.png" alt="Screenshot"></p>  <p><img src="screenshot2.png" alt="Screenshot"></p>
221    
222  <p>  <p>
223  For this particular page, the JavaScript does not execute automatically:  For this example, the JavaScript does not execute automatically:
224  you have to select one of the radio buttons to execute the code.  you have to select one of the radio buttons to execute the code.
225  </p>  </p>
226    
# Line 237  Line 229 
229  <h3>3. Generating a coverage report</h3>  <h3>3. Generating a coverage report</h3>
230    
231  <p>  <p>
232  Once you have executed the JavaScript code, you are instructed to click on the  Once the JavaScript code in the page in the "Browser" tab has been executed, click on
233  "Summary" tab.  the "Summary" tab.  This will display the current code coverage statistics.
234  </p>  </p>
235    
236  <p><img src="screenshot4.png" alt="Screenshot"></p>  <p><img src="screenshot4.png" alt="Screenshot"></p>
# Line 255  Line 247 
247    
248  <p><img src="screenshot6.png" alt="Screenshot"></p>  <p><img src="screenshot6.png" alt="Screenshot"></p>
249    
250    <p>
251    As long as you do not reload the
252    <code>jscoverage.html</code> page, the coverage report statistics are
253    cumulative.  If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
254    another scripted page, or by reloading the frame containing a scripted
255    page) and switch to the "Summary" tab again,
256    the coverage report will combine the statistics from the previous report with any newly generated statistics.
257    Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
258    </p>
259    
260  <h2>Inverted mode</h2>  <h2>Inverted mode</h2>
261    
262  <p>  <p>
# Line 299  Line 301 
301    
302  <p>  <p>
303  An example is located in the <code>doc/example-inverted</code> directory.  An example is located in the <code>doc/example-inverted</code> directory.
304  You can instrument the code and launch the <code>index.html</code> page:  You can instrument the code with the <code>jscoverage</code> program:
305  </p>  </p>
306    
307  <pre>  <pre>
308  jscoverage doc/example-inverted doc/instrumented-inverted  jscoverage doc/example-inverted doc/instrumented-inverted
 firefox "doc/instrumented-inverted/index.html"  
309  </pre>  </pre>
310    
311  <p>  <p>
312    You can load the page <code>doc/instrumented-inverted/index.html</code>
313    directly in your web browser.
314  From this page, you select one of the radio buttons and then click the "Coverage  From this page, you select one of the radio buttons and then click the "Coverage
315  report" button to launch the JSCoverage report.  report" button to launch the JSCoverage report.
316  </p>  </p>
Legend:
Removed from v.326  
changed lines
  Added in v.328
  ViewVC Help
Powered by ViewVC 1.1.24