README.md

Unmaintained: You can now use puppeteer the officially supported high level library by google.

a high level api to chrome debugger for automation.

currently working on core api built on promises. might provide a high level fluent api similar to nightmarejs in the future.

const Chrominator = require('chrominator');

Chrominator(async (driver) => {
    await driver.navigate('https://www.google.com')
    const search = await driver.querySelector('input[name="q"]')
    await search.sendKeys('yellow\n');
    await driver.delay(1000);
    await driver.screenshot('screenshot.png')
});

API

Driver

Abstraction to drive a webpage

setSize

Set the window size

Warning: depends on an unstable api

Parameters

• options object

Examples

await driver.setSize({width: 1366 , height: 768})

navigate

Navigate to a page and wait for the page to load.

available page load strategies:

• none
• loading
• interactive
• complete (default)

All the page load strategies but none correspond to the document.readyState. The none strategy does not wait for anything.

The default page load strategy can be overridden globally by setting driver.pageLoadStrategy.

The default timeout is 300,000 ms (5 minutes). It can be overridded globally by setting driver.timeouts.pageLoad.

Parameters

• args

Examples

await driver.navigate({url: 'http://google.com', pageLoadStrategy: 'interactive', timeout: 1000})
// or
await driver.navigate('http://google.com')

waitForPageLoad

Wait for an action to trigger a page load.

The action should return a Promise.

Parameters

• args

Examples

await driver.waitForPageLoad({action: () => { return driver.reload() }, pageLoadStrategy: 'interactive', timeout: 200})
or
await driver.waitForPageLoad(() => { return node.click() })

title

Get the title of the current page

Examples

title = await driver.title()

Returns string

handleJavaScriptDialog

Handle a javascript dialog

Parameters

• options object

Examples

await driver.handleJavaScriptDialog({accept: true})
// or accept and enter prompt text
await driver.handleJavaScriptDialog({accept: true, promptText: 'hello'})

triggerDialog

Trigger and wait for a dialog to open.

Warning: upstream alert handling is broken.

Parameters

• options

Examples

await driver.driver.triggerDialog(() => { return node.click() })
// or
await driver.driver.triggerDialog({action: () => { return node.click() }})

Returns Alert

waitForEvent

Simple utility to convert a one time event listener into a Promise.

Parameters

• eventName string name of the event in chrome remote debugger
• options (object | function)

Examples

const waiter = driver.waitForEvent('Page.javascriptDialogOpening')
await node.click()
const dialog = await waiter
// or
const dialog = await driver.waitForEvent('Page.javascriptDialogOpening', () => { node.click() })

querySelector

Search for a Node in the current document

Parameters

• args (Object | string) selector arguments or selector

Examples

node = await driver.querySelector({selector: '#my-id'})
node = await driver.querySelector('#my-id')

Returns Node

querySelectorAll

Search for Nodes in the current document

Parameters

• args (Object | string) selector arguments or selector

Examples

nodes = await driver.querySelectorAll({selector: 'a'})
nodes = await driver.querySelectorAll('a')

Returns Node

reload

Reload the current page

available page load strategies:

• none
• loading
• interactive
• complete (default)

All the page load strategies but none correspond to the document.readyState. The none strategy does not wait for anything.

The default page load strategy can be overridden globally by setting driver.pageLoadStrategy.

The default timeout is 300,000 ms (5 minutes). It can be overridded globally by setting driver.timeouts.pageLoad.

Parameters

• args

Examples

await driver.reload()
or
await driver.reload({pageLoadStrategy: 'interactive', timeout: 200})

pdf

Print the current page to pdf.

Parameters

• options (Object | string | undefined) pdf options

Examples

// writes image to file
driver.pdf({path: '/opt/save.pdf'})

// writes image to file
driver.pdf('/opt/save.pdf')

// returns base64 encoding
driver.pdf()

screenshot

Take a screenshot

Parameters

• options (Object | string | undefined) image options

Examples

// writes image to file
driver.screenshot({path: 'screenshot.png'});

// writes image to file
driver.screenshot('screenshot.png');

// returns base64 encoding.
driver.screenshot();

setUserAgent

Set the browsers user agent

Parameters

• args Object

Examples

driver.setUserAgent({userAgent: 'chrominator'})

getCookies

Get cookies

Parameters

• args Object

Examples

cookies = await driver.getCookies({urls: ['https://www.google.com/intl/en/ads']})

getCurrentCookies

Get cookies for the current page

Examples

cookies = await driver.getCookies()

getAllCookies

Get All cookies

deleteCookie

Delete a cookie.

The second parameter url is optional. The current url is used if nothing is provided.

Parameters

• name string The cookie name
• url (string | undefined) The url the cookie is on

Examples

// delete cookie on a specific url
await driver.deleteCookie('_ga', 'https://www.google.com/intl')
or
// delete cookie on the current url
await driver.deleteCookie('_ga')

deleteAllCookies

Delete All cookies

setCookie

Set a cookie

Parameters

• args

Examples

// set a cookie to a value on the current page
await driver.setCookie({name: 'foo', value: 'bar'})
or
await driver.setCookie({name: 'foo', value: 'bar', url: 'https://www.google.com/intl'})

setContent

Set the page content

Parameters

• html

Examples

driver.setContent('<div>hello</div>')

delay

Async delay.

Parameters

• ms number number of milliseconds

Examples

await driver.delay(500)

evaluate

Evaluate javascript

Parameters

• options Object

Examples

result = await node.evaluate({
    functionDeclaration: function(n) {
        return n + 1;
    },
    args: [n],
});

Returns Object resolved object

evaluateAsync

Evaluate Asynchronous javascript

The functionDeclaration must call either resolve to resolve the promise or reject to reject the promise.

Parameters

• options Object

Returns Object resolved object

currentUrl

Get the url of the current page

Examples

url = await driver.currentUrl()

Returns string the current url

until

Wait for a condition to be satisfied.

Parameters

• condition function The condition to wait for.

Examples

node = await driver.until(ExpectedConditions.isNodePresent({selector: 'button[value="Search"]'}))

until_not

Wait for a condition to not be satisfied.

Parameters

• condition function The condition to wait for.

Examples

node = await driver.until_not(ExpectedConditions.isNodePresent({selector: 'button[value="Search"]'}))

waitForNodePresent

Wait for a Node to be present

Parameters

• selector string css selector

Examples

node = await driver.waitForNodePresent('button[value="Search"]')

Returns Node

waitForNodeNotPresent

Wait for a Node to not be present

Parameters

• selector string css selector

Examples

node = await driver.waitForNodeNotPresent('button[value="Search"]')

waitForNodeClickable

Wait for a Node to be clickable

Parameters

• selector string css selector

Examples

node = await driver.waitForNodeClickable('button[value="Search"]')

Returns Node

waitForNodeNotClickable

Wait for a Node to not be clickable

Parameters

• selector string css selector

Examples

node = await driver.waitForNodeNotClickable('button[value="Search"]')

Returns Node

waitForTitle

Wait for title

Parameters

• title string page title

Examples

await driver.waitForTitle('Google')

createDriver

Create and initialize the driver.

Parameters

• crd Object an instance of chrome remote debugger

Examples

Driver.createDriver(crd)

Dialog

Parameters

• driver Driver
• data
• alert Object alert meta-data

dismiss

Dismiss a JavaScript Dialog

Examples

await alert.dismiss()

accept

Accept a JavaScript Dialog

Examples

await alert.accept()

handle

Handle a JavaScript Dialog

Parameters

• options

Examples

await alert.handle({accept: true})
// or
await alert.handle({accept: true, promptText: 'hello'})

Dialog

Abstract JavaScript Dialog

Warning: broken upstream

Parameters

• driver
• data

dismiss

Dismiss a JavaScript Dialog

Examples

await alert.dismiss()

accept

Accept a JavaScript Dialog

Examples

await alert.accept()

handle

Handle a JavaScript Dialog

Parameters

• options

Examples

await alert.handle({accept: true})
// or
await alert.handle({accept: true, promptText: 'hello'})

Node

Abstract DOM Element

Parameters

• driver
• nodeId

getAttributes

Get the Node's attributes.

Examples

attributes = await node.getAttributes()

Returns Object The attributes as key-value pairs.

getAttribute

Get an attribute on the node.

Parameters

• name string attribute name

Examples

value = await node.getAttribute('class')

Returns (string | null) attribute value or null if the attribute does not exist

querySelector

Search for a descendent of the current Node.

Parameters

• args (Object | string) selector arguments or selector

Examples

node = await node.querySelector({selector: '#my-id'})
node = await node.querySelector('#my-id')

Returns Node

querySelectorAll

Search for descendents of the current Node.

Parameters

• args (Object | string) selector arguments or selector

Examples

nodes = await node.querySelectorAll({selector: 'a'})
nodes = await node.querySelectorAll('a')

Returns Array<Node>

setFileInput

Set file selection on a file input element.

Parameters

• args Object

Examples

node.setFileInput({files: ['/opt/my-file.txt']})

focus

Focus on the Node

Examples

node.focus()

clickableAt

Test if the Node is clickable at a given location.

Parameters

• args Object

Returns boolean true if the element will directly receive a click event, otherwise false

resolveNodeAtDefaultClickPoint

Resolve Node at default click point

Parameters

• args Object

Returns Node Node to directly receive click

isClickable

Determine if the Node will receive a click

Parameters

• args Object

Returns boolean

getClickCoords

Calculate coordinates at the center of the Node for the click event.

Returns {x: Number, y: Number} coordinates for the click event.

click

Click on the Node.

Parameters

• args
• Object

Examples

node.click()

hover

Hover on the Node.

Parameters

• args
• Object

Examples

node.hover()

sendKeys

Type text to the Node

Parameters

• text string text to type into the node

Examples

node.sendKeys('jesg')

setProperty

Set a property on the Node

Parameters

• name string properties name
• value string properties value

Examples

node.setProperty('value', 'jesg')

getProperty

Get a property on the Node

Parameters

• name string properties name

Examples

value = await node.getProperty('value')

Returns string properties value

getProperties

Get the Node's properties

Examples

properties = await node.getProperties()

Returns Object properties as key-value pairs

evaluate

Evaluate javascript in the context of this Node.

Parameters

• options Object

Examples

propertyValue = await node.evaluate({
    functionDeclaration: function(name) {
        return this[name];
    },
    args: [name],
});

Returns Object resolved object

evaluateAsync

Evaluate Asynchronous javascript in the context of this Node.

The functionDeclaration must call either resolve to resolve the promise or reject to reject the promise.

Parameters

• options Object

Returns Object resolved object

equal

Test if the Node is equal to another Node.

Parameters

• node Node The Node to test against

Returns boolean

text

Get visible text.

The current implementation does not clean whitespace.

Parameters

• node

Returns string

Node

Parameters

• driver Driver
• nodeId string The nodes node id

getAttributes

Get the Node's attributes.

Examples

attributes = await node.getAttributes()

Returns Object The attributes as key-value pairs.

getAttribute

Get an attribute on the node.

Parameters

• name string attribute name

Examples

value = await node.getAttribute('class')

Returns (string | null) attribute value or null if the attribute does not exist

querySelector

Search for a descendent of the current Node.

Parameters

• args (Object | string) selector arguments or selector

Examples

node = await node.querySelector({selector: '#my-id'})
node = await node.querySelector('#my-id')

Returns Node

querySelectorAll

Search for descendents of the current Node.

Parameters

• args (Object | string) selector arguments or selector

Examples

nodes = await node.querySelectorAll({selector: 'a'})
nodes = await node.querySelectorAll('a')

Returns Array<Node>

setFileInput

Set file selection on a file input element.

Parameters

• args Object

Examples

node.setFileInput({files: ['/opt/my-file.txt']})

focus

Focus on the Node

Examples

node.focus()

clickableAt

Test if the Node is clickable at a given location.

Parameters

• args Object

Returns boolean true if the element will directly receive a click event, otherwise false

resolveNodeAtDefaultClickPoint

Resolve Node at default click point

Parameters

• args Object

Returns Node Node to directly receive click

isClickable

Determine if the Node will receive a click

Parameters

• args Object

Returns boolean

getClickCoords

Calculate coordinates at the center of the Node for the click event.

Returns {x: Number, y: Number} coordinates for the click event.

click

Click on the Node.

Parameters

• args
• Object

Examples

node.click()

hover

Hover on the Node.

Parameters

• args
• Object

Examples

node.hover()

sendKeys

Type text to the Node

Parameters

• text string text to type into the node

Examples

node.sendKeys('jesg')

setProperty

Set a property on the Node

Parameters

• name string properties name
• value string properties value

Examples

node.setProperty('value', 'jesg')

getProperty

Get a property on the Node

Parameters

• name string properties name

Examples

value = await node.getProperty('value')

Returns string properties value

getProperties

Get the Node's properties

Examples

properties = await node.getProperties()

Returns Object properties as key-value pairs

evaluate

Evaluate javascript in the context of this Node.

Parameters

• options Object

Examples

propertyValue = await node.evaluate({
    functionDeclaration: function(name) {
        return this[name];
    },
    args: [name],
});

Returns Object resolved object

evaluateAsync

Evaluate Asynchronous javascript in the context of this Node.

The functionDeclaration must call either resolve to resolve the promise or reject to reject the promise.

Parameters

• options Object

Returns Object resolved object

equal

Test if the Node is equal to another Node.

Parameters

• node Node The Node to test against

Returns boolean

text

Get visible text.

The current implementation does not clean whitespace.

Parameters

• node

Returns string

ExpectedConditions

Common expected conditions.

isNodePresent

Tests if a Node is present.

Parameters

• options

Examples

// returns Node
driver.until(ExpectedConditions.isNodePresent({selector: 'button[value="Search"]'}))

isNodeClickable

Tests if a Node is clickable.

Parameters

• options

Examples

// returns Node
driver.until(ExpectedConditions.isNodeClickable({selector: 'button[value="Search"]'}))

titleIs

Tests the page title

Parameters

• desiredTitle

Examples

// returns Node
driver.until(ExpectedConditions.titleIs('Google'))

nodeTextToEqual

Tests the nodes text

Parameters

• node
• desiredText

Examples

await driver.until(ExpectedConditions.nodeTextToEqual(node, 'Google'))

nodeValueToEqual

Tests the nodes value

Parameters

• node
• desiredValue

Examples

await driver.until(ExpectedConditions.nodeValueToEqual(node, 'Google'))

License

MIT