Blog

Posted September 11, 2017

Foxdriver: A Node.js Remote Debugging Client

Sauce Labs is pleased to announce that it is open-sourcing one of its internal projects called Foxdriver. It is a Node.js remote debugging client for Firefox that allows developer to boot a fresh Firefox instance or attach themselves to an already-running instance, e.g. while running a WebDriver test. It provides access to the Firefox Remote Debugging Protocol, which is a comprehensive interface to remote-control the browser.

As part of our internal effort to surface as much information as possible about the state of a customer’s application, we built this tool to capture, for example, network data, and other useful metrics during WebDriver tests in our cloud. It also allows certain browser emulations that would not be possible using just the WebDriver protocol.

The following script demonstrates how to listen to network events during your WebDriver test. It uses WebdriverIO as the WebDriver client. In addition to that, the script creates a specific Firefox profile that is required in order to allow 3rd party clients, like Foxdriver, to connect to the browser:

1
import Foxdriver from ‘foxdriver'
2
import FirefoxProfile from 'firefox-profile' 
3
import { remote } from 'webdriverio' 
4

5
(async () => { 
6
const fp = new FirefoxProfile()
7
fp.setPreference('devtools.debugger.remote-enabled', true)
8
fp.setPreference('devtools.chrome.enabled', true)
9
fp.setPreference('devtools.debugger.prompt-connection', false) 
10

11
const zippedProfile = await new Promise((resolve, reject) => { 
12
fp.encoded((err, zippedProfile) => { 
13
if (err) return reject(err) 
14
return resolve(zippedProfile) 
15
}) 
16
}) 
17

18
const browser = remote({ 
19
desiredCapabilities: { 
20
browserName: 'firefox', 
21
'moz:firefoxOptions': { 
22
args: ['--start-debugger-server', '9222'], 
23
profile: zippedProfile 
24
} 
25
} 
26
}) 
27

28
// start browser 
29
await browser.init() 
30

31
// attach to browser 
32
const { tabs } = await Foxdriver.attach('localhost', 9222) 
33

34
// listen to network events 
35
await tabs[0].network.startListeners() 
36
await tabs[0].network.on('request', 
37
({url, method}) => console.log("new request:", method, url) 
38
) 
39

40
// open page await 
41
browser.url('https://www.mozilla.org/en-US') 
42

43
// close session 
44
await browser.end() 
45
})()

Once you’ve attached yourself to a tab, you can access various so-called “Actors”. Each Actor addresses a certain domain within the browser and allows you to listen to its events or manipulate its behavior. Some of the currently supported actors are Network, Profiler, Performance and Emulation, just to name a few. These can be very useful if you want to access functionality beyond the WebDriver protocol.

Have a look at more of such examples at https://github.com/saucelabs/foxdriver.

The first release of Foxdriver already implements most of the common actors provided by the Firefox Remote Debugging Protocol. Our team is working on covering more in order to make the whole protocol accessible over a simplified API. We are looking for your feedback and appreciate any kind of contribution. We love Open Source!

The project was highly inspired by Heather Arthur’s initial project called firefox-client.

We <3 Open Source at Sauce Labs and encourage Saucers to contribute to projects like Appium, Selenium and their own initiatives.