Remote Debugging

  • Revision slug: Tools/Remote_Debugging
  • Revision title: Remote Debugging
  • Revision id: 448641
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

You can use the Firefox developer tools on your desktop to debug code running remotely: in a different process on the same device or on a completely different device. To do this you use Firefox to attach the Toolbox to the remote process, and the Toolbox is then launched in its own window. At the moment the following tools support remote debugging:

This guide explains how to get set up to debug code running in Firefox for Android over USB. The other main application for remote debugging is to debug code running in the Firefox OS Simulator, but that's covered separately, in the Firefox OS Simulator documentation.

This guide's split into two parts: the first part, "Prerequisites" covers stuff you only need to do once, while the second part, "Connecting", covers stuff you need to do each time you connect the device. 

Prerequisites

First, you'll need:

  • a desktop or laptop computer with Firefox running on it
  • an Android device capable of running Firefox for Android with Firefox for Android running on it
  • a USB cable to connect the two devices

ADB setup

Next, you'll need to get the desktop and the Android device talking to each other using the adb command-line tool.

On the Android device

On the desktop

  • Install the correct version of the Android SDK for your device.
  • Using the Android SDK, install the Android Platform Tools.
  • Android Platform Tools installs adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path.

To check it worked, open up a command shell on the desktop and type:

adb devices

You should see some output like:

List of devices attached
51800F220F01564 device

(The long hex string will be different.)

If you do, then adb has found your device and you've successfully set up ADB.

Enable remote debugging

Next, you need to enable remote debugging on both the Android device and the desktop.

Firefox for Android 24 and earlier

To enable remote debugging on the device, you need to set the devtools.debugger.remote-enabled preference to true.

Go to about:config in Firefox for Android, type "devtools" into the search box and press the Search key. You'll see all the devtools preferences. Find the devtools.debugger.remote-enabled preference, and press "Toggle".

Firefox for Android 25 and later

On Firefox for Android 25 and later, there's a menu item to enable remote debugging. Open the menu, select "More", then "Settings", then "Developer tools". Check the "Remote debugging" box:

The browser will display a notification reminding you to set up port forwarding, which we'll do later on.

On the desktop

On the desktop, remote debugging is enabled by a setting in the Toolbox. Open the Toolbox, click the "Settings" button in the toolbar, and check "Enable remote debugging" in the Settings tab:

Restart the browser, and you'll see a new option in the Web Developer menu labeled "Connect...":

Connecting

Now you can connect the remote debugging tools to the device. First, attach the device to the desktop with a USB cable, if you haven't already.

On the desktop

Go to a command prompt, and type:

adb forward tcp:6000 tcp:6000

(If you've changed the value the Android device uses for a debugging port, you'll need to adjust this accordingly.)

You'll need to reissue this command each time you physically attach desktop and device with the USB cable.

Then go to the Web Developer menu on Firefox, and select "Connect...". You'll see a page that looks like this:

Unless you've changed the port numbers, choose 6000 and press the "Connect" button.

On the Android device

Next you'll see a dialog on the Android device asking you to confirm the connection:

Press "OK". The desktop waits for a few seconds to give you time to acknowledge this dialog: if it times out, just press "Connect" in the desktop dialog again.

On the desktop

Next, the desktop shows you a dialog that looks something like this:

This is asking whether you want to debug web content running in a browser tab, or to debug the browser code itself.

  • You'll see one entry under "Available remote tabs" for each open tab, and clicking it will attach the debugging tools to the web content hosted by that tab. If you want to debug your web content, you'll choose the relevant content tab.
  • You'll see one entry under "Available remote processes": this is the browser process itself. You'll choose this option if you want to debug the browser's own code.

Let's choose to attach to the mozilla.org website. The Toolbox will open in its own window, attached to the Firefox for Android tab that's currently hosting mozilla.org:

The Toolbox, and the tools it hosts, work in just the same way as they do when attached to local content.

 

 

Revision Source

<p>You can use the Firefox developer tools on your desktop to debug code running remotely: in a different process on the same device or on a completely different device. To do this you use Firefox to attach the <a href="/en-US/docs/Toolbox" title="/en-US/docs/Toolbox">Toolbox</a> to the remote process, and the Toolbox is then launched in its own window. At the moment the following tools support remote debugging:</p>
<ul>
  <li><a href="/en-US/docs/Tools/Debugger" title="/en-US/docs/Tools/Debugger">JavaScript Debugger</a></li>
  <li><a href="/en-US/docs/Tools/Style_Editor" title="/en-US/docs/Tools/Style_Editor">Style Editor</a></li>
  <li><a href="/en-US/docs/Tools/Web_Console" title="/en-US/docs/Tools/Web_Console">Web Console</a></li>
  <li><a href="/en-US/docs/Tools/Profiler" title="/en-US/docs/Tools/Profiler">Profiler</a></li>
  <li><a href="/en-US/docs/Tools/Network_Monitor" title="/en-US/docs/Tools/Network_Monitor">Network Monitor</a></li>
</ul>
<p>This guide explains how to get set up to debug code running in Firefox for Android over USB. The other main application for remote debugging is to debug code running in the Firefox OS Simulator, but that's covered separately, in the <a href="/en-US/docs/Tools/Firefox_OS_Simulator#Attaching_developer_tools" title="/en-US/docs/Tools/Firefox_OS_Simulator#Attaching_developer_tools">Firefox OS Simulator documentation</a>.</p>
<p>This guide's split into two parts: the first part, "Prerequisites" covers stuff you only need to do once, while the second part, "Connecting", covers stuff you need to do each time you connect the device.&nbsp;</p>
<h2 id="Prerequisites">Prerequisites</h2>
<p>First, you'll need:</p>
<ul>
  <li>a desktop or laptop computer with Firefox running on it</li>
  <li>an Android device <a href="https://support.mozilla.org/en-US/kb/will-firefox-work-my-mobile-device" title="https://support.mozilla.org/en-US/kb/will-firefox-work-my-mobile-device">capable of running Firefox for Android</a> with Firefox for Android running on it</li>
  <li>a USB cable to connect the two devices</li>
</ul>
<h3 id="ADB_setup">ADB setup</h3>
<p>Next, you'll need to get the desktop and the Android device talking to each other using the <a href="https://developer.android.com/tools/help/adb.html" title="https://developer.android.com/tools/help/adb.html">adb</a> command-line tool.</p>
<h4 class="note" id="On_the_Android_device"><strong>On the Android device</strong></h4>
<ul>
  <li><a href="http://developer.android.com/guide/developing/device.html#setting-up" title="http://developer.android.com/guide/developing/device.html#setting-up">Enable USB debugging (step 2 of this link only)</a>.</li>
  <li>Attach the device to the desktop via USB.</li>
</ul>
<h4 class="note" id="On_the_desktop"><strong>On the desktop</strong></h4>
<ul>
  <li>Install the correct version of the <a href="http://developer.android.com/sdk/index.html" title="http://developer.android.com/sdk/index.html">Android SDK</a> for your device.</li>
  <li>Using the Android SDK, install the <a href="http://developer.android.com/sdk/installing.html#components" title="http://developer.android.com/sdk/installing.html#components">Android Platform Tools</a>.</li>
  <li>Android Platform Tools installs adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path.</li>
</ul>
<p>To check it worked, open up a command shell on the desktop and type:</p>
<pre>
adb devices</pre>
<p>You should see some output like:</p>
<pre>
List of devices attached
51800F220F01564 device
</pre>
<p>(The long hex string will be different.)</p>
<p>If you do, then <code>adb</code> has found your device and you've successfully set up ADB.</p>
<h3 id="Enable_remote_debugging">Enable remote debugging</h3>
<p>Next, you need to enable remote debugging on both the Android device and the desktop.</p>
<h4 id="On_the_Android_device.2C_Firefox_24_and_earlier">Firefox for Android 24 and earlier</h4>
<p>To enable remote debugging on the device, you need to set the <code>devtools.debugger.remote-enabled</code> preference to <code>true</code>.</p>
<p>Go to <code>about:config</code> in Firefox for Android, type "devtools" into the search box and press the Search key. You'll see all the devtools preferences. Find the <code>devtools.debugger.remote-enabled</code> preference, and press "Toggle".</p>
<h4 id="On_the_Android_device.2C_Firefox_24_and_earlier"><img alt="" src="https://mdn.mozillademos.org/files/5803/remote-debugger-about-config-toggle.png" style="width: 394px; height: 640px; display: block; margin-left: auto; margin-right: auto;" /></h4>
<h4 class="note" id="On_the_Android_device.2C_Firefox_25_and_later">Firefox for Android 25 and later</h4>
<p>On Firefox for Android 25 and later, there's a menu item to enable remote debugging. Open the menu, select "More", then "Settings", then "Developer tools". Check the "Remote debugging" box:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5829/remote-debugging-device-enable.png" style="width: 394px; height: 640px; display: block; margin-left: auto; margin-right: auto;" /></p>
<p>The browser will display a notification reminding you to set up port forwarding, which we'll do later on.</p>
<h4 id="On_the_desktop"><strong>On the desktop</strong></h4>
<p>On the desktop, remote debugging is enabled by a setting in the Toolbox. <a href="/en-US/docs/Tools_Toolbox" title="/en-US/docs/Tools_Toolbox">Open the Toolbox</a>, click the "Settings" button in the <a href="/en-US/docs/Tools_Toolbox#Toolbar" title="/en-US/docs/Tools_Toolbox#Toolbar">toolbar</a>, and check "Enable remote debugging" in the <a href="/en-US/docs/Tools_Toolbox#Settings" title="/en-US/docs/Tools_Toolbox#Settings">Settings </a>tab:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5827/remote-debugger-toolbox-settings.png" style="width: 800px; height: 307px; display: block; margin-left: auto; margin-right: auto;" />Restart the browser, and you'll see a new option in the Web Developer menu labeled "Connect...":</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5811/remote-debugging-connect-menuitem.png" style="width: 583px; height: 503px; display: block; margin-left: auto; margin-right: auto;" /></p>
<h2 id="Connecting">Connecting</h2>
<p>Now you can connect the remote debugging tools to the device. First, attach the device to the desktop with a USB cable, if you haven't already.</p>
<div style="margin-left:25%; padding: 1em; border:solid rgb(245, 242, 240) 3px; margin-bottom: 2em;">
  <div class="note">
    <strong>On the desktop</strong></div>
  <p>Go to a command prompt, and type:</p>
  <pre>
adb forward tcp:6000 tcp:6000</pre>
  <p>(If you've changed the value the Android device uses for a debugging port, you'll need to adjust this accordingly.)</p>
  <p>You'll need to reissue this command each time you physically attach desktop and device with the USB cable.</p>
  <p>Then go to the Web Developer menu on Firefox, and select "Connect...". You'll see a page that looks like this:</p>
  <p><img alt="" src="https://mdn.mozillademos.org/files/5813/remote-debugging-desktop-connect.png" style="width: 732px; height: 686px; display: block; margin-left: auto; margin-right: auto;" />Unless you've changed the port numbers, choose 6000 and press the "Connect" button.</p>
</div>
<div style="margin-right:25%; padding: 1em; border:solid rgb(245, 242, 240) 3px; margin-bottom: 2em;">
  <div class="note">
    <strong>On the Android device</strong></div>
  <p>Next you'll see a dialog on the Android device asking you to confirm the connection:</p>
  <p><img alt="" src="https://mdn.mozillademos.org/files/5815/remote-debugging-device-connect.png" style="width: 394px; height: 640px; display: block; margin-left: auto; margin-right: auto;" />Press "OK". The desktop waits for a few seconds to give you time to acknowledge this dialog: if it times out, just press "Connect" in the desktop dialog again.</p>
</div>
<div style="margin-left:25%; padding: 1em; border:solid rgb(245, 242, 240) 3px; margin-bottom: 2em;">
  <div class="note">
    <strong>On the desktop</strong></div>
  <p>Next, the desktop shows you a dialog that looks something like this:</p>
  <p><img alt="" src="https://mdn.mozillademos.org/files/5819/remote-debugging-desktop-select-target.png" style="width: 733px; height: 688px; display: block; margin-left: auto; margin-right: auto;" />This is asking whether you want to debug web content running in a browser tab, or to debug the browser code itself.</p>
  <ul>
    <li>You'll see one entry under "Available remote tabs" for each open tab, and clicking it will attach the debugging tools to the web content hosted by that tab. If you want to debug your web content, you'll choose the relevant content tab.</li>
    <li>You'll see one entry under "Available remote processes": this is the browser process itself. You'll choose this option if you want to debug the browser's own code.</li>
  </ul>
  <p>Let's choose to attach to the mozilla.org website. The Toolbox will open in its own window, attached to the Firefox for Android tab that's currently hosting mozilla.org:</p>
  <p><img alt="" src="https://mdn.mozillademos.org/files/5821/remote-debugging-console.png" style="width: 800px; height: 392px; display: block; margin-left: auto; margin-right: auto;" /></p>
  <p>The Toolbox, and the tools it hosts, work in just the same way as they do when attached to local content.<img alt="" src="https://mdn.mozillademos.org/files/5823/remote-debugging-debugger.png" style="width: 800px; height: 392px; display: block; margin-left: auto; margin-right: auto;" /></p>
</div>
<p>&nbsp;</p>
<p>&nbsp;</p>
Revert to this revision