Driver

Driver

The main driver class used to create a driver and actually use this API It will spawn a webdriver process by default.

Constructor

new Driver(config, opt)

Constructor returning a Driver object, which will be used to interface with a Webdriver.

It's used as a base class for specific drivers (ChromeDriver, FirefoxDriver, EdgeDriver, SafariDriver).

Specific drivers know how to run a local webdriver command (if present) and are able to adjust calls and return values so that they follow the w3c webdriver Protocol

Parameters:
Name Type Description
config Config

The session config that will be sent to the webdriver
opt Object

Options to configure the API itself

Properties
Name Type Default Description
hostname string 127.0.0.1

The hostname to connect to.
port number

The port. If not specified, a free port will automatically be found
pollInterval number 300

How many milliseconds to wait between each poll when using waitFor() by default
spawn boolean true

If true, it will spawn a new webdriver process when a new session is created
env Object process.env

(If spawn === true) The environment to pass to the spawn webdriver
stdio string ignore

(If spawn === true) The default parameter to pass to stdio when spawning new preocess.
args Array

(If spawn === true) The arguments to pass to the webdriver command
Mixes In:
Source:
Example
// Create a driver using the Chrome browser
var driver1 = new Driver(new Config())
await driver.newSession()

// Create a driver, but does NOT spawn a new webcontroller process
var driver2 = new Driver(new Config(), {
  spawn: false,
  hostname: '127.0.0.1',
  port: 4444
})
await driver.newSession()

Extends

Members

(static) Using

A value used by Driver#findElement and Driver#findElements to decide what kind of filter will be applied

Source:

(static) Key

Constant returning special KEY characters (enter, etc.) Constant are from the global variable KEY

Source:
Example
var body = await driver.findElementTagName('body')
body.sendKeys(driver.Key.ENTER + 'n')

Methods

setExecutable(executable)

Set executable for the specific webdriver. Deriving classes like ChromeDriver, SafariDriver etc. will set the specific executable to run.

Parameters:
Name Type Description
executable string

The name of the executable to run
Source:

(async) run(opt)

Run the actual webdriver's executable, depending on the browser This method might be overridden by deriving classes like ChromeDriver or SafariDriver

Parameters:
Name Type Description
opt Object

Options to configure the webdriver executable

Properties
Name Type Description
port number

The port the webdriver executable will listen to
args Array

The arguments to pass to the webdriver executable
env Object

The environment to pass to the spawn webdriver
stdio string

The default parameter to pass to stdio when spawning new preocess.
Source:

setPollInterval(interval)

Set the default poll interval

Parameters:
Name Type Description
interval number

How many milliseconds between each polling attempt
Source:
Example
// Create a driver using the Chrome browser
var driver = new drivers.ChromeDriver(new Config())
driver.setPollInterval(200)

setPollTimeout(timeout)

Set the default waitFor timeout

Parameters:
Name Type Description
timeout number

How many milliseconds between failing the call
Source:
Example
var driver = new drivers.ChromeDriver(new Config())
driver.setPollTimeout(200)

(async) waitFor(timeout)

This method will wrap ANY method in Driver or Element with a polling mechanism, which will retry the call every pollInterval milliseconds (it defaults to 300, but it can be set when running the Driver's constructor) It's also possible to pass an extra parameter to the original method in Driver, which represents a checker function that will need to return truly for success

Parameters:
Name Type Default Description
timeout number 0

How long to poll for
Source:
Example
// Create a driver using the Chrome browser
var driver = new drivers.ChromeDriver(new Config())
await driver.navigateTo('http://www.google.com')

// The findElementCss has 5 seconds to work
var el = driver.waitFor(5000).findElementCss('[name=q]')

// The findElementsCss (note the plural: it returns an array)
// has 10 seconds to work, AND the result needs to be not-empty
// (see the tester function added)
await el.waitFor(10000).findElementsCss('.listItem', (r) => r.length))

(async) startWebDriver()

Start the right webdriver, depending on what browser is attached to it. Since webdrivers can take a little while to answer, this method also checks that the webdriver process is actively and properly dealing with connections This method is called by newSession

Source:
Example
var driver = new drivers.ChromeDriver(new Config())
await driver.startWebDriver()

(async) stopWebDriver(signal)

Stops the webdriver process, if running. It does so by sending it a SIGTERM message. You can specify the message to send the process

Parameters:
Name Type Default Description
signal string | number SIGTERM

The signal to send. To know which signals you can send,
Source:
Example
// Create a driver using the Chrome browser
var driver = new drivers.ChromeDriver(new Config())
// ...
// ...
await driver.stopWebDriver()

(async) sleep(ms)

Sleep for ms milliseconds NOTE: you shouldn't use this as a quick means to wait for AJAX calls to finish. If you need to poll-wait, use waitFor

Parameters:
Name Type Description
ms number

The number of milliseconds to wait for *
Source:
Example
await driver.sleep(1000)

(async) newSession() → {Promise.<object>}

Create a new session. If the driver was created with spawn set to true, it will run the webdriver for the associated browser before asking for the session

Source:
Example
var driver = new drivers.ChromeDriver(new Config())
var session = await driver.newSession()

(async) deleteSession() → {Promise.<Driver>}

Delete the current session. This will not kill the webdriver process (if one was spawned). You can create a new session with newSession

Source:
Example
await driver.deleteSession()

(async) status() → {Promise.<object>}

Get status

Source:
Example
var status = await driver.status()

(async) performActions(actions) → {Promise.<Driver>}

Perform actions as specified in the passed actions object To see how to create an actions object, check the Actions class

Parameters:
Name Type Description
actions Actions

An object
Source:
Example
var actions = new Actions()
actions.tick.keyboardDown('R').keyboardUp('R')
await driver.performActions(actions)

(async) releaseActions()

Release the current actions

Source:
Example
await driver.releaseActions(actions)

(async) getTimeouts() → {Promise.<Object>}

Get timeout settings in the page

Source:
Example
var timeouts = await driver.getTimeouts()

(async) setTimeouts(param)

Set timeouts

Parameters:
Name Type Description
param Object

The object with the timeouts

Properties
Name Type Description
implicit number

Implicit timeout
pageLoad number

Timeout for page loads
script number

Timeout for scripts
Source:
Example
var timeouts = await driver.setTimeouts({ implicit: 7000 })

Navigate to page

Source:
await driver.navigateTo('http://www.google.com')

(async) getCurrentUrl() → {Promise.<string>}

Bake a cake without coffee Also, get the current URL

Source:
Example
var currentUrl = await driver.getCurrentUrl()

(async) back() → {Promise.<Driver>}

Go back one step

Source:
Example
await driver.back()

(async) forward() → {Promise.<Driver>}

Go forward one step

Source:
Example
await driver.forward()

(async) refresh() → {Promise.<Driver>}

Refresh the page

Source:
Example
await driver.refresh()

(async) getTitle() → {Promise.<string>}

Get page's title

Source:
Example
var title = await driver.getTitle()

(async) getWindowHandle() → {Promise.<string>}

Get the current window's handle

Source:
Example
var title = await driver.getWindowHandle()

(async) closeWindow() → {Promise.<Driver>}

Close the current window

Source:
Example
await driver.closeWindow()

(async) getWindowHandles() → {Promise.<Array.<string>>}

Get window handles as an array

Source:
Example
var wins = await driver.getWindowHandles()

(async) switchToWindow(string) → {Promise.<Driver>}

Switch to window

Parameters:
Name Type Description
string handle

The window handle to switched to
Source:
Example
var wins = await driver.getWindowHandles()
if (wins[1]) await switchToWindow (wins[1])

(async) switchToFrame(frame) → {Promise.<Driver>}

Switch to frame

Parameters:
Name Type Description
frame string | number | Element

Element object, or element ID, of the frame
Source:
Example
var frame = await driver.findElementCss('iframe')
await driver.switchToFrame(frame)

(async) switchToParentFrame() → {Promise.<Driver>}

Switch to the parent frame

Source:
Example
var frame = await driver.findElementCss('iframe')
  await driver.switchToFrame(frame)
  await driver.switchToParentFrame()

(async) getWindowRect() → {Promise.<Object>}

Get window rect

Source:
Example
await driver.getWindowRect()

(async) setWindowRect(rect) → {Promise.<Object>}

Set window rect

Parameters:
Name Type Description
rect Promise.<Object>

An object with properties height, width, x, y

Properties
Name Type Description
height Object

The desired height
width Object

The desired width
x Object

The desired x position
y Object

The desired y position
Source:
Example
await driver.getWindowRect()

(async) maximizeWindow() → {Promise.<Driver>}

Maximize window

Source:
Example
await driver.maximizeWindow()

(async) minimizeWindow() → {Promise.<Driver>}

Minimize window

Source:
Example
await driver.minimizeWindow()

(async) fullScreenWindow() → {Promise.<Driver>}

Make window full screen

Source:
Example
await driver.fullScreenWindow()

(async) getPageSource() → {Promise.<string>}

Get page source

Source:
Example
await driver.getPageSource()

(async) executeScript(script, args)

Execute sync script

Parameters:
Name Type Description
script string

The string with the script to be executed
args array

The arguments to be passed to the script
Source:
Example
await driver.executeScript('return 'Hello ' + arguments[0];', ['tony'])

(async) executeAsyncScript(script, args)

Execute async script NOTE: An extra argument is passed to the script, in addition to the arguments in args: it's the callback the script will need to call once the script has executed. To return a value from the async script, pass that value to the callback

Parameters:
Name Type Description
script string

The string with the script to be executed
args Array

The arguments to be passed to the script
Source:
Example
var script = 'var name = arguments[0];var cb = arguments[1];cb(\'Hello \' + name);'
await driver.executeAsyncScript(script, ['tony'])

(async) getAllCookies() → {Array.<Object>}

Get all cookies

Source:
Example
var list = await driver.getAllCookies()

(async) getNamedCookie() → {Object}

Get cookies matching a specific name

Source:
Example
var cookie = await driver.getNamedCookies('NID')

(async) addCookie(cookie) → {Promise.<Driver>}

Get cookies matching a specific name

Parameters:
Name Type Description
cookie object

The cookie object
Source:
Example
await driver.addCookie({
    name: 'test',
    value: 'a test',
    path: '/',
    domain: 'google.com.au',
    expiry: 1732569047,
    secure: true,
    httpOnly: true})

(async) deleteCookie() → {Promise.<Driver>}

Delete cookie matching a specific name

Source:
Example
var cookie = await driver.deleteCookie('test')

(async) deleteAllCookies() → {Promise.<Driver>}

Delete all cookies

Source:
Example
var list = await driver.deleteAllCookies()

(async) dismissAlert() → {Promise.<Driver>}

Dismiss an alert

Source:
Example
await driver.dismissAlert()

(async) acceptAlert() → {Promise.<Driver>}

Accepts an alert

Source:
Example
await driver.acceptAlert()

(async) getAlertText() → {string}

Get an alert's text

Source:
Example
var text = await driver.getAlertText()

(async) sendAlertText(text) → {Promise.<Driver>}

Send text to an alert

Parameters:
Name Type Description
text string

The text that should be sent
Source:
Example
await driver.sendAlertText('This is my answer')

(async) takeScreenshot() → {buffer}

Take screenshot *

Source:
Example
await driver.sendAlertText()

(async) getActiveElement() → {Element}

Get active element

Source:
Example
var el await driver.getActiveElement()

(async) findElement(using, value) → {Element}

Find an element. Note that you are encouraged to use one of the helper functions: findElementCss(), findElementLinkText(), findElementPartialLinkText(), findElementTagName(), findElementXpath()

Parameters:
Name Type Description
using string

It can be Driver.Using.CSS, Driver.Using.LINK_TEXT, Driver.Using.PARTIAL_LINK_TEXT, Driver.Using.TAG_NAME, Driver.Using.XPATH
value string

The parameter to the using method
Source:
Example
var el = await driver.findElement({ Driver.Using.CSS, value: '[name=q]' )

(async) findElements(using, value) → {Element}

Find several elements Note that you are encouraged to use one of the helper functions: findElementsCss(), findElemenstLinkText(), findElementsPartialLinkText(), findElementsTagName(), findElementsXpath()

Parameters:
Name Type Description
using string

It can be Driver.Using.CSS, Driver.Using.LINK_TEXT, Driver.Using.PARTIAL_LINK_TEXT, Driver.Using.TAG_NAME, Driver.Using.XPATH
value string

The parameter to the using method
Source:
Example
var el = await driver.findElements({ Driver.Using.CSS, value: '.item' )

(async) findElementCss(value)

Find first element matching CSS

Parameters:
Name Type Description
value string

The CSS expression
Overrides:
Source:
Example
var list = driver.findElementCss('.list')
var listTitle = list.findElementCss('.title')

(async) findElementLinkText(value)

Find first element matching text

Parameters:
Name Type Description
value string

The text to match
Overrides:
Source:
Example
var a = driver.findElementLinkText('cick here')
// or...
var el = driver.findElementCss('#something') // or
var l = item.findElementLinkText('click here')

(async) findElementPartialLinkText(value)

Find first element matching link text

Parameters:
Name Type Description
value string

The link text to match
Overrides:
Source:
Example
var a = driver.findElementPartialLinkText('cick here')
// or...
var el = driver.findElementCss('#something') // or
var l = item.findElementPartialLinkText('click here')

(async) findElementTagName(value)

Find first element matching tag name

Parameters:
Name Type Description
value string

The tag name to match
Overrides:
Source:
Example
var item = driver.findElementTagName('item') // or
var subItem = item.findElementTagName('subitem')

(async) findElementXpath(value)

Find first element matching xpath

Parameters:
Name Type Description
value string

The xpath to match
Overrides:
Source:
Example
var item = driver.findElementXpath('/html/body/form[1]') // or
var subItem = item.findElementXpath('/div/div/subitem')

(async) findElementsCss(value)

Find all elements matching CSS

Parameters:
Name Type Description
value string

The CSS expression
Overrides:
Source:
Example
var allItems = driver.findElementsCss('.list')
var item = allItems[0]
var allTitles = item.findElementsCss('.title')

(async) findElementsLinkText(value)

Find all elements matching text

Parameters:
Name Type Description
value string

The text to match
Overrides:
Source:
Example
var links = driver.findElementsLinkText('cick here')
// or...
var el = driver.findElementCss('#something') // or
var links = item.findElementsLinkText('click here')

(async) findElementsPartialLinkText(value)

Find all elements matching link text

Parameters:
Name Type Description
value string

The link text to match
Overrides:
Source:
Example
var links = driver.findElementsPartialLinkText('cick here')
// or...
var el = driver.findElementCss('#something') // or
var links = item.findElementsPartialLinkText('click here')

(async) findElementsTagName(value)

Find all elements matching tag name

Parameters:
Name Type Description
value string

The tag name to match
Overrides:
Source:
Example
var items = driver.findElementsTagName('item') // or
var el = items[0]
var subItem = el.findElementsTagName('subitem')

(async) findElementsXpath(value)

Find all elements matching xpath

Parameters:
Name Type Description
value string

The xpath to match
Overrides:
Source:
Example
var items = driver.findElementsXpath('/html/body') // or
var el = items[0]
var subItems = el.findElementXpath('/div/div/subitem')