Foxdriver is a Node library which provides a high-level API to control Firefox over the Remote Debugging Protocol.

Getting Started

Installation

To use Foxdriver in your project, run:

$ yarn add foxdriver
# or
$ npm i foxdriver

Usage

The Firefox Remote Debugging Protocol consists of multiple actors that provide different methods. The Foxdriver API allows you to launch a Firefox instance and connects to the protocol interface automatically. From there you can access the methods of all actors.

Example - opening page and get console.logs

import Foxdriver from 'foxdriver'

(async () => {
    const { browser, tab } = await Foxdriver.launch({
        url: 'https://www.mozilla.org/en-US'
    })

    // enable actor
    await tab.console.startListeners()
    // wait until page is loaded
    await new Promise((resolve) => setTimeout(resolve, 3000))
    // receive logs and page errors
    const logs = await tab.console.getCachedMessages()
    console.log(logs)

    // close browser
    browser.close()
})()

You can also attach yourself to an already running Firefox browser. This requires to start the browser with the -start-debugger-server=<port> cli argument and have the following settings set:

• devtools.chrome.enabled: true
• devtools.debugger.prompt-connection: false
• devtools.debugger.remote-enabled: true

To attach yourself to the browser you then need to create a Foxdriver instance with the correct port and host and call the connect() method:

import Foxdriver from 'foxdriver'

(async () => {
    const { browser, tab } = await Foxdriver.attach('localhost', 9222)
    const preferences = await browser.preference.getAllPrefs()

    // ...
})()

API

• Foxdriver
  • class: Foxdriver
    • Foxdriver.attach(options)
    • Foxdriver.launch(options)
  • class: Browser
    • browser.close()
    • browser.preference
    • browser.actorRegistry
    • browser.addons
    • browser.device
    • browser.heapSnapshotFile
  • class: Tab
    • tab.attach()
    • tab.detach()
    • tab.reload()
    • tab.navigateTo(url)
    • tab.console
    • tab.memory
    • tab.performance
    • tab.profiler
    • tab.timeline
    • tab.styleSheets
    • tab.cssUsage
    • tab.cssProperties
    • tab.emulation
    • tab.inspector

Foxdriver

Foxdriver.attach(host, port)

Attaches client to an already running instance.

• host <String> host where Firefox instance was launched
• port <Number> port on which the Firefox instance was launched
• returns: <Promise<Object>>
  • tab <[Tab]> list of opened tabs
  • browser <Browser> browser instance

Foxdriver.launch(options)

Attaches client to an already running instance.

• options <Object>
  • port <Number> port on which the Firefox instance should get launched
  • bin <String> path to Firefox binary (default: OS default path)
  • args <[String]> list of arguments pass to fs.spawn (default: [])
• returns: <Promise<Object>>
  • tab <Tab> opened tab
  • browser <Browser> browser instance

class: Browser

close()

Disconnects from the browser instance and closes browser if launched via launch() method

class: Tab

tab.attach()

Attaches to this tab

• returns: <Promise> fulfills once request was sent

tab.detach()

Detaches from this tab

• returns: <Promise> fulfills once request was sent

tab.reload()

Reloads current page url.

• returns: <Promise> fulfills once request was sent

tab.navigateTo(url)

Navigates to a certain url

• url <String> url to navigate to
• returns: <Promise> fulfills once request was sent

For more information please see API docs.