firefox-client

firefox-client is a node library for remote debugging Firefox. You can use it to make things like fxconsole, a remote JavaScript REPL.

``javascript
var FirefoxClient = require("firefox-client");

var client = new FirefoxClient();

client.connect(6000, function() {
client.listTabs(function(err, tabs) {
console.log("first tab:", tabs[0].url);
});
});
`

Install

With node.js npm package manager:

`bash
npm install firefox-client
`

Connecting

$3

1. Enable remote debugging (You'll only have to do this once)
1. Open the DevTools. Web Developer > Toggle Tools
2. Visit the settings panel (gear icon)
3. Check "Enable remote debugging" under Advanced Settings

2. Listen for a connection
1. Open the Firefox command line with Tools > Web Developer > Developer Toolbar.
2. Start a server by entering this command: listen 6000 (where 6000 is the port number)

$3

Follow the instructions in this Hacks video

$3

A limited set of the API (Console, StyleSheets) is compatible with the Simulator 4.0. See the wiki instructions for connecting.

client.listTabs() will list the currently open apps in the Simulator.

$3

client.getWebapps() will expose the webapps in the Simulator, where each app implements the Tab API.

`
client.getWebapps(function(err, webapps) {
webapps.getApp("app://homescreen.gaiamobile.org/manifest.webapp", function (err, app) {
console.log("homescreen:", actor.url);
app.Console.evaluateJS("alert('foo')", function(err, resp) {
console.log("alert dismissed");
});
});
});
`

Compatibility

This latest version of the library will stay compatible with Firefox Nightly. Almost all of it will be compatible with Firefox Aurora as well.

API

A FirefoxClient is the entry point to the API. After connecting, get a Tab object with listTabs() or selectedTab(). Once you have a Tab, you can call methods and listen to events from the tab's modules, Console or Network. There are also experimental DOM and StyleSheets tab modules, and an upcoming Debugger module.

#### Methods
Almost all API calls take a callback that will get called with an error as the first argument (or null if there is no error), and a return value as the second:

`javascript
tab.Console.evaluateJS("6 + 7", function(err, resp) {
if (err) throw err;

console.log(resp.result);
});
`

#### Events

The modules are EventEmitters, listen for events with on or once, and stop listening with off:

`javascript
tab.Console.on("page-error", function(event) {
console.log("new error from tab:", event.errorMessage);
});
`

Summary of the offerings of the modules and objects:

#### FirefoxClient
Methods: connect(), disconnect(), listTabs(), selectedTab(), getWebapps(), getRoot()

Events: "error", "timeout", "end"

#### Tab
Properties: url, title

Methods: reload(), navigateTo(), attach(), detach()

Events: "navigate", "before-navigate"

#### Tab.Console
Methods: evaluateJS(), startListening(), stopListening(), getCachedLogs()

Events: "page-error", "console-api-call"

#### JSObject
Properties: class, name, displayName

Methods: ownPropertyNames(), ownPropertyDescriptor(), ownProperties(), prototype()

#### Tab.Network
Methods: startLogging(), stopLogging(), sendHTTPRequest()

Events: "network-event"

#### NetworkEvent
Properties: url, method, isXHR

Methods: getRequestHeaders(), getRequestCookies(), getRequestPostData(), getResponseHeaders(), getResponseCookies(), getResponseContent(), getEventTimings()

Events: "request-headers", "request-cookies", "request-postdata", "response-start", "response-headers", "response-cookies", "event-timings"

#### Tab.DOM
Methods: document(), documentElement(), querySelector(), querySelectorAll()

#### DOMNode
Properties: nodeValue, nodeName, namespaceURI

Methods: parentNode(), parents(), siblings(), nextSibling(), previousSibling(), querySelector(), querySelectorAll(), innerHTML(), outerHTML(), setAttribute(), remove(), release()

#### Tab.StyleSheets
Methods: getStyleSheets(), addStyleSheet()

#### StyleSheet
Properties: href, disabled, ruleCount

Methods: getText(), update(), toggleDisabled(), getOriginalSources()

Events: "disabled-changed", "ruleCount-changed"

#### Tab.Memory
Methods: measure()

#### Webapps
Methods: listRunningApps(), getInstalledApps(), watchApps(), unwatchApps(), launch(), close(), getApp(), installHosted(), installPackaged(), installPackagedWithADB(), uninstall()

Events: "appOpen", "appClose", "appInstall", "appUninstall"`

Examples

fxconsole - a remote JavaScript console for Firefox

webapps test script - a sample usage of all webapps features

Feedback

What do you need from the API? File an issue.