Valence (Firefox Tools Adapter)

Valence (formerly Firefox Tools Adapter) is an experimental add-on that enables the Firefox Developer Tools to debug a wider variety of browsers, not just the Gecko-based Firefox, Firefox for Android, and Firefox OS browsers.

The initial debugging targets are Chrome on Android, Chrome Desktop and Safari on iOS.

Valence is still in its early stages and is available only as a preview. We do not yet recommend using it for day-to-day work.

Installation and setup

Installing Valence

If you use Firefox Developer Edition (any version) or Firefox 37 and later (any channel), opening WebIDE also installs the Valence add-on so you can skip this step.

Otherwise, install the latest version of the preview for your platform here.

Note: If your debugging target isn't showing up in WebIDE, make sure that the Valence add-on has not been disabled. You can find it in the Extensions section of the Add-ons Manager.

Chrome on Android setup

Valence requires Chrome 37.0 or higher (if you've installed both Chrome and Chrome Beta and both are running when connecting the Firefox Developer Tools to your device, you will only see the tabs of one of the browsers).

You will need to enable developer mode on your device, as well as USB debugging. Follow these instructions to enable developer mode.

Safari, Firefox, and other WebViews on iOS setup

Valence has been tested against Safari on iOS 6, 7 and 8, as well as the iOS Simulator on OS X. The same code supports debugging Firefox on iOS and other embedded WebViews on iOS or iOS Simulator.

You will need to enable developer support on your device. Follow the instructions on this page (in the "To enable Web Inspector on iOS" section) to get started.

iOS support uses Google's ios-webkit-debug-proxy and its fork ios-webkit-debug-proxy-win32 on Windows. No special setup needs to happen on Mac, Linux and Windows Vista (or later), Valence contains and manages the proxy. On Windows XP, download Microsoft's PowerShell before installing the add-on. On Windows, you will also see a firewall prompt the first time the proxy is launched, where you have to click Allow. Note that on Windows the device drivers are installed by iTunes, so you will need to have that installed, or, at least, the Apple Mobile Device Support and Apple Application Support applications that come with it.

Chrome Desktop setup

Valence requires Chrome 37.0 or higher. You also need to start Chrome Desktop with a special flag, as remote debugging is not enabled by default on Chrome Desktop.

The important flag is --remote-debugging-port=9222. There is a page with information on how to run the Chrome process with these flags.

There are some other flags that can be helpful if you'd like to run this alongside another Chrome profile. By running with --no-first-run, --no-default-browser-check, and --user-data-dir you can run this process alongside another Chrome profile.

For example, on OSX, you could run the following command to start a debuggable copy of Chrome:

$ /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --no-first-run --no-default-browser-check --user-data-dir=$(mktemp -d -t 'chrome-remote_data_dir')

If you click on the toolbar button, and nothing happens, you most likely don't have anything running on port 9222. Check the Browser Console to see what has gone wrong.

Running Valence

Valence works by adding to the WebIDE window that is already used to connect to Firefox OS.

  1. Connect your device: Plug it in, fire up your browser, and navigate to a page you want to work on. If you are using OS X and have Xcode installed, you can also use the iOS simulator.
  2. Start up WebIDE: Open WebIDE from the Web Developer menu in Firefox.
  3. Choose your Runtime: Open the runtime list on the right of the toolbar. Under the "Custom" section, choose "Safari, Firefox, and other WebViews on iOS" or "Chrome Desktop". For Android devices, choose "Chrome on Android" in the "USB Devices" section. You may need to accept a debugging connection from your device.
  4. Choose your Tab: From the application list on the left of the toolbar, choose the tab you want to debug.
  5. Start Debugging: Click on the Debug button (it looks like a pause button) to connect the developer tools.

Send us feedback: Report any issues or problems you run in to. You can use the issue tracker at our GitHub project. There is a ton of functionality to add, and your feedback will help us focus on the most important parts first!

FAQ

What’s under the hood?

This add-on is a new implementation of the Firefox Developer Tools Protocol. Rather than interfacing directly with content, it speaks to the remote debugging protocol surfaced by Chrome and iOS. This implementation is hosted inside the Firefox process and used internally by the Firefox Developer Tools.

When will it be ready?

We don’t know yet! We’re hard at work, and we wanted to show you our progress. When we’re confident that it’s ready to be used for full-time development, we’ll make a full release. In the meantime, the preview will regularly be updated.

How can I contribute?

The GitHub project page has instructions for getting involved with the code. Your feedback is also helpful: Talk to us on Twitter at @FirefoxDevTools, GitHub issues, or UserVoice.

Is this the same as remotedebug.org?

No. The ultimate goal of the remotedebug.org project is to provide a unified protocol for third party tools to communicate with all browsers, by standardizing on a version of the Chromium protocol. We know of no browser vendors that have committed to unifying protocols.

With Valence, we’re not currently trying to solve the problem of a standard protocol, we’re just doing what we need to do to provide the Firefox Developer Tools for these browsers. Our tool is based on the Firefox Developer Tools protocol rather than the Chromium protocol.

While the early versions of remotedebug.org’s protocol bridge served as some of the inspiration for this project, we’re taking the idea in a different direction.

Aren’t the downstream protocols constantly changing?

Yes, and we think that’s great - as vendor developer tools move at a rapid pace, we extend our protocols as fast as we develop features. We’re committed to keeping Valence up to date through these protocol changes. This is one reason we’re shipping this as an add-on rather than a built-in feature - we want updates to new protocol versions to get to you as fast as we can build them.

This isn’t easy work, but we care enough about this problem that we’re going to do what it takes to keep it going.

Can I use this protocol myself to target multiple browsers with my tool?

That is not an initial goal of Valence. But if there’s enough interest, we could consider it - get in touch.

Get help

Go to the #devtools room on IRC and we will try to help.

Document Tags and Contributors

 Last updated by: kbrosnan,