Quick Install

Taiko works on Windows, MacOS and Linux.

Note: You need to have Node.js installed in your system to start writing Taiko scripts in JavaScript.

Open a terminal application (or powershell in the case of windows) and install Taiko using npm 

npm install -g taiko

This installs Taiko and the latest version of the chromium browser. Now, we are all set to do some testing!

You can use Taiko with a test runner of your choice. We highly recommend using Taiko with Gauge.

Taiko Features

We built Taiko to make browser automation reliable. To fix the underlying problem behind ‘flaky tests’ and improve the browser automation experience, Taiko comes with an interactive recorder and a powerful API that provides

Getting Started with Taiko

Interactive Recorder

Taiko comes with a Recorder that’s a REPL to write test scripts. You can use Taiko’s API to control the browser from REPL.

To launch the REPL type taiko in your favorite terminal application. 

taiko

This launches the Taiko prompt.

Version: 0.2.0 (Chromium:69.0.3476.0)
Type .api for help and .exit to quit
>

You can now use Taiko’s API as commands in this prompt. For example, to launch a Chrome browser instance use 

openBrowser()

To automate this Chrome browser instance, you can use other commands from the Taiko API. Here's another example to get the browser to search google for something. 

goto("google.com")
write("taiko test automation")
click("Google Search")

These commands get the browser to

  • go to Google’s home page,
  • type the text "taiko test automation" and then
  • click on the "Google Search" button.

You can see the browser performing these actions as you type and press enter for each command.

Taiko’s REPL keeps a history of all successful commands. Once you finish a flow of execution, you can generate a test script using the special command .code 

.code

On execution, Taiko generates readable and maintainable JavaScript code.

const { openBrowser, goto, write, click } = require('taiko');
(async () => {
  try {
    await openBrowser();
    await goto("google.com");
    await write("taiko test automation");
    await click("Google Search");
  } catch (e) {
      console.error(e);
  } finally {
    closeBrowser();
  }
})();

You can copy and modify this code or save it directly to a file using 

.code googlesearch.js

Choose to continue automating or finish the recording using

.exit

To run a Taiko script pass the file as an argument to taiko 

taiko googlesearch.js

By default Taiko runs the script in headless mode - that means it does not launch a browser window. This makes it easy to run Taiko in containers like Docker. 

✔ Browser opened
✔ Navigated to url "http://google.com"
✔ Wrote taiko test automation into the focused element.
✔ Clicked element containing text "Google Search"
✔ Browser closed

To view the browser when the script executes use 

taiko googlesearch.js --observe

Taiko’s REPL also documents all the API’s. To view the documentation use this command. 

.api

To see more details of an API along with examples use .api with the name of the api. Here's an example 

.api openBrowser

This will generate details of the API along with examples.

Launches a browser with a tab. The browser will be closed when the parent node.js process is closed.
openBrowser() 
openBrowser({ headless: false }) 
openBrowser({args:['--window-size=1440,900']})

Smart Selectors

Taiko’s API treats the browser as a black box. With Taiko you can write scripts by looking at a web page and without inspecting it’s source code.

For example on google.com, this command will click on any element with the text 'Google Search' (a button on the page). 

click("Google Search")

Taiko’s API mimics user interactions with the browser. For example if you want to write into an element that’s currently in focus, use 

write("something")

Or if you want to write into a specific text field 

write("something", into(textField({placeholder: "Username"})))

With Taiko’s API you can avoid using ids/css/xpath selectors to create reliable tests that don’t break with changes in the web page’s structure.

You can also use Taiko’s proximity selectors to visually locate elements. For example, this command will click the checkbox that is nearest to any element with the text 'Username'.

click(checkbox(near("Username")))

Taiko’s also supports XPath and CSS selectors. 

click($("#button_id")) // Using CSS selectors
click($("//input[name=`button_name`]")) // Xpath selectors

Ability to handle XHR and dynamic content

Taiko’s API listens to actions that trigger XHR request or fetch dynamic content and automatically waits for them to complete before moving on to the next action. Taiko implicitly waits for elements to load on the page before performing executing the command. Scripts written in Taiko are free of explicit local or global waits to reduce ‘flakiness’.

Request/Response stubbing and mocking

Setting up test infrastructure and test data is hard. Taiko makes this easy with the intercept API. For example,

blocking requests on a page (like Google Analytics or any other resource) 

intercept("https://www.google-analytics.com/analytics.js");

or redirecting an XHR request on the page to a test instance 

intercept("https://fetchdata.com", "http://fetchtestdata.com")

stubbing an XHR request to return custom data 

intercept("https://fetchdata.com", {"test": data })

modify data sent by the XHR request 

 intercept("https://fetchdata.com", (request) =>  
  {request.continue({"custom": "data"})}))

This simplifies test setups as Taiko doesn’t have to set up mock servers, or replace URLs in tests to point to test instances.

Integrating with Gauge

We recommend using Taiko with Gauge. Gauge is a test runner for writing readable and reusable acceptance tests. It is easy to install and well integrated with Taiko.

Install Gauge using npm 

npm install @getgauge/cli

and initialize a sample Taiko project using

gauge init js

You can then use Taiko's REPL to record a flow and create step implementation stubs using the command .step

.step

It generates a step like below

step(" ", async () => {
      goto("google.com");
      write("Gauge test automation")
      press("Enter")
  });

you can also save it directly to a new or existing step implementation file

.step tests/google.js

Now that you've created your project with Gauge and Taiko, you can start to write test specifications using Gauge. You can see how Gauge and Taiko work together from this sample project.

Environment Variables

Taiko lets you specify certain Environment varibles to customise its behaviour

  • TAIKO_SKIP_CHROMIUM_DOWNLOAD - set to true to skip downloading chromium
  • TAIKO_CHROMIUM_URL - set to host url of mirror to download chromium
  • TAIKO_BROWSER_PATH - set to launch browser from different location
  • TAIKO_EMULATE_DEVICE - set to device model to emulate device view port

Taiko API

openBrowser

Launches a browser with a tab. The browser will be closed when the parent node.js process is closed.

Parameters

  • options Object {headless: true|false, args:['--window-size=1440,900']} (optional, default {headless:true})
    • options.headless boolean Option to open browser in headless/headful mode. (optional, default true)
    • options.args Array? Args to open chromium https://peter.sh/experiments/chromium-command-line-switches/.
    • options.port number Remote debugging port if not given connects to any open port. (optional, default 0)
    • options.ignoreCertificateErrors boolean Option to ignore certificate errors. (optional, default false)
    • options.observe boolean Option to run commands with delay to observe what's happening. (optional, default false)
    • options.observeTime number Option to modify delay time for observe mode. (optional, default 3000)
    • options.dumpio dumpio Option to dump IO from browser (optional, default true)

Examples

openBrowser()
openBrowser({ headless: false })
openBrowser({args:['--window-size=1440,900']})
openBrowser({args: [
     '--disable-gpu',
      '--disable-dev-shm-usage',
      '--disable-setuid-sandbox',
      '--no-first-run',
      '--no-sandbox',
      '--no-zygote']}) - These are recommended args that has to be passed when running in docker

Returns Promise<Object> Object with the description of the action performed.

closeBrowser

Closes the browser and all of its tabs (if any were opened).

Examples

closeBrowser()

Returns Promise<Object> Object with the description of the action performed.

client

Gives CRI client object.

Returns Object

switchTo

Allows to switch between tabs using URL or page title.

Parameters

  • targetUrl string URL/Page title of the tab to switch.

Examples

switchTo('https://taiko.gauge.org/') - switch using URL
switchTo('Taiko') - switch using Title

Returns Promise<Object> Object with the description of the action performed.

intercept

Add interceptor for the network call to override request or mock response.

Parameters

Examples

case 1: block url => intercept(url)
case 2: mockResponse => intercept(url,{mockObject})
case 3: override request => intercept(url,(request) => {request.continue({overrideObject})})
case 4: redirect => intercept(url,redirectUrl)
case 5: mockResponse based on request => intercept(url,(request) => { request.respond({mockResponseObject})} )

Returns object Object with the description of the action performed.

emulateNetwork

Set network emulation

Parameters

  • networkType String 'GPRS','Regular2G','Good2G','Good3G','Regular3G','Regular4G','DSL','WiFi, Offline'

Examples

emulateNetwork("Offline")
emulateNetwork("Good2G")

Returns Promise<Object> Object with the description of the action performed

emulateDevice

Allows to simulate device viewport

Parameters

Examples

emulateDevice('iPhone 6')

Returns Promise<Object> Object with the description of the action performed.

setViewPort

Sets page viewport

Parameters

Examples

setViewPort({width:600,height:800})

Returns Promise<Object> Object with the description of the action performed.

openTab

Launches a new tab with given url.

Parameters

  • targetUrl string URL/Page title of the tab to switch.
  • options (optional, default {timeout:30000})

Examples

openTab('https://taiko.gauge.org/')

Returns Promise<Object> Object with the description of the action performed.

closeTab

Closes the given tab with given url or closes current tab.

Parameters

  • targetUrl string URL/Page title of the tab to switch.

Examples

closeTab() - Closes the current tab.
closeTab('https://gauge.org') - Closes the tab with url 'https://gauge.org'.

Returns Promise<Object> Object with the description of the action performed.

overridePermissions

Override browser permissions

Parameters

Examples

overridePermissions('http://maps.google.com',['geolocation']);

clearPermissionOverrides

clears all the permissions set

Examples

clearPermissionOverrides()

setCookie

Sets a cookie with the given cookie data; may overwrite equivalent cookie if they exist.

Parameters

  • name string Cookie name.
  • value string Cookie value.
  • options (optional, default {})

Examples

setCookie("CSRFToken","csrfToken", {url: "http://the-internet.herokuapp.com"})
setCookie("CSRFToken","csrfToken", {domain: "herokuapp.com"})

Returns Promise<Object> Object with the description of the action performed.

clearBrowserCookies

Clears browser cookies.

Examples

clearBrowserCookies()

Returns Promise<Object> Object with the description of the action performed.

deleteCookies

Deletes browser cookies with matching name and url or domain/path pair.

Parameters

  • cookieName string Cookie name.
  • options Object (optional, default {})
    • options.url string deletes all the cookies with the given name where domain and path match provided URL. (optional, default 'http://www.google.com')
    • options.domain string deletes only cookies with the exact domain. (optional, default 'herokuapp.com')
    • options.path string deletes only cookies with the exact path. (optional, default 'Google/Chrome/Default/Cookies/..')

Examples

deleteCookies("CSRFToken", {url: "http://the-internet.herokuapp.com"})
deleteCookies("CSRFToken", {domain: "herokuapp.com"})

Returns Promise<Object> Object with the description of the action performed.

getCookies

Get browser cookies

Parameters

  • options (optional, default {})

Examples

getCookies() 
getCookies({urls:['https://the-internet.herokuapp.com']})

Returns Promise<Object> Array of cookie objects

setLocation

This function is used to mock geo location

Parameters

  • options
  • null-null object { latitude: 27.1752868, longitude: 78.040009, accuracy:20 }

Examples

overridePermissions("https://the-internet.herokuapp.com/geolocation",['geolocation'])
setLocation({ latitude: 27.1752868, longitude: 78.040009, accuracy:20 })

Returns Promise<Object> Object with the description of the action performed

goto

Opens the specified URL in the browser's tab. Adds http protocol to the URL if not present.

Parameters

  • url string URL to navigate page to.
  • options Object {timeout:5000, headers:{'Authorization':'Basic cG9zdG1hbjpwYXNzd29y2A=='}} Default timeout is 30 seconds to override set options = {timeout:10000}, headers to override defaults. (optional, default {timeout:default_timeout})
    • options.waitForNavigation boolean Skip to navigation - default is true (optional, default false)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

goto('https://google.com')
goto('google.com')

Returns Promise<Object> Object with the description of the action performed and the final URL.

reload

Reloads the page.

Parameters

  • url string URL to reload
  • options Object (optional, default {timeout:default_timeout})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

reload('https://google.com')
reload('https://google.com', { timeout: 30000 })

Returns Promise<Object> Object with the description of the action performed and the final URL.

goBack

Mimics browser back button click functionality.

Parameters

  • options Object (optional, default {timeout:default_timeout})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

goBack()

Returns Promise<Object> Object with the description of the action performed.

goForward

Mimics browser forward button click functionality.

Parameters

  • options Object (optional, default {timeout:default_timeout})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

goForward()

Returns Promise<Object> Object with the description of the action performed.

currentURL

Returns window's current URL.

Examples

openBrowser();
goto("www.google.com");
currentURL();
returns "https://www.google.com/?gws_rd=ssl"

Returns Promise<String>

title

Returns page's title.

Returns Promise<String>

click

Fetches an element with the given selector, scrolls it into view if needed, and then clicks in the center of the element. If there's no element matching selector, the method throws an error.

Parameters

  • selector (selector | string) A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
  • options Object Click options.
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number Timeout value in milliseconds for navigation after click. (optional, default 5000)
    • options.button string left, right, or middle. (optional, default 'left')
    • options.clickCount number Number of times to click on the element. (optional, default 1)
    • options.elementsToMatch number Number of elements to loop through to match the element with given selector. (optional, default 10)

Examples

click('Get Started')
click(link('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

doubleClick

Fetches an element with the given selector, scrolls it into view if needed, and then double clicks the element. If there's no element matching selector, the method throws an error.

Parameters

  • selector (selector | string) A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be double clicked.
  • options Object Click options. (optional, default {})
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
  • args ...any

Examples

doubleClick('Get Started')
doubleClick(button('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

rightClick

Fetches an element with the given selector, scrolls it into view if needed, and then right clicks the element. If there's no element matching selector, the method throws an error.

Parameters

  • selector (selector | string) A selector to search for element to right click. If there are multiple elements satisfying the selector, the first will be double clicked.
  • options Object Click options. (optional, default {})
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
  • args ...any

Examples

rightClick('Get Started')
rightClick(text('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

dragAndDrop

Fetches the source element with given selector and moves it to given destination selector or moves for given distance. If there's no element matching selector, the method throws an error. Drag and drop of HTML5 draggable does not work as expected. Issue tracked here https://github.com/getgauge/taiko/issues/279

Parameters

  • source (selector | string) Element to be Dragged
  • destination (selector | string) Element for dropping the dragged element
  • distance object Distance to be moved from position of source element

Examples

dragAndDrop($("work"),into($('work done')))
dragAndDrop($("work"),{up:10,down:10,left:10,right:10})

Returns Promise<Object> Object with the description of the action performed.

hover

Fetches an element with the given selector, scrolls it into view if needed, and then hovers over the center of the element. If there's no element matching selector, the method throws an error.

Parameters

  • selector (selector | string) A selector to search for element to right click. If there are multiple elements satisfying the selector, the first will be hovered.
  • options (optional, default {})

Examples

hover('Get Started')
hover(link('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

focus

Fetches an element with the given selector and focuses it. If there's no element matching selector, the method throws an error.

Parameters

  • selector (selector | string) A selector of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
  • options object {waitForNavigation:true,waitForStart:500,timeout:10000} (optional, default {})

Examples

focus(textField('Username:'))

Returns Promise<Object> Object with the description of the action performed.

write

Types the given text into the focused or given element.

Parameters

  • text string Text to type into the element.
  • into (selector | string)? A selector of an element to write into.
  • options Object? (optional, default {delay:10})
    • options.delay number Time to wait between key presses in milliseconds.
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number Timeout value in milliseconds for navigation after click (optional, default 5000)

Examples

write('admin', into('Username:'))
write('admin', 'Username:')
write('admin')

Returns Promise<Object> Object with the description of the action performed.

clear

Clears the value of given selector. If no selector is given clears the current active element.

Parameters

  • selector selector A selector to search for element to clear. If there are multiple elements satisfying the selector, the first will be cleared.
  • options Object Click options. (optional, default {})
    • options.waitForNavigation boolean Wait for navigation after clear. Default navigation timeout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number Timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

clear()
clear(inputField({placeholder:'Email'}))

Returns Promise<Object> Object with the description of the action performed.

attach

Attaches a file to a file input element.

Parameters

  • filepath string The path of the file to be attached.
  • to (selector | string) The file input element to which to attach the file.

Examples

attach('c:/abc.txt', to('Please select a file:'))
attach('c:/abc.txt', 'Please select a file:')

Returns Promise<Object> Object with the description of the action performed.

press

Presses the given keys.

Parameters

  • keys (string | Array<string>) Name of keys to press, such as ArrowLeft. See USKeyboardLayout for a list of all key names.
  • options Object (optional, default {})
    • options.text string? If specified, generates an input event with this text.
    • options.delay number Time to wait between keydown and keyup in milliseconds. (optional, default 0)
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number Timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

press('Enter')
press('a')
press(['Shift', 'ArrowLeft', 'ArrowLeft'])

Returns Promise<Object> Object with the description of the action performed.

highlight

Highlights the given element on the page by drawing a red rectangle around it. This is useful for debugging purposes.

Parameters

  • selector (selector | string) A selector of an element to highlight. If there are multiple elements satisfying the selector, the first will be highlighted.
  • args ...relativeSelector Proximity selectors

Examples

highlight('Get Started')
highlight(link('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

scrollTo

Scrolls the page to the given element.

Parameters

  • selector (selector | string) A selector of an element to scroll to.
  • options (optional, default {})

Examples

scrollTo('Get Started')
scrollTo(link('Get Started'))

Returns Promise<Object> Object with the description of the action performed.

scrollRight

Scrolls the page/element to the right.

Parameters

Examples

scrollRight()
scrollRight(1000)
scrollRight('Element containing text')
scrollRight('Element containing text', 1000)

Returns Promise<Object> Object with the description of the action performed.

scrollLeft

Scrolls the page/element to the left.

Parameters

Examples

scrollLeft()
scrollLeft(1000)
scrollLeft('Element containing text')
scrollLeft('Element containing text', 1000)

Returns Promise<Object> Object with the description of the action performed.

scrollUp

Scrolls up the page/element.

Parameters

Examples

scrollUp()
scrollUp(1000)
scrollUp('Element containing text')
scrollUp('Element containing text', 1000)

Returns Promise<Object> Object with the description of the action performed.

scrollDown

Scrolls down the page/element.

Parameters

Examples

scrollDown()
scrollDown(1000)
scrollDown('Element containing text')
scrollDown('Element containing text', 1000)

Returns Promise<Object> Object with the description of the action performed.

screenshot

Captures a screenshot of the page. Appends timeStamp to filename if no filepath given.

Parameters

  • selector
  • options object {path:'screenshot.png', fullPage:true, padding:16} or {encoding:'base64'} (optional, default {})

Examples

screenshot()
screenshot({path : 'screenshot.png'})
screenshot({fullPage:true})
screenshot(text('Images', toRightOf('gmail')))

Returns Promise<Buffer> Promise which resolves to buffer with captured screenshot if {encoding:'base64} given.

Returns Promise<object> Object with the description of the action performed

$

This selector lets you identify elements on the web page via XPath or CSS selector.

Parameters

Examples

highlight($(`//*[text()='text']`))
$(`//*[text()='text']`).exists()
$(`#id`)

Returns ElementWrapper

image

This selector lets you identify an image on a web page. Typically, this is done via the image's alt text or attribute and value pairs.

Parameters

  • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
  • args ...relativeSelector Proximity selectors
  • alt string The image's alt text.

Examples

click(image('alt'))
image('alt').exists()

Returns ElementWrapper

This selector lets you identify a link on a web page with text or attribute and value pairs.

Parameters

  • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
  • args ...relativeSelector Proximity selectors
  • text string The link text.

Examples

click(link('Get Started'))
link('Get Started').exists()

Returns ElementWrapper

listItem

This selector lets you identify a list item (HTML

  • element) on a web page with label or attribute and value pairs.

    Parameters

    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • args ...relativeSelector Proximity selectors
    • label string The label of the list item.

    Examples

    highlight(listItem('Get Started'))
listItem('Get Started').exists()

    Returns ElementWrapper

    button

    This selector lets you identify a button on a web page with label or attribute and value pairs.

    Parameters

    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • args ...relativeSelector Proximity selectors
    • label string The button label.

    Examples

    highlight(button('Get Started'))
button('Get Started').exists()

    Returns ElementWrapper

    inputField

    This selector lets you identify an input field on a web page with label or attribute and value pairs.

    Parameters

    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • args ...relativeSelector Proximity selectors

    Examples

    focus(inputField({'id':'name'})
inputField({'id': 'name'}).exists()

    Returns ElementWrapper

    fileField

    This selector lets you identify a file input field on a web page either with label or with attribute and value pairs.

    Parameters

    • label string The label (human-visible name) of the file input field.
    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • args ...relativeSelector Proximity selectors

    Examples

    fileField('Please select a file:').value()
fileField('Please select a file:').exists()
fileField({'id':'file'}).exists()

    Returns ElementWrapper

    textField

    This selector lets you identify a text field on a web page either with label or with attribute and value pairs.

    Parameters

    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • label string The label (human-visible name) of the text field.
    • args ...relativeSelector Proximity selectors

    Examples

    focus(textField('Username:'))
textField('Username:').exists()

    Returns ElementWrapper

    tap

    Parameters

    • selector
    • options (optional, default {})
    • args ...relativeSelector Proximity selectors
    • false options.waitForNavigation Default to true

    Examples

    tap('Gmail')
tap(link('Gmail'))

    Returns Promise<Object> Object with the description of the action performed.

    comboBox

    This selector lets you identify a combo box on a web page either with label or with attribute and value pairs. Any value can be selected using value or text of the options.

    Parameters

    • attrValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • args ...relativeSelector Proximity selectors
    • label string The label (human-visible name) of the combo box.

    Examples

    comboBox('Vehicle:').select('Car')
comboBox('Vehicle:').value()
comboBox('Vehicle:').exists()

    Returns ElementWrapper

    checkBox

    This selector lets you identify a checkbox on a web page either with label or with attribute and value pairs.

    Parameters

    • attrValuePairs
    • args ...relativeSelector Proximity selectors
    • attributeValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • label string The label (human-visible name) of the check box.

    Examples

    checkBox('Vehicle').check()
checkBox('Vehicle').uncheck()
checkBox('Vehicle').isChecked()
checkBox('Vehicle').exists()

    Returns ElementWrapper

    radioButton

    This selector lets you identify a radio button on a web page either with label or with attribute and value pairs.

    Parameters

    • attrValuePairs
    • args ...relativeSelector
    • attributeValuePairs object Pairs of attribute and value like {"id":"name","class":"class-name"}
    • label string The label (human-visible name) of the radio button.

    Examples

    radioButton('Vehicle').select()
radioButton('Vehicle').deselect()
radioButton('Vehicle').isSelected()
radioButton('Vehicle').exists()

    Returns ElementWrapper

    text

    This selector lets you identify an element with text. Looks for exact match if not found does contains.

    Parameters

    Examples

    highlight(text('Vehicle'))
text('Vehicle').exists()

    Returns ElementWrapper

    contains

    This selector lets you identify an element containing the text. DEPRECATED since text will do contains if exact match not found

    Parameters

    Examples

    contains('Vehicle').exists()

    Returns ElementWrapper

    toLeftOf

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

    click(link("Block", toLeftOf("name"))

    Returns RelativeSearchElement

    toRightOf

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

    click(link("Block", toRightOf("name"))

    Returns RelativeSearchElement

    above

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

    click(link("Block", above("name"))

    Returns RelativeSearchElement

    below

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

    click(link("Block", below("name"))

    Returns RelativeSearchElement

    near

    This relativeSelector lets you perform relative HTML element searches. An element is considered nearer to a reference element, only if the element offset is lesser than the 30px of the reference element in any direction. Default offset is 30 px to override set options = {offset:50}

    Parameters

    • selector (selector | string) Web element selector.
    • opts (optional, default {})

    Examples

    click(link("Block", near("name"))
click(link("Block", near("name", {offset: 50}))

    Returns RelativeSearchElement

    alert

    Lets you perform an operation when an alert with given text is shown.

    Parameters

    • message string Identify alert based on this message.
    • callback function Operation to perform. Accept/Dismiss

    Examples

    alert('Message', async () => await dismiss())

    prompt

    Lets you perform an operation when a prompt with given text is shown.

    Parameters

    • message string Identify prompt based on this message.
    • callback function Operation to perform.Accept/Dismiss

    Examples

    prompt('Message', async () => await dismiss())

    confirm

    Lets you perform an operation when a confirm with given text is shown.

    Parameters

    • message string Identify confirm based on this message.
    • callback function Operation to perform.Accept/Dismiss

    Examples

    confirm('Message', async () => await dismiss())

    beforeunload

    Lets you perform an operation when a beforeunload with given text is shown.

    Parameters

    • message string Identify beforeunload based on this message.
    • callback function Operation to perform.Accept/Dismiss

    Examples

    beforeunload('Message', async () => await dismiss())

    evaluate

    Evaluates script on element matching the given selector.

    Parameters

    • selector (selector | string) Web element selector.
    • callback function callback method to execute on the element.
    • options Object Click options. (optional, default {})
      • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 15 seconds, to override pass { timeout: 10000 } in options parameter. (optional, default true)
      • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
      • options.timeout number Timeout value in milliseconds for navigation after click. (optional, default 5000)

    Examples

    evaluate(link("something"), (element) => element.style.backgroundColor)
evaluate(()=>{return document.title})

    Returns Promise<Object> Object with description of action performed and return value of callback given

    intervalSecs

    Converts seconds to milliseconds.

    Parameters

    • secs number Seconds to convert.

    Examples

    link('Plugins').exists(intervalSecs(1))

    Returns number Milliseconds.

    timeoutSecs

    Converts seconds to milliseconds.

    Parameters

    • secs number Seconds to convert.

    Examples

    link('Plugins').exists(intervalSecs(1), timeoutSecs(10))

    Returns number Milliseconds.

    to

    This function is used to improve the readability. It simply returns the parameter passed into it.

    Parameters

    • e

    Examples

    attach('c:/abc.txt', to('Please select a file:'))

    Returns (string | selector)

    into

    This function is used to improve the readability. It simply returns the parameter passed into it.

    Parameters

    • e

    Examples

    write("user", into('Username:'))

    Returns (string | selector)

    waitFor

    This function is used to wait for number of secs given.

    Examples

    waitFor(intervalSecs(5))

    Returns promise

    accept

    Accept callback for dialogs

    dismiss

    Dismiss callback for dialogs

    selector

    Identifies an element on the page.

    Type: Function

    Parameters

    Examples

    link('Sign in')
button('Get Started')
$('#id')
text('Home')

    relativeSelector

    Lets you perform relative HTML element searches.

    Type: Function

    Parameters

    Examples

    near('Home')
toLeftOf('Sign in')
toRightOf('Get Started')
above('Sign in')
below('Home')
link('Sign In',near("Home"),toLeftOf("Sign Out")) - Multiple selectors can be used to perform relative search

    Returns RelativeSearchElement

    RelativeSearchElement

    Represents a relative HTML element search. This is returned by relativeSelector

    Type: Object

    Examples

    // returns RelativeSearchElement
above('username')

    ElementWrapper

    Wrapper object for the element present on the web page. Extra methods are avaliable based on the element type.

    • get(), exists(), description, text() for all the elements. (NOTE: exists() returns boolean form version 0.4.0)
    • value() for input field, fileField and text field.
    • value(), select() for combo box.
    • check(), uncheck(), isChecked() for checkbox.
    • select(), deselect(), isSelected() for radio button.

    Type: Object

    Properties

    • exists function (number, number) Checks existence for element.
    • description string Describing the operation performed.
    • text Array Gives innerText of all matching elements.

    Examples

    link('google').exists()
link('google').exists(intervalSecs(1), timeoutSecs(10))
link('google').description
textField('username').value()
$('.class').text()

    • Troubleshoot

    Running on Linux

    To check missing dependencies on linux machine run below command

    ldd chrome | grep

    Dependencies for Debian

        gconf-service 
    libasound2
    libatk1.0-0 
    libatk-bridge2.0-0
    libc6 
    libcairo2
    libcups2 
    libdbus-1-3
    libexpat1 
    libfontconfig1
    libgcc1 
    libgconf-2-4
    libgdk-pixbuf2.0-0 
    libglib2.0-0
    libgtk-3-0 
    libnspr4
    libpango-1.0-0 
    libpangocairo-1.0-0
    libstdc++6 
    libx11-6
    libx11-xcb1 
    libxcb1
    libxcomposite1 
    libxcursor1
    libxdamage1 
    libxext6
    libxfixes3 
    libxi6
    libxrandr2 
    libxrender1
    libxss1 
    libxtst6
    ca-certificates 
    fonts-liberation
    libappindicator1 
    libnss3
    lsb-release 
    xdg-utils
    wget

    Dependencies for Cent OS

        pango.x86_64 
    libXcomposite.x86_64
    libXcursor.x86_64 
    libXdamage.x86_64
    libXext.x86_64 
    libXi.x86_64
    libXtst.x86_64 
    cups-libs.x86_64
    libXScrnSaver.x86_64 
    libXrandr.x86_64
    GConf2.x86_64
    alsa-lib.x86_64
    atk.x86_64 
    gtk3.x86_64
    ipa-gothic-fonts 
    xorg-x11-fonts-100dpi
    xorg-x11-fonts-75dpi 
    xorg-x11-utils
    xorg-x11-fonts-cyrillic 
    xorg-x11-fonts-Type1
    xorg-x11-fonts-misc

    Configure sandbox

    There are two ways to setup sandbox in chromium:

    • Enable user namespace cloning:

      sudo sysctl -w kernel.unprivileged_userns_clone=1

    • Setup setuid sandbox:

      Follow steps given here to setup setuid sandbox

    To disable sandboxing launch chromium with below arguments:

    await openBrowser({args: ['--no-sandbox', '--disable-setuid-sandbox']});

    Disabling sandbox is not recommended unless you trust the content being loaded.

    Running on Docker

    Taiko docker image

    Docker image with all dependencies for taiko can be found here

    Other Troubleshootings Tips

    Intercepting request with method options

    To ensure CORS security browser sends requests with method OPTIONS for cross-orgin resource access and currently there is no way to intercept such requests

    As a workaround security can be disabled like below,

    await openBrowser({ args: ["--disable-web-security"] });

    Chromium command line args to enhance parallel run

    To improve load time when running tests in parallel on cloud, following chromium command line args are recommended

    await openBrowser({args: [
                    '--disable-gpu',
                     '--disable-dev-shm-usage',
                     '--disable-setuid-sandbox',
                     '--no-first-run',
                     '--no-sandbox',
                     '--no-zygote']});

    Enable debug logs to log events

    Run with below env to enable debug logs

    env DEBUG="taiko:*" taiko code.js