API.md

API Reference

Return types clarification

resolves: the function is asynchronous and returns a Promise which resolves to the value
returns: the function is synchronous and returns the value

Configuration

folder

The local folder with static html files you wish to test. This folder is used both by browserstack-local and the static webserver. If you dont use either of those, the files will be loaded through the file:// protocol.

quiet

boolean (default: false)

If tue then information logging eg by static server and xvfb wont show

xvfb

boolean (default: true)

Whether a Xvfb server should be started.

Is automatically set to false for headless browsers or when using a provider

window

object (default: undefined)

An object in the form { width, height } where width & height define the window size. Can be overridden by setWindow

extendPage

function (default: undefined)

This function is called after a page is opened and receives the webpage instance as argument.

It should return or resolve to an object which is used in the page proxy

staticServer

boolean / object

If an object the configuration for the included static webserver. If true then the default configuration will be used.

• host (string, default localhost)
  The hostname / ip to run the static server on. Optionally you can also set the HOST env variable.
• port (integer, default 3000)
  The port the static server should run on. Optionally you can also set the PORT env variable.
• folder (string, optional)
  The path used as the webroot for the webserver. If not provided the default folder browser config option is used

BrowserStackLocal

object

This configuration is only used with browserstack/local browsers

The object can list the following properties:

• start (boolean, default true)
  Whether to start the browserstack-local daemon on browser.start
• stop (boolean, default true)
  Whether to stop the browserstack-local daemon on browser.close
• user (string)
  Your browserstack user name
  

for security reasons it is recommended to use the env var BROWSERSTACK_USER instead

• key (string)
  Your browserstack key
  

for security reasons it is recommended to use the env var BROWSERSTACK_KEY instead

• folder (string, boolean optional)
  The path to the folder which should be accessible through the browserstack-local tunnel. Explicitly set this to false if you wish to test an internal server. If any other falsy value is provided the default folder browser config option is used.

Browser methods

constructor

arguments

• config (type: object)

start

arguments

• capabilities (type: string)
• ...arguments (type: any)

resolves this

rejects on error

Starts the browser and all extra commands

For Puppeteer capabilities are added as launch options and arguments to the args key of launch options
For Selenium arguments are ignored

isReady

returns boolean

Returns true when the browser was started succesfully

close

resolves void

Closes the browser and all commands that were started

getUrl

arguments

• path (type: string) returns url

Returns the full url for a path. Depending your browser config it returns the url to/for browserstack-local, static server or just local files.

page

arguments

• url (type: string)
• readyCondition? (type: string | Function)

resolves page proxy (see below)

rejects on error

Opens the url on a new webpage in the browser and waits for the readyCondition to become true.

Page Proxy

It resolves to a Proxy which returns properties in the following order:

• a userExtended property (see configuration options)
• a Webpage property (from tib)
• a Page property (from the BrowserDriver, Puppeteer only)
• a BrowserDriver property

If the requested property doesnt exist on any of the internal objects it returns undefined

Also see the webpage:property hook which is called every time you access a property through the Proxy

setLogLevel

getCapabilities

arguments

• capabilities? (type object)

returns object

Returns the current capabilities. If the capabilities argument is specified these capabilities are also returned but are not added to the current capabilities.

addCapabilities

arguments

• capabilities (type object)

returns this

Adds to or sets the current capabilities with the new capabilities

getCapability

arguments

• capability (type string)

returns string

Returns the value for the requested capability

addCapability

arguments

• key (type string)
• value (type string)

returns this

Adds or sets the value of the capability with name key

setWindow

arguments

• width (type number)
• height (type number)

Sets the window size.

Also used for the Xvfb comamand

getBrowser

returns string

Returns the browser name

setBrowser

arguments

• browserName (type string)

Dont call this unless you have to, if you use a browserstring the browser name should already be set correctly

Sets the browser name

setHeadless

returns this

If called the browser will be started headless (if supported). Disables the Xvfb command

getBrowserVersion

returns string

this capability is probably only usefull when using a provider or selenium server

Returns the browser version which was set

setBrowserVersion

arguments

• version (type string)

returns this

this capability is probably only usefull when using a provider or selenium server

Sets the browser version

setOs / setOS

arguments

• name (type string)
• version (type string)

returns this

this capability is probably only usefull when using a provider or selenium server

Sets the os name and os version

browser.setOs('windows', 7)

setOsVersion / setOSVersion

arguments

• version (type string)

returns this

this capability is probably only usefull when using a provider or selenium server

Sets the os version

browser.setOs('windows') // default
browser.setOsVersion(7)

setDevice

arguments

• name (type string)

returns this

this capability is probably only usefull when using a provider or selenium server

Sets the name of the device (eg for mobile testing)

getLocalFolderUrl

arguments

• path (type string)

This method is only available in BrowserStackLocal browsers

Returns the full url for the relative path so browserstack can access your code through the browserstack-local tunnel

Webpage methods

getHtml

resolves string

The full html of the loaded Webpage

getTitle

resolves string

Resolves the document title of the loaded Webpage

getElement

arguments

• selector (type: string)

resolves ASTElement

Retrieves the html from the matched element and parses the returned outerHTML with htmlCompiler to return the corresponding ASTElement

getElements

arguments

• selector (type: string)

resolves Array<ASTElement>

Retrieves the html from matched elements and parses the returned outerHTML with htmlCompiler to return an array of the corresponding ASTElements

getElementCount

arguments

• selector (type: string)

resolves number

Retrieves the number of elements found

getElementHtml

arguments

• selector (type: string)

resolves string

Retrieves the outerHTML for the matched element

getElementsHtml

arguments

• selector (type: string)

resolves Array<string>

Retrieves an array with the outerHTML of all matched elements

getAttribute

arguments

• selector (type: string)
• attribute (type: string)

resolves string

Retrieves the value of the attribute for the matched element

getAttributes

arguments

• selector (type: string)
• attribute (type: string)

resolves Array<string>

Retrieves an array of the attribute values for the matched elements

getText

arguments

• selector (type: string)
• trim (type: boolean)

resolves string

Retrieves the textContent for the matched element. If trim is true the textContent will be trimmed

getTexts

arguments

• selector (type: string)
• trim (type: boolean)

resolves Array<string>

Retrieves an array with the textContent of all matched elements. If trim is true the textContent's will be trimmed

clickElement

arguments

• selector (type: string)

resolves void

Calls click on the matched element

runScript

arguments

• pageFunction (type: Function)
• ...arguments (type: any)

returns any

Executes the synchronous pageFunction in the loaded webpage context. The pageFunction is parsed to a string using @babel/parser, then transpiled with @babel/core/transform for the specified browser version^*. The function is reconstructed on the webpage using new Function. If you need to pass arguments from your test scope to the pageFunction, pass them as additional arguments to runScript. Make sure to only pass serializable variables (e.g. a Function is not).

It returns whatever pageFunction returns

^*Please note that the syntax is transpiled but polyfills are not added automatically. Polyfills need to be already loaded on the webpage. In other words, dont use features in your test pageFunctions which you dont also use in production

runAsyncScript

arguments

• pageFunction (type: Function)
• ...arguments (type: any)

returns any

Does the same as runScript but pageFunction can be asynchronous

Hooks

dependencies:load

Called before any browser dependency is loaded

dependencies:loaded

Called immediately after all browser dependencies are loaded

start:before

Called before the browser is started

start:after

passed arguments

• driver (type: object, the browser driver instance)

When starting the browser failed this hook will not be called

Called immediately after the browser has started

close:before

Called before the browser is closed

close:after

Called immediately after the browser was closed

page:before

Called before a new browser page is opened

page:created

passed arguments

• page (type: object, the page instance)

Called immediately after a new browser page is instantiated, but before navigation occures^* and before the wait condition is triggered.

^*On puppeteer, on selenium instantiating and navigating arent separate actions

page:after

passed arguments

• page (type: object, the page instance)

Called immediately after a new browser page was opened

webpage.property

passed arguments

• property (type: string)

Called whenever a property from the page proxy is requested.

selenium:build:before Selenium browsers only

passed arguments

• builder (type: object, the Selenium builder instance)

Called just before the build is called on the Selenium builder to start the browser

selenium:build:options Selenium browsers only

passed arguments

• options (type: array)
• builder (type: object, the Selenium builder instance)

Called just before browser specific options are applied