/foxdriver

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

Primary LanguageJavaScriptApache License 2.0Apache-2.0

Foxdriver Build Status

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

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.