/js/lib/Socket.IO-node/support/expresso/deps/jscoverage/doc/manual.html

http://github.com/onedayitwillmake/RealtimeMultiplayerNodeJs · HTML · 701 lines · 593 code · 108 blank · 0 comment · 0 complexity · b03e0de8593733116082296a53b06de4 MD5 · raw file 

    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>JSCoverage user manual</title>
    5. 

  5. <link rel="stylesheet" type="text/css" href="sh_nedit.min.css">
    6. 

  6. <link rel="stylesheet" type="text/css" href="doc.css">
    7. 

  7. <script type="text/javascript" src="sh_main.min.js"></script>
    8. 

  8. <script type="text/javascript" src="sh_html.min.js"></script>
    9. 

  9. <script type="text/javascript" src="sh_javascript.min.js"></script>
    10. 

  10. </head>
    11. 

  11. <body onload="sh_highlightDocument();">
    12. 

  12. 

  13. <h1>JSCoverage user manual</h1>
    14. 

  14. 

  15. <p>
    16. 

  16. JSCoverage is a tool that measures code coverage for JavaScript programs.
    17. 

  17. </p>
    18. 

  18. 

  19. <p>
    20. 

  20. JSCoverage works by adding instrumentation to JavaScript code before it is
    21. 

  21. executed in a web browser.  JSCoverage provides several alternative ways of doing
    22. 

  22. this:
    23. 

  23. </p>
    24. 

  24. 

  25. <ul>
    26. 

  26. <li>The simplest method is to use the <code>jscoverage</code> program to generate
    27. 

  27. instrumented JavaScript files.
    28. 

  28. </li>
    29. 

  29. <li>Alternatively, you can use the <code>jscoverage-server</code> program, a simple web server that instruments
    30. 

  30. JavaScript code as it is served.
    31. 

  31. </li>
    32. 

  32. <li>Finally, <code>jscoverage-server</code> can be run with the <code>--proxy</code> option to
    33. 

  33. act as a proxy server which instruments any JavaScript code proxied through it.
    34. 

  34. </li>
    35. 

  35. </ul>
    36. 

  36. 

  37. <p>
    38. 

  38. The <code>jscoverage-server</code> program (with or without the <code>--proxy</code>
    39. 

  39. option) has the advantage of being able to store coverage reports to the filesystem.
    40. 

  40. </p>
    41. 

  41. 

  42. <h2>Compiling JSCoverage</h2>
    43. 

  43. 

  44. <p>
    45. 

  45. You can compile JSCoverage on GNU/Linux or Microsoft Windows, using the GCC C++ compiler (<code>g++</code>). On
    46. 

  46. Windows you will require <a href="http://cygwin.com/">Cygwin</a> or <a
    47. 

  47. href="http://mingw.org/">MinGW/MSYS</a>.
    48. 

  48. </p>
    49. 

  49. 

  50. <p>
    51. 

  51. You can extract and compile the code with the following commands:
    52. 

  52. </p>
    53. 

  53. 

  54. <pre>
    55. 

  55. tar jxvf jscoverage-0.4.tar.bz2
    56. 

  56. cd jscoverage-0.4/
    57. 

  57. ./configure
    58. 

  58. make
    59. 

  59. </pre>
    60. 

  60. 

  61. <p>
    62. 

  62. This will create the <code>jscoverage</code> and <code>jscoverage-server</code>
    63. 

  63. executables (<code>jscoverage.exe</code> and <code>jscoverage-server.exe</code>
    64. 

  64. on Windows). You can install the executables in <code>/usr/local</code> with the
    65. 

  65. command:
    66. 

  66. </p>
    67. 

  67. 

  68. <pre>
    69. 

  69. make install
    70. 

  70. </pre>
    71. 

  71. 

  72. <p>
    73. 

  73. Alternatively, you may simply copy the <code>jscoverage</code> executable and/or
    74. 

  74. the <code>jscoverage-server</code> executable to a suitable location in your
    75. 

  75. <code>PATH</code>.
    76. 

  76. </p>
    77. 

  77. 

  78. <h2>Using the <code>jscoverage</code> program</h2>
    79. 

  79. 

  80. <p>
    81. 

  81. To demonstrate how the <code>jscoverage</code> program works, we will use the
    82. 

  82. trivial example JavaScript code located in the
    83. 

  83. <code>doc/example/</code> directory of the JSCoverage distribution.  You can run
    84. 

  84. this example by viewing the file <code>doc/example/index.html</code> in your web browser.
    85. 

  85. </p>
    86. 

  86. 

  87. <p>
    88. 

  88. Generating code coverage statistics for this example using the
    89. 

  89. <code>jscoverage</code> program involves the following steps:
    90. 

  90. </p>
    91. 

  91. 

  92. <h3>1. Instrumenting code</h3>
    93. 

  93. 

  94. <p>
    95. 

  95. The first step is to add instrumentation to your JavaScript code.  You do this by
    96. 

  96. executing <code>jscoverage</code> with two arguments:
    97. 

  97. </p>
    98. 

  98. 

  99. <pre>
    100. 

  100. jscoverage <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
    101. 

  101. </pre>
    102. 

  102. 

  103. <p>
    104. 

  104. <var>SOURCE-DIRECTORY</var> is the directory containing the JavaScript code to be instrumented,
    105. 

  105. and <var>DESTINATION-DIRECTORY</var> is the name of the
    106. 

  106. directory to which <code>jscoverage</code> should output the instrumented code.
    107. 

  107. The <code>jscoverage</code> program will create <var>DESTINATION-DIRECTORY</var> if necessary and (recursively) copy
    108. 

  108. <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>, instrumenting
    109. 

  109. any files ending with a <code>.js</code> extension.
    110. 

  110. </p>
    111. 

  111. 

  112. <p>
    113. 

  113. The directory structure under <var>SOURCE-DIRECTORY</var> is preserved, so that if you have a file
    114. 

  114. <code><var>SOURCE-DIRECTORY</var>/dir/index.html</code> referencing the script
    115. 

  115. <code><var>SOURCE-DIRECTORY</var>/dir/script.js</code>, then
    116. 

  116. <code>jscoverage</code> will create a copy of the HTML file at
    117. 

  117. <code><var>DESTINATION-DIRECTORY</var>/dir/index.html</code> and an instrumented
    118. 

  118. version of the script at
    119. 

  119. <code><var>DESTINATION-DIRECTORY</var>/dir/script.js</code>.
    120. 

  120. In addition, <code>jscoverage</code> creates a file called <code>jscoverage.html</code>
    121. 

  121. which is used to execute the instrumented code.
    122. 

  122. </p>
    123. 

  123. 

  124. <table>
    125. 

  125. <tr>
    126. 

  126. <td><pre>
    127. 

  127. <var>SOURCE-DIRECTORY</var>/
    128. 

  128.   dir/
    129. 

  129.     index.html
    130. 

  130.     script.js
    131. 

  131. 

  132. </pre></td>
    133. 

  133. <td class="arrow">&rarr;</td>
    134. 

  134. <td><pre>
    135. 

  135. <var>DESTINATION-DIRECTORY</var>/
    136. 

  136.   dir/
    137. 

  137.     index.html
    138. 

  138.     script.js [instrumented]
    139. 

  139.   jscoverage.html
    140. 

  140. </pre></td>
    141. 

  141. </tr>
    142. 

  142. </table>
    143. 

  143. 

  144. <p>
    145. 

  145. For the example code in the <code>doc/example/</code> directory, you can execute the
    146. 

  146. following command line from the top-level directory of the JSCoverage distribution:
    147. 

  147. </p>
    148. 

  148. 

  149. <pre>
    150. 

  150. jscoverage doc/example doc/instrumented
    151. 

  151. </pre>
    152. 

  152. 

  153. <p>
    154. 

  154. This will create the directory <code>doc/instrumented/</code> and place an
    155. 

  155. instrumented copy of the code from <code>doc/example/</code> in
    156. 

  156. <code>doc/instrumented/</code>.
    157. 

  157. </p>
    158. 

  158. 

  159. <table>
    160. 

  160. <tr>
    161. 

  161. <td><pre>
    162. 

  162. doc/example/
    163. 

  163.   index.html
    164. 

  164.   script.js
    165. 

  165. 

  166. </pre></td>
    167. 

  167. <td class="arrow">&rarr;</td>
    168. 

  168. <td><pre>
    169. 

  169. doc/instrumented/
    170. 

  170.   index.html
    171. 

  171.   script.js [instrumented]
    172. 

  172.   jscoverage.html
    173. 

  173. </pre></td>
    174. 

  174. </tr>
    175. 

  175. </table>
    176. 

  176. 

  177. <h3>2. Executing the instrumented code in a web browser</h3>
    178. 

  178. 

  179. <p>
    180. 

  180. Open the generated <code>jscoverage.html</code> file
    181. 

  181. (<code>doc/instrumented/jscoverage.html</code>) in your web browser.
    182. 

  182. The page contains a tabbed user interface:
    183. 

  183. </p>
    184. 

  184. 

  185. <ul>
    186. 

  186. <li>The "Browser" tab is used to display pages with instrumented scripts.
    187. 

  187. <li>The "Summary" tab is used to display code coverage data.
    188. 

  188. <li>The "Source" tab is used to display JavaScript code, showing the number of times
    189. 

  189. each line of code was executed.
    190. 

  190. <li>The "About" tab displays information about the current version of JSCoverage.
    191. 

  191. </ul>
    192. 

  192. 

  193. <p><img src="screenshot.png" alt="Screenshot"></p>
    194. 

  194. 

  195. <p>
    196. 

  196. The "Browser" tab contains an <code>&lt;iframe&gt;</code>, which is initially empty.
    197. 

  197. You can load a page into this frame by
    198. 

  198. entering its URL into the "URL" input field.
    199. 

  199. You can load any page located in <code><var>DESTINATION-DIRECTORY</var>/</code>
    200. 

  200. or a subdirectory underneath <code><var>DESTINATION-DIRECTORY</var>/</code>; loading a page
    201. 

  201. from outside <code><var>DESTINATION-DIRECTORY</var>/</code>, or from a foreign web
    202. 

  202. server, will give unexpected results.
    203. 

  203. </p>
    204. 

  204. 

  205. <p>
    206. 

  206. For example, you can load the file <code>doc/instrumented/index.html</code> by typing
    207. 

  207. <code>index.html</code> in the "URL" input field (relative URLs are acceptable).
    208. 

  208. </p>
    209. 

  209. 

  210. <p>
    211. 

  211. Alternatively, you can load a page into the <code>&lt;iframe&gt;</code> by
    212. 

  212. appending the page URL to the query string of the <code>jscoverage.html</code> URL.
    213. 

  213. For example, appending <code>?index.html</code> to the <code>jscoverage.html</code> URL
    214. 

  214. will cause the <code>index.html</code> file to be loaded automatically.
    215. 

  215. </p>
    216. 

  216. 

  217. <p><img src="screenshot2.png" alt="Screenshot"></p>
    218. 

  218. 

  219. <p>
    220. 

  220. For this example, the JavaScript does not execute automatically:
    221. 

  221. you have to select one of the radio buttons to execute the code.
    222. 

  222. </p>
    223. 

  223. 

  224. <p><img src="screenshot3.png" alt="Screenshot"></p>
    225. 

  225. 

  226. <h3>3. Generating a coverage report</h3>
    227. 

  227. 

  228. <p>
    229. 

  229. Once the JavaScript code in the page in the "Browser" tab has been executed, click on
    230. 

  230. the "Summary" tab.  This will display the current code coverage statistics.
    231. 

  231. </p>
    232. 

  232. 

  233. <p><img src="screenshot4.png" alt="Screenshot"></p>
    234. 

  234. 

  235. <p>
    236. 

  236. You can click the checkbox to show a list of statements missed during execution.
    237. 

  237. </p>
    238. 

  238. 

  239. <p><img src="screenshot5.png" alt="Screenshot"></p>
    240. 

  240. 

  241. <p>
    242. 

  242. You can click one of the links to get a detailed view of a JavaScript source file.
    243. 

  243. </p>
    244. 

  244. 

  245. <p><img src="screenshot6.png" alt="Screenshot"></p>
    246. 

  246. 

  247. <p>
    248. 

  248. As long as you do not reload the
    249. 

  249. <code>jscoverage.html</code> page, the coverage report statistics are
    250. 

  250. cumulative.  If you execute more JavaScript in the frame in the "Browser" tab (e.g., by clicking on a link to
    251. 

  251. another scripted page, or by reloading the frame containing a scripted
    252. 

  252. page) and switch to the "Summary" tab again,
    253. 

  253. the coverage report will combine the statistics from the previous report with any newly generated statistics.
    254. 

  254. Reloading <code>jscoverage.html</code> resets all code coverage statistics to zero.
    255. 

  255. </p>
    256. 

  256. 

  257. <h2>Inverted mode</h2>
    258. 

  258. 

  259. <p>
    260. 

  260. In some situations it may be difficult to execute your code within the
    261. 

  261. JSCoverage "Browser" tab. For example, the code may assume that it is running in
    262. 

  262. the top-level browser window, generating errors if it is executed from within a
    263. 

  263. frame. JSCoverage has an alternative mode of operation, called <dfn>inverted
    264. 

  264. mode</dfn>, which may be useful in this case.
    265. 

  265. </p>
    266. 

  266. 

  267. <p>
    268. 

  268. Normally you load <code>jscoverage.html</code> in your web browser, and in its
    269. 

  269. "Browser" tab you launch your test code. In inverted mode, you do the
    270. 

  270. opposite: you load your test page directly in your web browser, and from there
    271. 

  271. you launch JSCoverage. To do this you need to add some code to your test page:
    272. 

  272. </p>
    273. 

  273. 

  274. <pre class="sh_javascript">
    275. 

  275. window.open('path/to/jscoverage.html');
    276. 

  276. </pre>
    277. 

  277. 

  278. <p>
    279. 

  279. The <code>"path/to/jscoverage.html"</code> should be a URL pointing to the
    280. 

  280. location of the <code>jscoverage.html</code> file (remember, this will be in the
    281. 

  281. top level of the <var>DESTINATION-DIRECTORY</var> you specified when running
    282. 

  282. the <code>jscoverage</code> executable).
    283. 

  283. </p>
    284. 

  284. 

  285. <p>
    286. 

  286. You can place this code wherever you like in your page: for example, you could
    287. 

  287. attach it to a button:
    288. 

  288. </p>
    289. 

  289. 

  290. <pre class="sh_html">
    291. 

  291. &lt;button onclick="window.open('path/to/jscoverage.html');"&gt;Coverage report&lt;/button&gt;
    292. 

  292. </pre>
    293. 

  293. 

  294. <p>
    295. 

  295. Note that you <em>must</em> use a <code>window.open</code> call; simply making a
    296. 

  296. link to <code>jscoverage.html</code> is not sufficient.
    297. 

  297. </p>
    298. 

  298. 

  299. <p>
    300. 

  300. An example is located in the <code>doc/example-inverted</code> directory.
    301. 

  301. You can instrument the code with the <code>jscoverage</code> program:
    302. 

  302. </p>
    303. 

  303. 

  304. <pre>
    305. 

  305. jscoverage doc/example-inverted doc/instrumented-inverted
    306. 

  306. </pre>
    307. 

  307. 

  308. <p>
    309. 

  309. You can load the page <code>doc/instrumented-inverted/index.html</code>
    310. 

  310. directly in your web browser.
    311. 

  311. From this page, you select one of the radio buttons and then click the "Coverage
    312. 

  312. report" button to launch the JSCoverage report.
    313. 

  313. </p>
    314. 

  314. 

  315. <p>
    316. 

  316. Another example is located in the <code>doc/example-jsunit</code> directory.
    317. 

  317. See the <a href="faq.html#jsunit">FAQ</a> for more information.
    318. 

  318. </p>
    319. 

  319. 

  320. <h2><code>jscoverage</code> command line options</h2>
    321. 

  321. 

  322. <p>
    323. 

  323. The <code>jscoverage</code> program accepts the following options:
    324. 

  324. </p>
    325. 

  325. 

  326. <dl>
    327. 

  327. <dt><code>-h</code>, <code>--help</code>
    328. 

  328. <dd>Display a brief help message.
    329. 

  329. <dt><code>-V</code>, <code>--version</code>
    330. 

  330. <dd>Display the version of the program.
    331. 

  331. <dt><code>-v</code>, <code>--verbose</code>
    332. 

  332. <dd>Explain what is being done.
    333. 

  333. <dt><code>--encoding=<var>ENCODING</var></code>
    334. 

  334. <dd>Assume that all JavaScript files use the given character encoding.  The
    335. 

  335. default is ISO-8859-1.
    336. 

  336. <dt><code>--exclude=<var>PATH</var></code>
    337. 

  337. <dd>The command
    338. 

  338. <pre>
    339. 

  339. jscoverage --exclude=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
    340. 

  340. </pre>
    341. 

  341. copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
    342. 

  342. recursively, but does not copy <var>SOURCE-DIRECTORY</var>/<var>PATH</var>.
    343. 

  343. <var>PATH</var> must be a complete path relative to <var>SOURCE-DIRECTORY</var>.
    344. 

  344. <var>PATH</var> can be a file or a directory (in which case the directory and
    345. 

  345. its entire contents are skipped). This option may be given multiple times.
    346. 

  346. <dt><code>--js-version=<var>VERSION</var></code>
    347. 

  347. <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
    348. 

  348. are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
    349. 

  349. or <code>ECMAv3</code> (the default).
    350. 

  350. <dt><code>--no-highlight</code>
    351. 

  351. <dd>Do not perform syntax highlighting of JavaScript code.
    352. 

  352. <dt><code>--no-instrument=<var>PATH</var></code>
    353. 

  353. <dd>The command
    354. 

  354. <pre>
    355. 

  355. jscoverage --no-instrument=<var>PATH</var> <var>SOURCE-DIRECTORY</var> <var>DESTINATION-DIRECTORY</var>
    356. 

  356. </pre>
    357. 

  357. copies <var>SOURCE-DIRECTORY</var> to <var>DESTINATION-DIRECTORY</var>
    358. 

  358. recursively, but does not instrument any JavaScript code in
    359. 

  359. <var>SOURCE-DIRECTORY</var>/<var>PATH</var>. <var>PATH</var> must be a complete
    360. 

  360. path relative to <var>SOURCE-DIRECTORY</var>. <var>PATH</var> can be a
    361. 

  361. (JavaScript) file or a directory (in which case any JavaScript files located
    362. 

  362. anywhere underneath the directory are not instrumented). This option may be
    363. 

  363. given multiple times.
    364. 

  364. </dl>
    365. 

  365. 

  366. <h2>Query string options</h2>
    367. 

  367. 

  368. <p>
    369. 

  369. When accessing <code>jscoverage.html</code> in a web browser, you may provide a
    370. 

  370. query string consisting of options separated by ampersand (<code>&amp;</code>)
    371. 

  371. or semicolon (<code>;</code>). Any option not containing an equals sign
    372. 

  372. (<code>=</code>) is considered to be a URL which will be loaded in the "Browser"
    373. 

  373. tab.
    374. 

  374. </p>
    375. 

  375. 

  376. <dl>
    377. 

  377. <dt><code>u=<var>URL</var></code>, <code>url=<var>URL</var></code>
    378. 

  378. <dd>Load <var>URL</var> in the "Browser" tab.  (This is the same as specifying
    379. 

  379. an option without an equals sign.)
    380. 

  380. <dt><code>m=<var>BOOLEAN</var></code>, <code>missing=<var>BOOLEAN</var></code>
    381. 

  381. <dd>Determines whether to initially display the "Missing" column in the "Summary"
    382. 

  382. tab.  <var>BOOLEAN</var> can be 
    383. 

  383. <code>true</code>, <code>t</code>, <code>yes</code>, <code>y</code>, <code>on</code>, <code>1</code>
    384. 

  384. (to display the "Missing" column), or
    385. 

  385. <code>false</code>, <code>f</code>, <code>no</code>, <code>n</code>, <code>off</code>, <code>0</code>
    386. 

  386. (to hide the "Missing" column).  By default, the "Missing" column is not displayed.
    387. 

  387. </dl>
    388. 

  388. 

  389. <h2>Using the <code>jscoverage-server</code> program</h2>
    390. 

  390. 

  391. <p>
    392. 

  392. The <code>jscoverage-server</code> program is a simple web server. You can use
    393. 

  393. <code>jscoverage-server</code> to serve files from the <code>doc/example/</code>
    394. 

  394. directory:
    395. 

  395. </p>
    396. 

  396. 

  397. <pre>
    398. 

  398.   cd doc/example
    399. 

  399.   jscoverage-server --verbose
    400. 

  400. </pre>
    401. 

  401. 

  402. <p>
    403. 

  403. Once the server is running, you can access the JSCoverage web interface by
    404. 

  404. visiting the URL <code>http://127.0.0.1:8080/jscoverage.html</code>, and you can
    405. 

  405. load the <code>doc/example/index.html</code> file by entering
    406. 

  406. <code>index.html</code> in the "URL" input field.  (Or you can do this all in
    407. 

  407. one step by loading the URL
    408. 

  408. <code>http://127.0.0.1:8080/jscoverage.html?index.html</code> in your web
    409. 

  409. browser.)  The
    410. 

  410. <code>jscoverage-server</code> program automatically instruments any served
    411. 

  411. JavaScript code, so that code coverage data will be gathered as the code is
    412. 

  412. executed in your browser.
    413. 

  413. </p>
    414. 

  414. 

  415. <p>
    416. 

  416. The web interface is slightly different from that generated by the
    417. 

  417. <code>jscoverage</code> program: it has a new tab named "Store".
    418. 

  418. To store coverage data, click the "Store" tab.
    419. 

  419. </p>
    420. 

  420. 

  421. <p><img src="screenshot7.png" alt="Screenshot"></p>
    422. 

  422. 

  423. <p>
    424. 

  424. When you click the "Store Report" button, the coverage data will be saved to a directory named <code>jscoverage-report/</code>.
    425. 

  425. You can view this stored report at any time by opening the file <code>jscoverage-report/jscoverage.html</code> in
    426. 

  426. your web browser - you don't need the <code>jscoverage-server</code> running to access it.
    427. 

  427. </p>
    428. 

  428. 

  429. <p>
    430. 

  430. If you use the "Store" tab again to store coverage data, the new data will be merged with
    431. 

  431. the previous data in the <code>jscoverage-report/</code> directory.  This can be useful,
    432. 

  432. for instance, if you wish to run a set of tests in different browsers and generate an
    433. 

  433. aggregate report which combines the data for all of them.
    434. 

  434. </p>
    435. 

  435. 

  436. <p>
    437. 

  437. You can stop the server by running another instance of <code>jscoverage-server</code> with the
    438. 

  438. <code>--shutdown</code> option:
    439. 

  439. </p>
    440. 

  440. 

  441. <pre>
    442. 

  442.   jscoverage-server --shutdown
    443. 

  443. </pre>
    444. 

  444. 

  445. <h2>Using <code>jscoverage-server --proxy</code></h2>
    446. 

  446. 

  447. <p>
    448. 

  448. To use <code>jscoverage-server</code> as a proxy server, use the <code>--proxy</code> option:
    449. 

  449. </p>
    450. 

  450. 

  451. <pre>
    452. 

  452.   jscoverage-server --verbose --proxy
    453. 

  453. </pre>
    454. 

  454. 

  455. <p>
    456. 

  456. Configure your browser to use an HTTP proxy with address 127.0.0.1 and port 8080.
    457. 

  457. You can then generate code coverage data for a web page on the server <code>example.com</code>
    458. 

  458. by accessing the JSCoverage web interface at the special URL <code>http://example.com/jscoverage.html</code>.  
    459. 

  459. Note that this URL is not provided by the <code>example.com</code> server; it is automatically generated
    460. 

  460. by the proxy server whenever a URL with path <code>/jscoverage.html</code> is requested.
    461. 

  461. </p>
    462. 

  462. 

  463. <h2><code>jscoverage-server</code> command line options</h2>
    464. 

  464. 

  465. <dl>
    466. 

  466. <dt><code>-h</code>, <code>--help</code>
    467. 

  467. <dd>Display a brief help message.
    468. 

  468. <dt><code>-V</code>, <code>--version</code>
    469. 

  469. <dd>Display the version of the program.
    470. 

  470. <dt><code>-v</code>, <code>--verbose</code>
    471. 

  471. <dd>Explain what is being done.
    472. 

  472. <dt><code>--document-root=<var>PATH</var></code>
    473. 

  473. <dd>Serve web content from the directory given by <var>PATH</var>.  The default is
    474. 

  474. the current directory.  This option may not be given with the <code>--proxy</code> option.
    475. 

  475. <dt><code>--encoding=<var>ENCODING</var></code>
    476. 

  476. <dd>Assume that all JavaScript files use the given character encoding.  The
    477. 

  477. default is ISO-8859-1.  Note that if you use the <code>--proxy</code> option, the
    478. 

  478. character encoding will be determined from the <code>charset</code> parameter in
    479. 

  479. the <code>Content-Type</code> HTTP header.
    480. 

  480. <dt><code>--ip-address=<var>ADDRESS</var></code>
    481. 

  481. <dd>Run the server on the IP address given by <var>ADDRESS</var>.  The default is <code>127.0.0.1</code>.  Specify
    482. 

  482. <code>0.0.0.0</code> to use any address.
    483. 

  483. <dt><code>--js-version=<var>VERSION</var></code>
    484. 

  484. <dd>Use the specified JavaScript version; valid values for <var>VERSION</var>
    485. 

  485. are <code>1.0</code>, <code>1.1</code>, <code>1.2</code>, ..., <code>1.8</code>,
    486. 

  486. or <code>ECMAv3</code> (the default).
    487. 

  487. <dt><code>--no-highlight</code>
    488. 

  488. <dd>Do not perform syntax highlighting of JavaScript code.
    489. 

  489. <dt><code>--no-instrument=<var>URL</var></code>
    490. 

  490. <dd>Do not instrument JavaScript code from <var>URL</var>.  If you are running <code>jscoverage-server</code>
    491. 

  491. with the <code>--proxy</code> option, <var>URL</var> should be a full URL.  For example:
    492. 

  492. <pre>
    493. 

  493. jscoverage-server --proxy --no-instrument=http://example.com/scripts/
    494. 

  494. </pre>
    495. 

  495. Without <code>--proxy</code>, <var>URL</var> should be only the path portion of a URL:
    496. 

  496. <pre>
    497. 

  497. jscoverage-server --no-instrument=/scripts/
    498. 

  498. </pre>
    499. 

  499. This option may be given multiple times.
    500. 

  500. <dt><code>--port=<var>PORT</var></code>
    501. 

  501. <dd>Run the server on the port given by <var>PORT</var>.  The default is port 8080.
    502. 

  502. <dt><code>--proxy</code>
    503. 

  503. <dd>Run as a proxy server.
    504. 

  504. <dt><code>--report-dir=<var>PATH</var></code>
    505. 

  505. <dd>Use the directory given by <var>PATH</var> for storing coverage reports.  The default is
    506. 

  506. <code>jscoverage-report/</code> in the current directory.
    507. 

  507. <dt><code>--shutdown</code>
    508. 

  508. <dd>Stop a running instance of the server.
    509. 

  509. </dl>
    510. 

  510. 

  511. <h2>Advanced topics</h2>
    512. 

  512. 

  513. <h3>Storing coverage reports programmatically</h3>
    514. 

  514. 

  515. <p>
    516. 

  516. If you are executing a test suite using <code>jscoverage-server</code>, you can
    517. 

  517. store a coverage report programmatically by having your test suite call the
    518. 

  518. <code>jscoverage_report</code> function (automatically generated by
    519. 

  519. <code>jscoverage-server</code>) after all your tests have finished running:
    520. 

  520. </p>
    521. 

  521. 

  522. <pre class="sh_javascript">
    523. 

  523. if (window.jscoverage_report) {
    524. 

  524.   jscoverage_report();
    525. 

  525. }
    526. 

  526. </pre>
    527. 

  527. 

  528. <p>
    529. 

  529. You can specify the name of the directory in which to store the report by
    530. 

  530. passing the name as a parameter to the <code>jscoverage_report</code> function:
    531. 

  531. </p>
    532. 

  532. 

  533. <pre class="sh_javascript">
    534. 

  534. if (window.jscoverage_report) {
    535. 

  535.   // determine the directory name based on the browser
    536. 

  536.   var directory;
    537. 

  537.   if (/MSIE/.test(navigator.userAgent)) {
    538. 

  538.     directory = 'IE';
    539. 

  539.   }
    540. 

  540.   else {
    541. 

  541.     directory = 'other';
    542. 

  542.   }
    543. 

  543.   jscoverage_report(directory);
    544. 

  544. }
    545. 

  545. </pre>
    546. 

  546. 

  547. <p>
    548. 

  548. This directory will be a subdirectory under the <code>jscoverage-report/</code>
    549. 

  549. directory (or whatever is specified with the <code>--report-dir</code> option).
    550. 

  550. Using the above example, the report would be stored to either
    551. 

  551. <code>jscoverage-report/IE/</code> or <code>jscoverage-report/other/</code>.
    552. 

  552. </p>
    553. 

  553. 

  554. <p>
    555. 

  555. It is not necessary that your test suite be executed within the
    556. 

  556. <code>jscoverage.html</code> web interface to store a coverage report.  The URL
    557. 

  557. of the test suite can simply be loaded directly in a web browser.
    558. 

  558. </p>
    559. 

  559. 

  560. <p>
    561. 

  561. The example in <code>doc/example-jsunit/</code> demonstrates storing coverage
    562. 

  562. reports programmatically.
    563. 

  563. </p>
    564. 

  564. 

  565. <h3>Ignoring certain lines of code</h3>
    566. 

  566. 

  567. <p>
    568. 

  568. Sometimes you may wish to exclude certain lines of code from coverage
    569. 

  569. statistics. Some lines of code may be executed only in certain browsers; other
    570. 

  570. lines should never be executed at all (they may be present only to detect
    571. 

  571. programming errors).  You can use specially formatted comments in your code to
    572. 

  572. tell JSCoverage to ignore certain lines of code. These lines will not be
    573. 

  573. included in the JSCoverage "Summary" tab; in the "Source" tab, these lines will
    574. 

  574. be indicated with the color yellow.
    575. 

  575. </p>
    576. 

  576. 

  577. <p>
    578. 

  578. These comments take the following form:
    579. 

  579. </p>
    580. 

  580. 

  581. <pre class="sh_javascript">
    582. 

  582. //#JSCOVERAGE_IF <var>CONDITION</var>
    583. 

  583. ...
    584. 

  584. //#JSCOVERAGE_ENDIF
    585. 

  585. </pre>
    586. 

  586. 

  587. <p>
    588. 

  588. The comment must be formatted exactly as shown: it must be a line comment
    589. 

  589. starting with <code>//</code>, it must start in the first column, and it must be
    590. 

  590. followed by <code>#JSCOVERAGE_IF</code> or <code>#JSCOVERAGE_ENDIF</code> in
    591. 

  591. uppercase letters with no intervening white space.
    592. 

  592. </p>
    593. 

  593. 

  594. <p>
    595. 

  595. The <var>CONDITION</var> is an ordinary JavaScript expression; if this
    596. 

  596. expression evaluates to <code>true</code>, then the lines of code between the
    597. 

  597. <code>//#JSCOVERAGE_IF</code> and <code>//#JSCOVERAGE_ENDIF</code> comments are
    598. 

  598. included in coverage statistics; otherwise, they are excluded from coverage
    599. 

  599. statistics.
    600. 

  600. </p>
    601. 

  601. 

  602. <p>
    603. 

  603. For example:
    604. 

  604. </p>
    605. 

  605. 

  606. <pre class="sh_javascript">
    607. 

  607. function log(s) {
    608. 

  608.   if (window.console) {
    609. 

  609. //#JSCOVERAGE_IF window.console
    610. 

  610.     console.log(s);
    611. 

  611. //#JSCOVERAGE_ENDIF
    612. 

  612.   }
    613. 

  613. }
    614. 

  614. </pre>
    615. 

  615. 

  616. <p>
    617. 

  617. You can exclude code from coverage statistics unconditionally by using
    618. 

  618. <code>#JSCOVERAGE_IF 0</code> or <code>#JSCOVERAGE_IF false</code>:
    619. 

  619. </p>
    620. 

  620. 

  621. <pre class="sh_javascript">
    622. 

  622. function f(x) {
    623. 

  623.   if (x === null) {
    624. 

  624. //#JSCOVERAGE_IF 0
    625. 

  625.     throw 'error';
    626. 

  626. //#JSCOVERAGE_ENDIF
    627. 

  627.   }
    628. 

  628.   ...
    629. 

  629. </pre>
    630. 

  630. 

  631. <p>
    632. 

  632. There is also a short form, which must appear on the line preceding an
    633. 

  633. <code>if</code> statement:
    634. 

  634. </p>
    635. 

  635. 

  636. <pre class="sh_javascript">
    637. 

  637. //#JSCOVERAGE_IF
    638. 

  638. if (...) {
    639. 

  639.   ...
    640. 

  640. }
    641. 

  641. else if (...) {
    642. 

  642.   ...
    643. 

  643. }
    644. 

  644. ...
    645. 

  645. else {
    646. 

  646.   ...
    647. 

  647. }
    648. 

  648. </pre>
    649. 

  649. 

  650. <p>
    651. 

  651. 

  652. In this form, there is no condition on the <code>//#JSCOVERAGE_IF</code> line
    653. 

  653. and no <code>//#JSCOVERAGE_ENDIF</code>. You use this form to tell JSCoverage
    654. 

  654. that you expect only one branch of the <code>if</code> statement to be executed;
    655. 

  655. coverage statistics will not be collected for the other branch(es).  For
    656. 

  656. example:
    657. 

  657. </p>
    658. 

  658. 

  659. <pre class="sh_javascript">
    660. 

  660. function log(s) {
    661. 

  661. //#JSCOVERAGE_IF
    662. 

  662.   if (window.console) {
    663. 

  663.     console.log(s);
    664. 

  664.   }
    665. 

  665.   else if (window.opera) {
    666. 

  666.     opera.postError(s);
    667. 

  667.   }
    668. 

  668.   else {
    669. 

  669.     throw 'no logging function available';
    670. 

  670.   }
    671. 

  671. }
    672. 

  672. </pre>
    673. 

  673. 

  674. <p>
    675. 

  675. Currently, <code>//#JSCOVERAGE_IF</code> comments are not recorded in stored coverage reports.
    676. 

  676. </p>
    677. 

  677. 

  678. <h2>Caveats</h2>
    679. 

  679. 

  680. <ul>
    681. 

  681. <li>JSCoverage adds instrumentation to JavaScript code, which will slow down execution speed.
    682. 

  682. Expect instrumented code to take at least twice as much time to run.
    683. 

  683. <li>JSCoverage currently instruments only <code>.js</code> files; it does not instrument code in <code>&lt;script&gt;</code>
    684. 

  684. elements in HTML files.
    685. 

  685. <li>HTML files must use relative URLs to reference scripts.  If you use an absolute URL, your page will reference
    686. 

  686. the original uninstrumented script rather than the instrumented one, and no code coverage data will be collected.
    687. 

  687. <li>JSCoverage instruments physical lines of code rather than logical JavaScript statements; it works bests with code
    688. 

  688. that has exactly one statement per line.  If you put multiple statements on a line, or  split a line across two or more
    689. 

  689. statements, you may get strange results.
    690. 

  690. <li>JSCoverage uses frames.  Some web pages that use frames may not function properly when run under JSCoverage, especially
    691. 

  691. those which try to access the top-level frame (<code>window.top</code>, <code>target="_top"</code>, etc.).
    692. 

  692. <li>JSCoverage is distributed without any warranty.  See the <a href="license.html">license</a> for more details.
    693. 

  693. </ul>
    694. 

  694. 

  695. <address>
    696. 

  696.   Copyright &copy; 2007, 2008 <a href="http://siliconforks.com/"><img src="siliconforks-16x16.png" width="16" height="16" class="icon" alt="Silicon Forks"></a> <a href="http://siliconforks.com/">siliconforks.com</a><br>
    697. 

  697.   <a href="mailto:jscoverage@siliconforks.com">jscoverage@siliconforks.com</a>
    698. 

  698. </address>
    699. 

  699. 

  700. </body>
    701. 

  701. </html>
    702.