tut_debugging.html revision 731df977c0511bca2206b5f333555b1205ff1f43
1<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 2 1) The <head> information in this page is significant, should be uniform 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 6 browser, it will be re-generated from the template, json schema and 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10--><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="/third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <title>Tutorial: Debugging - Google Chrome Extensions - Google Code</title></head> 19 <body> <div id="gc-container" class="labs"> 20 <div id="devModeWarning"> 21 You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. 22 </div> 23 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 24 <!-- In particular, sub-templates that recurse, must be used by allowing 25 jstemplate to make a copy of the template in this section which 26 are not operated on by way of the jsskip="true" --> 27 <div style="display:none"> 28 29 <!-- VALUE --> 30 <div id="valueTemplate"> 31 <dt> 32 <var>paramName</var> 33 <em> 34 35 <!-- TYPE --> 36 <div style="display:inline"> 37 ( 38 <span class="optional">optional</span> 39 <span class="enum">enumerated</span> 40 <span id="typeTemplate"> 41 <span> 42 <a> Type</a> 43 </span> 44 <span> 45 <span> 46 array of <span><span></span></span> 47 </span> 48 <span>paramType</span> 49 <span></span> 50 </span> 51 </span> 52 ) 53 </div> 54 55 </em> 56 </dt> 57 <dd class="todo"> 58 Undocumented. 59 </dd> 60 <dd> 61 Description of this parameter from the json schema. 62 </dd> 63 <dd> 64 This parameter was added in version 65 <b><span></span></b>. 66 You must omit this parameter in earlier versions, 67 and you may omit it in any version. If you require this 68 parameter, the manifest key 69 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 70 can ensure that your extension won't be run in an earlier browser version. 71 </dd> 72 73 <!-- OBJECT PROPERTIES --> 74 <dd> 75 <dl> 76 <div> 77 <div> 78 </div> 79 </div> 80 </dl> 81 </dd> 82 83 <!-- FUNCTION PARAMETERS --> 84 <dd> 85 <div></div> 86 </dd> 87 88 </div> <!-- /VALUE --> 89 90 <div id="functionParametersTemplate"> 91 <h5>Parameters</h5> 92 <dl> 93 <div> 94 <div> 95 </div> 96 </div> 97 </dl> 98 </div> 99 </div> <!-- /SUBTEMPLATES --> 100 101 <a id="top"></a> 102 <div id="skipto"> 103 <a href="#gc-pagecontent">Skip to page content</a> 104 <a href="#gc-toc">Skip to main navigation</a> 105 </div> 106 <!-- API HEADER --> 107 <table id="header" width="100%" cellspacing="0" border="0"> 108 <tbody><tr> 109 <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> 110 <td valign="middle" width="100%" style="padding-left:0.6em;"> 111 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 112 <div id="gsc-search-box"> 113 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 114 <input type="hidden" name="ie" value="UTF-8"> 115 <input type="text" name="q" value="" size="55"> 116 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 117 <br> 118 <span class="greytext">e.g. "page action" or "tabs"</span> 119 </div> 120 </form> 121 122 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 123 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 124 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 125 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 126 </td> 127 </tr> 128 </tbody></table> 129 130 <div id="codesiteContent" class=""> 131 132 <a id="gc-topnav-anchor"></a> 133 <div id="gc-topnav"> 134 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 135 <ul id="home" class="gc-topnav-tabs"> 136 <li id="home_link"> 137 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 138 </li> 139 <li id="docs_link"> 140 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 141 </li> 142 <li id="faq_link"> 143 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 144 </li> 145 <li id="samples_link"> 146 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 147 </li> 148 <li id="group_link"> 149 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 150 </li> 151 </ul> 152 </div> <!-- end gc-topnav --> 153 154 <div class="g-section g-tpl-170"> 155 <!-- SIDENAV --> 156 <div class="g-unit g-first" id="gc-toc"> 157 <ul> 158 <li><a href="getstarted.html">Getting Started</a></li> 159 <li><a href="overview.html">Overview</a></li> 160 <li><a href="whats_new.html">What's New?</a></li> 161 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 162 <ul> 163 <li>Browser UI 164 <ul> 165 <li><a href="browserAction.html">Browser Actions</a></li> 166 <li><a href="contextMenus.html">Context Menus</a></li> 167 <li><a href="notifications.html">Desktop Notifications</a></li> 168 <li><a href="options.html">Options Pages</a></li> 169 <li><a href="override.html">Override Pages</a></li> 170 <li><a href="pageAction.html">Page Actions</a></li> 171 <li><a href="themes.html">Themes</a></li> 172 </ul> 173 </li> 174 <li>Browser Interaction 175 <ul> 176 <li><a href="bookmarks.html">Bookmarks</a></li> 177 <li><a href="cookies.html">Cookies</a></li> 178 <li><a href="events.html">Events</a></li> 179 <li><a href="history.html">History</a></li> 180 <li><a href="management.html">Management</a></li> 181 <li><a href="tabs.html">Tabs</a></li> 182 <li><a href="windows.html">Windows</a></li> 183 </ul> 184 </li> 185 <li>Implementation 186 <ul> 187 <li><a href="a11y.html">Accessibility</a></li> 188 <li><a href="background_pages.html">Background Pages</a></li> 189 <li><a href="content_scripts.html">Content Scripts</a></li> 190 <li><a href="xhr.html">Cross-Origin XHR</a></li> 191 <li><a href="idle.html">Idle</a></li> 192 <li><a href="i18n.html">Internationalization</a></li> 193 <li><a href="messaging.html">Message Passing</a></li> 194 <li><a href="npapi.html">NPAPI Plugins</a></li> 195 </ul> 196 </li> 197 <li>Finishing 198 <ul> 199 <li><a href="hosting.html">Hosting</a></li> 200 <li><a href="external_extensions.html">Other Deployment Options</a></li> 201 </ul> 202 </li> 203 </ul> 204 </li> 205 <li><h2><a href="tutorials.html">Tutorials</a></h2> 206 <ul> 207 <li class="leftNavSelected">Debugging</li> 208 <li><a href="tut_analytics.html">Google Analytics</a></li> 209 <li><a href="tut_oauth.html">OAuth</a></li> 210 </ul> 211 </li> 212 <li><h2>Reference</h2> 213 <ul> 214 <li>Formats 215 <ul> 216 <li><a href="manifest.html">Manifest Files</a></li> 217 <li><a href="match_patterns.html">Match Patterns</a></li> 218 <!-- <li>Packages (.crx)</li> --> 219 </ul> 220 </li> 221 <li><a href="api_index.html">chrome.* APIs</a></li> 222 <li><a href="api_other.html">Other APIs</a></li> 223 </ul> 224 </li> 225 <li><h2><a href="samples.html">Samples</a></h2></li> 226 </ul> 227 </div> 228 229 <div class="g-unit" id="gc-pagecontent"> 230 <div id="pageTitle"> 231 <h1 class="page_title">Tutorial: Debugging</h1> 232 </div> 233 <!-- TABLE OF CONTENTS --> 234 <div id="toc"> 235 <h2>Contents</h2> 236 <ol> 237 <li> 238 <a href="#extension-info"> View extension information </a> 239 <ol> 240 <li style="display: none; "> 241 <a>h3Name</a> 242 </li> 243 </ol> 244 </li><li> 245 <a href="#inspect-popup"> Inspect the popup </a> 246 <ol> 247 <li style="display: none; "> 248 <a>h3Name</a> 249 </li> 250 </ol> 251 </li><li> 252 <a href="#debug"> Use the debugger </a> 253 <ol> 254 <li style="display: none; "> 255 <a>h3Name</a> 256 </li> 257 </ol> 258 </li><li> 259 <a href="#summary">Summary</a> 260 <ol> 261 <li style="display: none; "> 262 <a>h3Name</a> 263 </li> 264 </ol> 265 </li><li> 266 <a href="#next">Now what?</a> 267 <ol> 268 <li style="display: none; "> 269 <a>h3Name</a> 270 </li> 271 </ol> 272 </li> 273 <li style="display: none; "> 274 <a href="#apiReference">API reference</a> 275 <ol> 276 <li> 277 <a href="#properties">Properties</a> 278 <ol> 279 <li> 280 <a href="#property-anchor">propertyName</a> 281 </li> 282 </ol> 283 </li> 284 <li> 285 <a href="#methods">Methods</a> 286 <ol> 287 <li> 288 <a href="#method-anchor">methodName</a> 289 </li> 290 </ol> 291 </li> 292 <li> 293 <a href="#events">Events</a> 294 <ol> 295 <li> 296 <a href="#event-anchor">eventName</a> 297 </li> 298 </ol> 299 </li> 300 <li> 301 <a href="#types">Types</a> 302 <ol> 303 <li> 304 <a href="#id-anchor">id</a> 305 </li> 306 </ol> 307 </li> 308 </ol> 309 </li> 310 </ol> 311 </div> 312 <!-- /TABLE OF CONTENTS --> 313 314 <!-- Standard content lead-in for experimental API pages --> 315 <p id="classSummary" style="display: none; "> 316 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 317 </p> 318 319 <!-- STATIC CONTENT PLACEHOLDER --> 320 <div id="static"><div id="pageData-name" class="pageData">Tutorial: Debugging</div> 321<div id="pageData-showTOC" class="pageData">true</div> 322 323<p> 324This tutorial introduces you to using 325Google Chrome's built-in Developer Tools 326to interactively debug an extension. 327</p> 328 329 330<h2 id="extension-info"> View extension information </h2> 331 332<p> 333To follow this tutorial, you need 334the Hello World extension that was featured in 335<a href="getstarted.html">Getting Started</a>. 336In this section, 337you'll load the extension 338and take a look at its information 339in the Extensions page. 340</p> 341 342<ol> 343 <li> 344 <p> 345 Load the Hello World extension if it isn't already running. 346 If the extension is running, 347 you'll see the Hello World icon 348 <img src="examples/tutorials/getstarted/icon.png" width="19" height="19" alt="" style="margin:0"> 349 to the right of 350 your browser's address bar. 351 </p> 352 353 <p> 354 If the Hello World extension isn't already running, 355 find the extension files and load them. 356 If you don't have a handy copy of the files, 357 extract them from this 358 <a href="examples/tutorials/getstarted/getstarted.zip">ZIP file</a>. 359 See Getting Started if you need 360 <a href="getstarted.html#load-ext">instructions 361 for loading the extension</a>. 362 </p> 363 </li> 364 365 <li> 366 Go to the Extensions page 367 (<b>chrome://extensions</b>), 368 and make sure the page is in Developer mode. 369 </li> 370 371 <li> 372 Look at the Hello World extension's information on that page. 373 You can see details such as the extension's 374 name, description, and ID. 375 </li> 376</ol> 377 378<h2 id="inspect-popup"> Inspect the popup </h2> 379 380<p> 381As long as your browser is in Developer mode, it's easy to inspect popups. 382</p> 383 384<ol> 385 <li> 386 Go to the Extensions page (<b>chrome://extensions</b>), and make sure Developer 387 mode is still enabled. The Extensions page doesn't need to be open 388 for the following to work. The browser remembers the setting, 389 even when the page isn't shown. 390 </li> 391 <li> 392 Right-click the Hello World icon 393 <img src="examples/tutorials/getstarted/icon.png" width="19" height="19" alt="" style="margin:0"> 394 and choose the <b>Inspect popup</b> menu item. The popup appears, 395 and a Developer Tools window like the following should display the code 396 for <b>popup.html</b>. 397 398 <p> 399 <img src="images/devtools-1.gif" alt="" width="500" height="294"> 400 </p> 401 The popup remains open as long as the Developer Tools window does. 402 </li> 403 <li> 404 If the <strong>Scripts</strong> button isn't already selected, 405 click it. 406 <!-- [PENDING: can we omit this step?] --> 407 </li> 408 <li> 409 Click the console button 410 <img src="images/console-button.gif" style="margin:0; padding:0" align="absmiddle" width="26" height="22" alt="">(second 411 from left, 412 at the bottom of the Developer Tools window) 413 so that you can see both the code and the console. 414 </li> 415</ol> 416 417<h2 id="debug"> Use the debugger </h2> 418 419<p> 420In this section, 421you'll follow the execution of the popup page 422as it adds images to itself. 423</p> 424 425<ol> 426 <li> 427 Set a breakpoint inside the image-adding loop 428 by searching for the string <b>img.src</b> 429 and clicking the number of the line where it occurs 430 (for example, <strong>37</strong>): 431 <p> 432 <img src="images/devtools-2.gif" alt="" width="500" height="294"> 433 </p> 434 </li> 435 436 <li> 437 Make sure you can see the <b>popup.html</b> tab. 438 It should show 20 "hello world" images. 439 </li> 440 441 <li> 442 At the console prompt, reload the popup page 443 by entering <b>location.reload(true)</b>: 444 445<pre>> <b>location.reload(true)</b> 446</pre> 447 448 <p> 449 The popup page goes blank as it begins to reload, 450 and its execution stops at line 37. 451 </p> 452 </li> 453 454 <li> 455 In the upper right part of the tools window, 456 you should see the local scope variables. 457 This section shows the current values of all variables in the current scope. 458 For example, in the following screenshot 459 the value of <code>i</code> is 0, and 460 <code>photos</code> is a node list 461 that contains at least a few elements. 462 (In fact, it contains 20 elements at indexes 0 through 19, 463 each one representing a photo.) 464 465 <p> 466 <img src="images/devtools-localvars.gif" alt="" width="225" height="215"> 467 </p> 468 </li> 469 470 <li> 471 Click the play/pause button 472 <img src="images/play-button.gif" style="margin:0; padding:0" align="absmiddle" width="22" height="20" alt="">(near 473 the top right of the Developer Tools window) 474 to go through the image-processing loop a single time. 475 Each time you click that button, 476 the value of <code>i</code> increments and 477 another icon appears in the popup page. 478 For example, when <code>i</code> is 10, 479 the popup page looks something like this: 480 </li> 481 482 <p> 483 <img src="images/devtools-3.gif" width="500" height="245" alt="the popup page with 10 images"> 484 </p> 485 486 <li> 487 Use the buttons next to the play/pause button 488 to step over, into, and out of function calls. 489 To let the page finish loading, 490 click line <b>37</b> to disable the breakpoint, 491 and then press play/pause 492 <img src="images/play-button.gif" style="margin:0; padding:0" align="absmiddle" width="22" height="20" alt="">to 493 continue execution. 494 </li> 495 496</ol> 497 498 499<h2 id="summary">Summary</h2> 500 501<p> 502This tutorial demonstrated some techniques you can use 503to debug your extensions: 504</p> 505 506<ul> 507 <li> 508 Find your extension's ID and links to its pages in 509 the <b>Extensions</b> page 510 (<b>chrome://extensions</b>). 511 </li> 512 <li> 513 View hard-to-reach pages 514 (and any other file in your extension) using 515 <b>chrome-extension://</b><em>extensionId</em><b>/</b><em>filename</em>. 516 </li> 517 <li> 518 Use Developer Tools to inspect 519 and step through a page's JavaScript code. 520 </li> 521 <li> 522 Reload the currently inspected page from the console 523 using <b>location.reload(true)</b>. 524 </li> 525</ul> 526 527 528<h2 id="next">Now what?</h2> 529 530<p> 531Now that you've been introduced to debugging, 532here are suggestions for what to do next: 533</p> 534 535<ul> 536 <li> 537 Watch the extensions video 538 <a href="http://www.youtube.com/watch?v=IP0nMv_NI1s&feature=PlayList&p=CA101D6A85FE9D4B&index=5">Developing and Debugging</a>. 539 </li> 540 <li> 541 Try installing and inspecting other extensions, 542 such as the 543 <a href="samples.html">samples</a>. 544 </li> 545 <li> 546 Try using widely available debugging APIs such as 547 <code>console.log()</code> and <code>console.error()</code> 548 in your extension's JavaScript code. 549 Example: <code>console.log("Hello, world!")</code> 550 </li> 551 <li> 552 Follow the <a href="http://www.chromium.org/devtools/google-chrome-developer-tools-tutorial">Developer Tools tutorial</a>, 553 explore the 554 <a href="http://www.chromium.org/devtools">Developer Tools site</a>, 555 and watch some video tutorials. 556 </li> 557</ul> 558 559<!-- [PENDING: do something to help people debug content scripts, which show up in blue] --> 560 561<p> 562For more ideas, 563see the <a href="getstarted.html#summary">Now what?</a> section 564of Getting Started. 565</p> 566</div> 567 568 <!-- API PAGE --> 569 <div class="apiPage" style="display: none; "> 570 <a name="apiReference"></a> 571 <h2>API reference: chrome.apiname </h2> 572 573 <!-- PROPERTIES --> 574 <div class="apiGroup"> 575 <a name="properties"></a> 576 <h3 id="properties">Properties</h3> 577 578 <div> 579 <a></a> 580 <h4>getLastError</h4> 581 <div class="summary"> 582 <!-- Note: intentionally longer 80 columns --> 583 <span>chrome.extension</span><span>lastError</span> 584 </div> 585 <div> 586 </div> 587 </div> 588 589 </div> <!-- /apiGroup --> 590 591 <!-- METHODS --> 592 <div class="apiGroup" id="methods"> 593 <a name="methods"></a> 594 <h3>Methods</h3> 595 596 <!-- iterates over all functions --> 597 <div class="apiItem"> 598 <a></a> <!-- method-anchor --> 599 <h4>method name</h4> 600 601 <div class="summary"><span>void</span> 602 <!-- Note: intentionally longer 80 columns --> 603 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 604 <var><span></span></var></span>)</div> 605 606 <div class="description"> 607 <p class="todo">Undocumented.</p> 608 <p> 609 A description from the json schema def of the function goes here. 610 </p> 611 612 <!-- PARAMETERS --> 613 <h4>Parameters</h4> 614 <dl> 615 <div> 616 <div> 617 </div> 618 </div> 619 </dl> 620 621 <!-- RETURNS --> 622 <h4>Returns</h4> 623 <dl> 624 <div> 625 <div> 626 </div> 627 </div> 628 </dl> 629 630 <!-- CALLBACK --> 631 <div> 632 <div> 633 <h4>Callback function</h4> 634 <p> 635 The callback <em>parameter</em> should specify a function 636 that looks like this: 637 </p> 638 <p> 639 If you specify the <em>callback</em> parameter, it should 640 specify a function that looks like this: 641 </p> 642 643 <!-- Note: intentionally longer 80 columns --> 644 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 645 <dl> 646 <div> 647 <div> 648 </div> 649 </div> 650 </dl> 651 </div> 652 </div> 653 654 <!-- MIN_VERSION --> 655 <p> 656 This function was added in version <b><span></span></b>. 657 If you require this function, the manifest key 658 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 659 can ensure that your extension won't be run in an earlier browser version. 660 </p> 661 </div> <!-- /description --> 662 663 </div> <!-- /apiItem --> 664 665 </div> <!-- /apiGroup --> 666 667 <!-- EVENTS --> 668 <div class="apiGroup"> 669 <a name="events"></a> 670 <h3 id="events">Events</h3> 671 672 <!-- iterates over all events --> 673 <div class="apiItem"> 674 <a></a> 675 <h4>event name</h4> 676 677 <div class="summary"> 678 <!-- Note: intentionally longer 80 columns --> 679 <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); 680 </div> 681 682 <div class="description"> 683 <p class="todo">Undocumented.</p> 684 <p> 685 A description from the json schema def of the event goes here. 686 </p> 687 688 <!-- PARAMETERS --> 689 <h4>Parameters</h4> 690 <dl> 691 <div> 692 <div> 693 </div> 694 </div> 695 </dl> 696 697 </div> <!-- /decription --> 698 699 </div> <!-- /apiItem --> 700 701 </div> <!-- /apiGroup --> 702 703 <!-- TYPES --> 704 <div class="apiGroup"> 705 <a name="types"></a> 706 <h3 id="types">Types</h3> 707 708 <!-- iterates over all types --> 709 <div class="apiItem"> 710 <a></a> 711 <h4>type name</h4> 712 713 <div> 714 </div> 715 716 </div> <!-- /apiItem --> 717 718 </div> <!-- /apiGroup --> 719 720 </div> <!-- /apiPage --> 721 </div> <!-- /gc-pagecontent --> 722 </div> <!-- /g-section --> 723 </div> <!-- /codesiteContent --> 724 <div id="gc-footer" --=""> 725 <div class="text"> 726 <p> 727 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 728 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 729 Attribution 3.0 License</a>, and code samples are licensed under the 730 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 731 </p> 732 <p> 733 ©2010 Google 734 </p> 735 736<!-- begin analytics --> 737<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 738<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 739 740<script type="text/javascript"> 741 // chrome doc tracking 742 try { 743 var engdocs = _gat._getTracker("YT-10763712-2"); 744 engdocs._trackPageview(); 745 } catch(err) {} 746 747 // code.google.com site-wide tracking 748 try { 749 _uacct="UA-18071-1"; 750 _uanchor=1; 751 _uff=0; 752 urchinTracker(); 753 } 754 catch(e) {/* urchinTracker not available. */} 755</script> 756<!-- end analytics --> 757 </div> 758 </div> <!-- /gc-footer --> 759 </div> <!-- /gc-container --> 760</body></html> 761
