chrome/common/extensions/docs/templates/articles/tut_debugging.html

   1 <h1>Tutorial: Debugging</h1>
   2
   3
   4 <p>
   5 This tutorial introduces you to using
   6 Google Chrome's built-in Developer Tools
   7 to interactively debug an extension.
   8 </p>
   9
  10
  11 <h2 id="extension-info"> View extension information </h2>
  12
  13 <p>
  14 To follow this tutorial, you need
  15 the Hello World extension that was featured in
  16 <a href="getstarted">Getting Started</a>.
  17 In this section,
  18 you'll load the extension
  19 and take a look at its information
  20 in the Extensions page.
  21 </p>
  22
  23 <ol>
  24   <li>
  25     <p>
  26       Load the Hello World extension if it isn't already running.
  27       If the extension is running,
  28       you'll see the Hello World icon
  29       <img src="examples/tutorials/getstarted/icon.png"
  30            width="19" height="19" alt=""
  31            style="margin:0" />
  32       to the right of
  33       your browser's address bar.
  34     </p>
  35
  36     <p>
  37       If the Hello World extension isn't already running,
  38       find the extension files and load them.
  39       If you don't have a handy copy of the files,
  40       extract them from this
  41       <a href="examples/tutorials/getstarted.zip" download="getstarted.zip">ZIP file</a>.
  42       See Getting Started if you need
  43       <a href="getstarted#unpacked">instructions
  44       for loading the extension</a>.
  45     </p>
  46   </li>
  47
  48   <li>
  49   Go to the Extensions page
  50   (<b>chrome://extensions</b>),
  51   and make sure the page is in Developer mode.
  52   </li>
  53
  54   <li>
  55   Look at the Hello World extension's information on that page.
  56   You can see details such as the extension's
  57   name, description, and ID.
  58   </li>
  59 </ol>
  60
  61 <h2 id="inspect-popup"> Inspect the popup </h2>
  62
  63 <p>
  64 As long as your browser is in Developer mode, it's easy to inspect popups.
  65 </p>
  66
  67 <ol>
  68   <li>
  69   Go to the Extensions page (<b>chrome://extensions</b>), and make sure Developer
  70   mode is still enabled. The Extensions page doesn't need to be open
  71   for the following to work. The browser remembers the setting,
  72   even when the page isn't shown.
  73   </li>
  74   <li>
  75   Right-click the Hello World icon
  76   <img src="examples/tutorials/getstarted/icon.png"
  77        width="19" height="19" alt=""
  78        style="margin:0" />
  79   and choose the <b>Inspect popup</b> menu item. The popup appears,
  80   and a Developer Tools window like the following should display the code
  81   for <b>popup.html</b>.
  82
  83   <p>
  84      <img src="{{static}}/images/devtools-1.gif" alt=""
  85           width="500" height="294" />
  86      </p>
  87   The popup remains open as long as the Developer Tools window does.
  88   </li>
  89   <li>
  90   If the <strong>Scripts</strong> button isn't already selected,
  91   click it.
  92
  93   </li>
  94   <li>
  95   Click the console button
  96   <img src="{{static}}/images/console-button.gif"
  97        style="margin:0; padding:0" align="absmiddle"
  98        width="26" height="22" alt="" />(second
  99   from left,
 100   at the bottom of the Developer Tools window)
 101   so that you can see both the code and the console.
 102   </li>
 103 </ol>
 104
 105 <h2 id="debug"> Use the debugger </h2>
 106
 107 <p>
 108 In this section,
 109 you'll follow the execution of the popup page
 110 as it adds images to itself.
 111 </p>
 112
 113 <ol>
 114   <li>
 115   Set a breakpoint inside the image-adding loop
 116   by searching for the string <b>img.src</b>
 117   and clicking the number of the line where it occurs
 118   (for example, <strong>37</strong>):
 119   <p>
 120   <img src="{{static}}/images/devtools-2.gif" alt=""
 121        width="500" height="294" />
 122   </p>
 123   </li>
 124
 125   <li>
 126   Make sure you can see the <b>popup.html</b> tab.
 127   It should show 20 "hello world" images.
 128   </li>
 129
 130   <li>
 131   At the console prompt, reload the popup page
 132   by entering <b>location.reload(true)</b>:
 133
 134 <pre>
 135 > <b>location.reload(true)</b>
 136 </pre>
 137
 138   <p>
 139   The popup page goes blank as it begins to reload,
 140   and its execution stops at line 37.
 141   </p>
 142   </li>
 143
 144   <li>
 145   In the upper right part of the tools window,
 146   you should see the local scope variables.
 147   This section shows the current values of all variables in the current scope.
 148   For example, in the following screenshot
 149   the value of <code>i</code> is 0, and
 150   <code>photos</code> is a node list
 151   that contains at least a few elements.
 152   (In fact, it contains 20 elements at indexes 0 through 19,
 153   each one representing a photo.)
 154
 155   <p>
 156   <img src="{{static}}/images/devtools-localvars.gif" alt=""
 157        width="225" height="215" />
 158   </p>
 159   </li>
 160
 161   <li>
 162   Click the play/pause button
 163   <img src="{{static}}/images/play-button.gif"
 164        style="margin:0; padding:0" align="absmiddle"
 165        width="22" height="20" alt="" />(near
 166   the top right of the Developer Tools window)
 167   to go through the image-processing loop a single time.
 168   Each time you click that button,
 169   the value of <code>i</code> increments and
 170   another icon appears in the popup page.
 171   For example, when <code>i</code> is 10,
 172   the popup page looks something like this:
 173   </li>
 174
 175   <p>
 176   <img src="{{static}}/images/devtools-3.gif"
 177        width="500" height="245"
 178        alt="the popup page with 10 images" />
 179   </p>
 180
 181   <li>
 182   Use the buttons next to the play/pause button
 183   to step over, into, and out of function calls.
 184   To let the page finish loading,
 185   click line <b>37</b> to disable the breakpoint,
 186   and then press play/pause
 187   <img src="{{static}}/images/play-button.gif"
 188        style="margin:0; padding:0" align="absmiddle"
 189        width="22" height="20" alt="" />to
 190   continue execution.
 191   </li>
 192
 193 </ol>
 194
 195
 196 <h2 id="summary">Summary</h2>
 197
 198 <p>
 199 This tutorial demonstrated some techniques you can use
 200 to debug your extensions:
 201 </p>
 202
 203 <ul>
 204   <li>
 205     Find your extension's ID and links to its pages in
 206     the <b>Extensions</b> page
 207     (<b>chrome://extensions</b>).
 208   </li>
 209   <li>
 210     View hard-to-reach pages
 211     (and any other file in your extension) using
 212     <b>chrome-extension://</b><em>extensionId</em><b>/</b><em>filename</em>.
 213   </li>
 214   <li>
 215     Use Developer Tools to inspect
 216     and step through a page's JavaScript code.
 217   </li>
 218   <li>
 219     Reload the currently inspected page from the console
 220     using <b>location.reload(true)</b>.
 221   </li>
 222 </ul>
 223
 224
 225 <h2 id="next">Now what?</h2>
 226
 227 <p>
 228 Now that you've been introduced to debugging,
 229 here are suggestions for what to do next:
 230 </p>
 231
 232 <ul>
 233   <li>
 234     Watch the extensions video
 235     <a href="http://www.youtube.com/watch?v=IP0nMv_NI1s&feature=PlayList&p=CA101D6A85FE9D4B&index=5">Developing and Debugging</a>.
 236   </li>
 237   <li>
 238     Try installing and inspecting other extensions,
 239     such as the
 240     <a href="samples">samples</a>.
 241   </li>
 242   <li>
 243     Try using widely available debugging APIs such as
 244     <code>console.log()</code> and <code>console.error()</code>
 245     in your extension's JavaScript code.
 246     Example: <code>console.log("Hello, world!")</code>
 247   </li>
 248   <li>
 249     Follow the <a href="http://www.chromium.org/devtools/google-chrome-developer-tools-tutorial">Developer Tools tutorial</a>,
 250     explore the
 251     <a href="http://www.chromium.org/devtools">Developer Tools site</a>,
 252     and watch some video tutorials.
 253   </li>
 254 </ul>
 255
 256
 257
 258 <p>
 259 For more ideas,
 260 see the <a href="getstarted#next-steps">Now what?</a> section
 261 of Getting Started.
 262 </p>