Chrome DevTools

Remote Debugging Chrome on Android

Contents

Note: For information on the interaction protocol we use for our remote debugging, please see the Debugger Protocol documentation and chrome.debugger.

Remote debugging

The experience of your web content on mobile operates very differently than what users experience on the desktop. The Google Chrome DevTools allow you to inspect, debug, and analyze the on-device experience with the full suite of tools you're used to, meaning you can use the Chrome DevTools on your development machine to debug a page on your mobile device.

Debugging Chrome for Android using the Chrome Developer Tools

Debugging occurs over USB and as long as your mobile device is connected to your development machine, you can view and change HTML, scripts and styles until you get a bug-free page that behaves perfectly on all devices.

To begin remote debugging, you will need:

  • An Android phone or tablet with Chrome for Android 32 or later installed from Google Play.
  • A USB cable to plug in your device. (Windows users will also need to install an appropriate USB device driver.)
  • Chrome 32 or later installed on your development machine.

When debugging a web application served from your development machine, you can also use reverse port forwarding to allow the mobile device to access a site from the development machine over USB.

1. Setting up your device

In order to debug over USB, you need to setup your Android device for development.

To enable USB debugging:

  • On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Yup, just tap it 7 times, even if it seems crazy. Then, return to the previous screen to find Developer options.
  • On Android 4.0 and 4.1, it's in Settings > Developer options.
USB debugging settings in Developer options

If you are developing on Windows, you need to install the appropriate USB driver for your device. See OEM USB Drivers on the Android Developers site.

2.1 Connecting directly over USB

DevTools now supports native USB debugging of connected devices. You no longer need to configure ADB or the ADB plugin to see all instances of Chrome and the Chrome-powered WebView on devices connected to your system. This functionality works on all OS's: Windows, Mac, Linux and Chrome OS.

Windows user? You'll need to install device drivers to enable communication between Windows and your device.

Just visit about:inspect and verify Discover USB Devices is checked.

about:inspect Discover USB Devices

This direct USB connection between Chrome and the device may interrupt an `adb` connection that you may be trying to establish. If you need to use the `adb` binary for other reasons, uncheck the "Discover USB Devices" checkbox, unplug the device, and plug it back in, before establishing your connection via `adb devices`.

3. Connect your device

  1. Connect your mobile device to the development machine using a USB cable.
  2. When connecting your device to your development machine, you may see an alert on the device requesting permission for USB debugging from this computer. To avoid seeing this alert each time you debug, check Always allow from this computer and click OK
USB debugging permission alert

Now, to see all connected devices, go to the Chrome menu > Tools > Inspect Devices:

You can also navigate directly to about:inspect.

This page displays each connected device and its tabs. You can have multiple devices simultaneously connected as well as multiple versions of Chrome open on each device. As indicated lower on the page, debuggable WebViews appear here, as well.

Find the tab you're interested in and click the inspect link to open DevTools on it. You may also reload the page, bring it to the front, or close it. Lastly, you can open new links on the device through a text input field.

Troubleshooting

  • On your device, verify you have Developer Options available, and USB debugging turned on. If it's working and connected, it'll set a notification on your device.
  • Verify you're using Chrome for Android 32 or later.
  • If USB debugging is on, but about:inspect doesn't show your device check that Discover USB devices is checked. If so, unplug the device and try revoking all USB authorizations in Developer Options to retry.
  • You can try Chrome Canary on desktop as new improvements land daily.

4. Debug Your Application

Inspecting a remote page using the Chrome Developer Tools

For example, inspect an element in the page you have selected and the element highlights in Chrome mobile on your device in real time. In fact, you can turn on inspect mode by clicking the icon, and then tap on your device screen.

Element inspection on a remote device

Similarly, editing scripts or executing commands from the DevTools console affects the page being inspected on your device. You can also also use all of the other panels, such as Timeline and Profiles.

Notes

  • Because we're connected over USB, you can keep the device on a real cellular network, and view the network waterfall in the Network panel under actual network conditions.
  • Chrome will prevent your screen from going to sleep while remote debugging. Be aware that whilst useful, this makes your device less secure.
  • The hardware on mobile devices often runs your content much slower, so use the Timeline to analyze how to optimize rendering and CPU for the best effect.
  • If you're running a web server on your development machine, and network restrictions prevent your mobile device from accessing the server, see reverse port forwarding.
  • You may notice that the version of the DevTools you have access to during remote debugging differs to the version you have running on your development machine. This is because the tools are synchronized with the Chrome on Android version in use.

Screencasting your device's screen

Screencasting lets you bring the experience of your device onto your machine. This allows you to keep your attention on one screen instead of switching back and forth between the device and the DevTools.

Clicking on the screencast icon Screencast in the toolbar opens up a panel on your computer displaying your device's screen. As you navigate, click, scroll, the screencast display will provide a live view of what's on your device.

While you are screencasting your device, can you control the mobile browsers's back and forward buttons, reload, and change the URL directly.

Screencast toolbar

Interacting with the screencast

You can interact with the screencast of your device in a number of ways.

  • Type on your machine's keyboard and these keystrokes are sent to the device
  • Click to tap. Clicks will be sent to the device as proper touch events.
  • Scroll by mousewheel, trackpad, or by flinging the content with your pointer.
  • Inspect Element by selecting the magnifying glass or by pressing Cmd + Shift + C
  • Zoom with a simulated pinch gesture with Cmd + Click with two fingers + Drag
  • Resize the pane that screencast is in to better size its contents.
  • Transparent portions of the screencast are covered by things like the omnibox and keyboard. Only page content is being screencasted.
Screencasting device

Note: The screencast feature repeatedly snaps screenshots on the device to give you the live view, but this does have a performance overhead. Disable screencast if you're testing framerate-sensitive situations.

Debugging Android WebViews

Starting Android 4.4 (KitKat), you can use the DevTools to debug the contents of Android WebViews inside native Android applications. Debugging WebViews requires:

  • An Android device or emulator running Android 4.4 or later, with USB debugging enabled as described in 2. Enable USB debugging on your device .
  • Chrome 30 or later. Enhanced WebView debugging UI is available in Chrome 31 or later.
  • An Android application with a WebView configured for debugging.

Configure WebViews for debugging

The Enable USB web debugging setting in Chrome doesn't affect WebViews. To debug the contents of your WebView, you need to enable it programmatically from within your application by calling setWebContentsDebuggingEnabled, a static method on the WebView class.

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true);
}

This setting applies to all of the application's WebViews. Note that web debugging is not affected by the state of the debuggable flag in the application's manifest. If you want to enable web debugging only when debuggable is true, test the flag at runtime.

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    if ( 0 != ( getApplcationInfo().flags &= ApplicationInfo.FLAG_DEBUGGABLE ) ) {
        WebView.setWebContentsDebuggingEnabled(true);
    }
}

Open a WebView in DevTools

To debug a WebView in DevTools:

  1. Connect your mobile device to the development machine using a USB cable.

    When connecting your device to your development machine, you may see an alert on the device requesting permission for USB debugging from this computer.

  2. To avoid seeing this alert each time you debug, check Always allow from this computer and click OK.

  3. In Chrome on your development machine, open about:inspect.
  4. You should see the name of your application and a list of debuggable WebViews. Click the inspect link next to one of the tabs to inspect the WebView's contents in DevTools.

Port Forwarding

Commonly you have a web server running on your local development machine, and you want to connect to that site from your device. If the mobile device and the development machine are on the same network, this is straightforward. But this may be difficult in some cases, like on a restricted corporate network.

Chrome for Android supports port fowarding making this workflow very simple to do. It works by creating a listening TCP port on your mobile device that maps to a particular TCP port on your development machine. The traffic through the forwarded port travels over USB, so it doesn't depend on the mobile device's network configuration.

This procedure assumes that you already have remote debugging configured and working.

1. Connect your mobile device

  1. Connect your device to your development machine over USB.
  2. Stop all instances of Chrome currently running on the mobile device.
  3. Open Chrome for Android.

2. Enable port forwarding

Perform the following steps on Chrome on your development machine:
  1. Open about:inspect. You should see your mobile device and a list of its open tabs.
  2. Click Port Forwarding button at the top.
  3. In the Device port field, enter the port number the Android should device listen on (defaults to 8080).
  4. In the Host field, add the IP and port number where your web application is running on localhost.
  5. Make sure to check Enable port forwarding before hitting Done.

3. Profit

On about:inspect you should now see a green circle indicating your port forwarding is succssful. Now, enter in your local URL into the Open tab field and hit Go to open it on your device's browser.

You should see the content being served by your development machine.

Authenticatie vereist

U moet daarvoor zijn aangemeld bij Google+.

U wordt aangemeld...

Google Developers heeft daarvoor uw toestemming nodig.