path: root/chrome/common/extensions/docs/static/tut_debugging.html

<div id="pageData-title" class="pageData">Tutorial: Debugging</div>
<div id="pageData-showTOC" class="pageData">true</div>

<p>
This tutorial shows you how to use
Google Chrome's built-in developer tools
to view your extension's code,
display debugging output,
and interactively debug your extension.
</p>

<p class="comment">
[PENDING: Rewrite this when we update the example.]
</p>

<h2 id="files"> Get the source code </h2>

<p>
To follow this tutorial,
you use a modified version of
the Hello World extension that was featured in
<a href="getstarted.html">Getting Started</a>.
</p>

<ol>

  <li>
    <p>
    Find your copy of the Hello World extension's files.
    If you don't have a handy copy,
    extract them from this
    <a href="samples/tut_debugging.zip">ZIP file</a>.
    </p>
  </li>
  <li>
    <p> Edit <code>my_toolstrip.html</code> so that it has the following code: </p>
<pre><b>&lt;script&gt;
function helloWorld() {
  var hwFile = 'hello_world.html';
  console.log(&quot;in helloWorld()&quot;);
  window.open(hwFile);
}
&lt;/script&gt;</b>

&lt;div class=&quot;toolstrip-button&quot; onclick=&quot;<b>helloWorld();</b>&quot;&gt;
&lt;span&gt;Hello, World!&lt;/span&gt;
&lt;/div&gt;</pre>
    <p> The revised code has the same effect
    but now has some debugging output,
    thanks to the call to <code>console.log()</code>.</p>
  </li>
</ol>

<h2 id="load"> Load and inspect the extension </h2>

<ol>
  <li>
  <em>Optional:</em>
  Close all your Google Chrome windows, except for one.
  <br />
  The fewer windows you have open,
  the easier it'll be to debug the extension.
  <span class="comment">
  [PENDING: OK to say?
  Is there a better way
  to match extensions to windows?]
  </span>
  </li>
  <li>
  Go to <b>chrome://extensions</b>.
  If the extension is already running, click <b>Reload</b>.
  Otherwise, load the extension by clicking
  <b>Load unpacked extension</b>
  and choosing the folder that contains
  the modified extension files.
  </li>

  <li>
  In <b>chrome://extensions</b>,
  click the <b>Inspect</b> link
  next to <b>my_toolstrip.html</b>.
  <span class="comment">[PENDING: show this?]</span>
  <br />
  A Developer Tools window like this should appear:

  <p>
     <img src="images/devtools-1.gif" alt="" />  </p>

  <p>
  <b>Note:</b>
  If you have multiple browser windows open,
  you'll see multiple copies of <b>my_toolstrip.html</b>
  in <b>chrome://extensions</b>.
  Each copy corresponds to a window &mdash;
  or, more precisely, to an instance of the toolstrip.
  </p>
  </li>
  <li>
  If the <strong>Scripts</strong> button isn't already selected,
  click it.
  </li>
  <li>
  If <strong>my_toolstrip.html</strong> isn't already selected,
  choose it from the list of scripts.
  The result should be something like this:
  <p>
  <img src="images/devtools-2.gif" alt="" />  </p>
  </li>
</ol>

<h2 id="debug"> Debug the extension </h2>
<ol>
  <li>
  Set a debugging breakpoint at the <code>window.open()</code> statement
  by clicking <strong>5</strong> in the left column:
  <p>
  <img src="images/devtools-3.gif" alt="" />  </p>
  </li>
  <li>
  Click the Console button
  (second from left, at the bottom of the Developer Tools window)
  so that you can see both the code and the console.
  <p>
  <img src="images/devtools-4.gif" alt="" /></p>
  </li>
  <li>
  Back in the main browser window,
  click the <strong>Hello, World!</strong> button,
  so that the extension begins executing.
  You should see the output of <code>console.log()</code>
  along with the line number,
  and execution should stop just before
  the call to <code>window.open()</code>.
  <p>
  <img src="images/devtools-5.gif" alt="" />
  </p>

  <p>
  The Call Stack area at the right of the tools window shows that
  the <code>helloWorld()</code> method was called by an anonymous function
  that was called by <code>onclick</code>.
  Anywhere in the Call Stack or console that you see a file and line number
  (for example, &quot;my_toolstrip.html:4&quot;),
  you can click that text to see the relevant line of code.  </p>
  </li>
  <li>
  In the upper right part of the tools window,
  scroll down (if necessary) until you can see the local scope variables.
  This section shows the current values of all variables in the current scope.
  For example, you can see that <code>hwFile</code> is a local variable
  that has the value &quot;hello_world.html&quot;.
  <p>
  <img src="images/devtools-6.gif" alt="" />  </p>
  </li>
  <li>
  Click the buttons at the upper right of the window
  to resume execution or to step through the code.
  Once the call to <code>window.open()</code> returns,
  the main browser window should open a new tab
  that displays the contents of <code>hello_world.html</code>.</li>
</ol>

<div class="comment">
[PENDING: more stuff we might want to cover:]
<ul>
  <li>
    You can't currently use the debugger with content scripts;
    you need to use console.*.
  </li>
  <li>
    location.reload()
  </li>
</ul>
</div>

<h2 id="summary">Now what?</h2>

<p>
Now that you've been introduced to debugging,
here are suggestions for what to do next:
</p>

<ul>
  <li>
    Explore the developer tools to find more features
    <span class="comment">
    [PENDING: should point to dev tools doc]
    </span>
  </li>
  <li>
    Try installing and debugging other extensions,
    such as the
    <a href="http://dev.chromium.org/developers/design-documents/extensions/samples">samples</a>
  </li>
</ul>

<p>
For more ideas,
see the <a href="getstarted.html#summary">Now what?</a> section
of Getting Started.
</p>