chrominator
v0.0.12
Published
High Level automation framework for chrome
Downloads
44
Readme
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
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
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
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})
Print the current page to pdf.
Parameters
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
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
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
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
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
Examples
nodes = await node.querySelectorAll({selector: 'a'})
nodes = await node.querySelectorAll('a')
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
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
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
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
Examples
nodes = await node.querySelectorAll({selector: 'a'})
nodes = await node.querySelectorAll('a')
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
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