Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
299 lines (231 sloc) 10.3 KB
title description
Debugging Dart web apps
Learn how to use DevTools to debug your Dart web app.

You can use Chrome DevTools and the Dart development compiler (dartdevc) to debug your Dart web app.

This page walks you through using Dart with Chrome DevTools, with special attention for setup and Dart-specific considerations. For general information on debugging with Chrome DevTools, see the JavaScript debugging get started guide and reference.

Overview

* To serve your app, use `webdev serve` (which uses dartdevc), either at the command line or through your IDE. * To see Dart types in Chrome DevTools, [enable custom formatters](#enabling-custom-formatters). * You can't use Dart code in the Chrome DevTools console (`someProperty`), but sometimes you can use JavaScript code that's close (`this.someProperty`). * If you have trouble setting a breakpoint in Dart code, try [disabling and re-enabling source maps](#enabling-and-disabling-source-maps).
**Note:** A [Dart fork of Chrome DevTools][] exists but isn't ready yet for general use. For the latest status, see the [devtools-frontend README.][devtools-frontend README]

{% asset chrome-devtools-screenshot.png %}

{% comment %} NOTE TO EDITORS: Be careful to match the text formatting and terminology of the Chrome DevTools docs (https://developers.google.com/web/tools/chrome-devtools/) — especially the JavaScript debugging reference and JavaScript get started guide, so readers can easily switch back and forth between these docs.

TODO: Once Dart DevTools (or whatever we call it) is ready for use by ordinary developers, make DDT the first section/page and CDT the second, with the DDT section having all the step-by-step directions. {% endcomment %}

Getting started with Chrome DevTools {#using-chrome-devtools}

The Dart development compiler (dartdevc) has built-in support for source maps and for custom formatting of Dart objects.

Prerequisites {#prerequisites}

To use the Chrome DevTools to debug with dartdevc, you need the following software:

Walkthrough {#walkthrough}

This section leads you through the basics of using Chrome DevTools to debug a web app. If you already have an app that's ready to debug, you can skip creating the test app (step 1), but you'll need to adjust the instructions to match your app.

  1. Optional: Create an app named test_app that uses Stagehand's web-angular template.

    • If you're using the command line, here's how to create the app using Stagehand:

mkdir test_app cd test_app stagehand web-angular pub get


   * If you're using a Dart IDE or editor,
    create an **AngularDart web app** and name it `test_app`.
    You might see the description _A web app with material design components_.

1. Compile and serve the app with dartdevc,
   using either your IDE or `webdev` at the command line.

   ```terminal
   > webdev serve
**Note:** The first dartdevc compilation takes the longest, because the entire app must be compiled. After that, refreshes are much faster.
  1. Open the app in a Chrome browser window.
    For example, if you use webdev serve with no arguments, open localhost:8080{: .no-automatic-external}.

  2. Open DevTools: Press Control+Shift+I (or Command+Option+I on Mac).

  3. Enable custom formatters, so that you can see Dart types in Chrome DevTools. {% comment %} [Using Dart DevTools? You can skip this step, since custom formatters are enabled by default.] {% endcomment %}

  4. Select the Sources tab.

  5. In the File Navigator pane, select Page and navigate to the Dart file for a nontrivial component.
    For example, navigate to packages/test_app/src/todo_list/todo_list_component.dart.

  6. Set a line-of-code breakpoint in a method that's called in response to a user event.
    For example, break at the top of the add() method by clicking the line number 36. {% comment %} TODO: Add this page to https://github.com/dart-lang/stagehand/wiki/Docs-that-depend-on-stagehand. Periodically check that the line number hasn't changed, due to template changes. {% endcomment %}

  7. In the app's UI, trigger the event that causes the method call. Execution stops at the breakpoint.
    For example, type something into a text field and press Enter.

  8. In the Code Editor pane, mouse over the properties. You can see their Dart runtime types and values.
    For example, in the add() method, items is a List<String> with a length of 0.

    **Troubleshooting:** If you see `Array` instead of `List`, then custom formatters aren't on. [Enable them](#enabling-custom-formatters).
  9. Look at the Call Stack and Scope panes, which are in the JavaScript Debugging pane. Under Scope, look at the type and value of the local variable this.

  10. Resume script execution, and trigger the event again. Execution pauses again.

  11. If the console isn't visible, press Esc.

  12. In the console, try viewing a property of the component.

    For example, try to view the items object:

    • Enter items. It doesn't work because JavaScript requires a this. prefix.

    • Enter this.items. This works because the JavaScript object has the same name as the Dart object. Thanks to custom formatters, you can see the Dart type and value.

    • Enter this.items[0]. This works because Dart lists map to JavaScript arrays.

    • Enter this.items.first. This doesn't work, because unlike the Dart List class, JavaScript arrays don't have a first property.

{% comment %} Dart DevTools: items.first items.isEmpty items.length items.runtimeType [PENDING: once indexing works in DDT, tell them to try items[0]) {% endcomment %}

  1. Try other DevTools features.

Changing DevTools settings

This section covers settings that you might need to change as you debug your app.

Enabling custom formatters {#enabling-custom-formatters}

To see Dart types in Chrome DevTools, you need to enable custom formatters.

  1. From the DevTools Customize and control DevTools ⋮ menu, choose Settings. Or press F1.
  2. Select Enable custom formatters, which is under the Console heading in the Preferences settings.
  3. Close Settings: Press Esc or click the x at the upper right.

{% comment %} The best description I found was http://www.mattzeunert.com/2016/02/19/custom-chrome-devtools-object-formatters.html. {% endcomment %}

Disabling and re-enabling source maps {#enabling-and-disabling-source-maps}

Chrome DevTools enables source maps, by default. You might want to temporarily disable source maps so that you can see the generated JavaScript code.

{% comment %} In Dart DevTools, use Alt+S to toggle source maps. {% endcomment %}

  1. From the DevTools Customize and control DevTools ⋮ menu, choose Settings. Or press F1.
  2. Find the Enable JavaScript source maps checkbox, which is under the Sources heading in the Preferences settings.
    • To display only JavaScript code, clear Enable JavaScript source maps.
    • To display Dart code (when available), select Enable JavaScript source maps.
  3. Close Settings: Press Esc or click the x at the upper right.

Getting webdev and stagehand {#getting-webdev-and-stagehand}

If you're using the command line instead of an IDE or Dart-enabled editor, then you need the webdev tool. To use the command line to create apps from standard templates, you also need the stagehand tool. Use pub to get these tools:

> pub global activate webdev
> pub global activate stagehand

If your PATH environment variable is set up correctly, you can now use these tools at the command line:

> webdev --help
A tool to develop Dart web projects.
...

For information on setting PATH, see the pub global documentation.

Whenever you update the Dart SDK or want to get the latest Stagehand templates, update the tools by activating them again:

> pub global activate webdev     # update webdev
> pub global activate stagehand  # update stagehand
You can’t perform that action at this time.