evghenin / foxr

🦊 Node.js API to control Firefox

foxr

Node.js API to control Firefox.

• uses a built-in Marionette through remote protocol
• no Selenium WebDriver is needed
• works with Headless mode
• compatible subset of Puppeteer API

At this point Foxr is more a proof of concept, work is pretty much in progress.

Example

Run a locally installed Firefox:

/path/to/firefox -headless -marionette -safe-mode

Or a dockerized version:

docker run -it --rm --shm-size 2g -p 2828:2828 deepsweet/firefox-headless-remote:68

import foxr from 'foxr'
// const foxr = require('foxr').default

(async () => {
  try {
    const browser = await foxr.connect()
    const page = await browser.newPage()

    await page.goto('https://example.com')
    await page.screenshot({ path: 'example.png' })
    await browser.close()
  } catch (error) {
    console.error(error)
  }
})()

Install

yarn add --dev foxr
# or
npm install --save-dev foxr

API

Foxr

connect

Connect to the Marionette endpoint.

type TConnectOptions = {
  host?: string,
  port?: number,
  defaultViewport?: {
    width?: number,
    height?: number
  }
}

foxr.connect(options?: TConnectOptions): Promise<Browser>

• host – 'localhost' by default
• port – 2828 by default
• defaultViewport
  • width – 800 by default
  • height – 600 by default

launch

type TLaunchOptions = {
  args?: string[],
  dumpio?: boolean,
  executablePath: string,
  headless?: boolean
} & TConnectOptions

foxr.launch(options?: TLaunchOptions): Promise<Browser>

• args – array of additional args, ['-marionette', '-safe-mode', '-no-remote'] by default
• dumpio – print browser process stdout and stderr, false by default
• executablePath – path to Firefox executable, required
• headless – whether to run browser in headless mode, true by default

Browser

close

browser.close(): Promise<void>

disconnect

browser.disconnect(): Promise<void>

newPage

browser.newPage(): Promise<Page>

pages

browser.pages(): Promise<Page[]>

install

browser.install(extensionPath: string, isTemporary: boolean): Promise<string | null>

uninstall

browser.install(extensionId: string): Promise<void>

getPref

browser.getPref(pref: string, defaultBranch: boolean = false): Promise<any>

setPref

browser.setPref(pref: string, value: string | number | boolean, defaultBranch: boolean = false): Promise<void>

Page

$

page.$(selector: string): Promise<ElementHandle | null>

$$

page.$$(selector: string): Promise<ElementHandle[]>

$eval

page.$eval(selector: string, func: TSerializableFunction, ...args: TEvaluateArg[]): Promise<TJsonValue | void>

$$eval

page.$$eval(selector: string, func: TSerializableFunction, ...args: TEvaluateArg[]): Promise<Array<TJsonValue | void>>

bringToFront

page.bringToFront(): Promise<void>

browser

page.browser(): TBrowser

close

page.close(): Promise<void>

content

page.content(): Promise<string>

evaluate

page.evaluate(target: string): Promise<TJsonValue | void>
page.evaluate(target: TSerializableFunction, ...args: TEvaluateArg[]): Promise<TJsonValue | void>

evaluateHandle

page.evaluate(target: string): Promise<JSHandle>
page.evaluate(target: TSerializableFunction, ...args: TEvaluateArg[]): Promise<JSHandle>

focus

page.focus(selector: string): Promise<void>

goto

page.goto(url: string): Promise<void>

screenshot

page.screenshot(options?: { path?: string }): Promise<Buffer>

setContent

page.setContent(html: string): Promise<void>

title

page.title(): Promise<string>

url

page.url(): Promise<string>

viewport

page.viewport(): Promise<{ width: number, height: number }>

JSHandle

…

ElementHandle

$

elementHandle.$(selector: string): Promise<ElementHandle | null>

$$

elementHandle.$$(selector: string): Promise<ElementHandle[]>

click

type TOptions = {
  button?: 'left' | 'middle' | 'right',
  clickCount?: number
}

elementHandle.click(options?: TOptions): Promise<void>

focus

elementHandle.focus(): Promise<void>

hover

elementHandle.hover(): Promise<void>

press

elementHandle.press(key: string): Promise<void>

Where key is of the possible keys or a single character.

screenshot

elementHandle.screenshot(options?: { path?: string }): Promise<Buffer>

type

elementHandle.type(text: string): Promise<void>

Development

See my Start task runner preset for details.

References

• Python Client: API, source
• Perl Client: API, source
• Node.js client (outdated): source
• Marionette Google Group