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 () => {
      await goto("google.com");
      await write("Gauge test automation");
      await 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.

Integrating with Mocha

Install Mocha using npm 

npm install mocha -g

You can then use Taiko's REPL to record a flow and create tests.

Add tests like below

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

You can see how Mocha 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

await openBrowser({ headless: false })
await openBrowser()
await openBrowser({args:['--window-size=1440,900']})
await 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

closeBrowser

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

Examples

await closeBrowser()

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

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

intercept

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

Parameters

Examples

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

emulateNetwork

Set network emulation

Parameters

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

Examples

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

emulateDevice

Allows to simulate device viewport

Parameters

Examples

await emulateDevice('iPhone 6')

setViewPort

Sets page viewport

Parameters

Examples

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

openTab

Launches a new tab with given url.

Parameters

  • targetUrl string URL/Page title of the tab to switch.
  • options Object Click options. (optional, default {navigationTimeout:config.navigationTimeout,waitForEvents:['firstMeaningfulPaint']})
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

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

closeTab

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

Parameters

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

Examples

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

overridePermissions

Override browser permissions

Parameters

Examples

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

clearPermissionOverrides

clears all the permissions set

Examples

await 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

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

clearBrowserCookies

Clears browser cookies.

Examples

await clearBrowserCookies()

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

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

getCookies

Get browser cookies

Parameters

  • options (optional, default {})

Examples

await getCookies()
await 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

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

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 { navigationTimeout:5000, headers:{'Authorization':'Basic cG9zdG1hbjpwYXNzd29y2A=='}} Default navigationTimeout is 30 seconds to override set options = {navigationTimeout:10000}, headers to override defaults. (optional, default {navigationTimeout:config.navigationTimeout,waitForEvents:['firstMeaningfulPaint']})
    • 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'])
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

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

reload

Reloads the page.

Parameters

  • url string URL to reload
  • options Object (optional, default {navigationTimeout:config.navigationTimeout,waitForEvents:['firstMeaningfulPaint']})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

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

goBack

Mimics browser back button click functionality.

Parameters

  • options Object (optional, default {navigationTimeout:config.navigationTimeout,waitForEvents:['firstMeaningfulPaint']})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

await goBack()

goForward

Mimics browser forward button click functionality.

Parameters

  • options Object (optional, default {navigationTimeout:config.navigationTimeout,waitForEvents:['firstMeaningfulPaint']})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)

Examples

await goForward()

currentURL

Returns window's current URL.

Examples

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

Returns Promise<String> The URL of the current window.

title

Returns page's title.

Examples

await openBrowser();
await goto("www.google.com");
await title();
returns "Google"

Returns Promise<String> The title of the current page.

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 | object) A selector to search for element to click / coordinates of the elemets to click on. 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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation 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)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

await click('Get Started')
await click(link('Get Started'))
await click({x : 170, y : 567})

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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
  • args ...any

Examples

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

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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
  • args ...any

Examples

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

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

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

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

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

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,navigationTimeout:10000} (optional, default {})
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

await focus(textField('Username:'))

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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

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

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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

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

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

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

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 { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)
    • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

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

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

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

mouseAction

Performs the given mouse action on the given coordinates. This is useful in performing actions on canvas.

Parameters

  • action string Action to be performed on the canvas
  • coordinates object Coordinates of a point on canvas to perform the action.

Examples

await mouseAction('press', {x:0,y:0})
await mouseAction('move', {x:9,y:9})
await mouseAction('release', {x:9,y:9})

scrollTo

Scrolls the page to the given element.

Parameters

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

Examples

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

scrollRight

Scrolls the page/element to the right.

Parameters

Examples

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

scrollLeft

Scrolls the page/element to the left.

Parameters

Examples

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

scrollUp

Scrolls up the page/element.

Parameters

Examples

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

scrollDown

Scrolls down the page/element.

Parameters

Examples

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

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

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

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

$

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

await 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

await 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

    await 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

    await 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

    await 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

    textBox

    This selector lets you identify a text field(input with type text and textarea) 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

    await focus(textBox('Username:'))
textBox('Username:').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. DEPRECATED use textBox to select inputField with type text and textarea.

    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

    await 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

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

    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

    await 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

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

    Returns RelativeSearchElement

    toRightOf

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

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

    Returns RelativeSearchElement

    above

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

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

    Returns RelativeSearchElement

    below

    This relativeSelector lets you perform relative HTML element searches.

    Parameters

    Examples

    await 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

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

    Returns RelativeSearchElement

    alert

    Lets you perform an operation when an alert with given text is shown. Note : alert listener has to be added before it is triggered.

    Parameters

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

    Examples

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

    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())
prompt('Message', async () => await accept('Something'))

    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. NOTE : In callback, we can access only inline css not the one which are define in css files.
    • options Object Click options. (optional, default {})
      • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 15 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
      • options.waitForStart number wait for navigation to start. Default to 500ms (optional, default 500)
      • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
      • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 5000)
      • options.args number? Arguments to be passed to the provided callback.
      • options.waitForEvents string Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

    Examples

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

    Returns Promise<Object> Object with 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

    await 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

    await 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

    Parameters

    • text (optional, default '')

    Examples

    prompt('Message', async () => await accept('Something'))

    dismiss

    Dismiss callback for dialogs

    Examples

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

    loadPlugin

    This function is used by taiko to initiate the plugin

    Parameters

    • id
    • clientHandler Function callback method to set taiko instance for plugin
    • ID string unique id or name of the plugin

    Examples

    import {loadPlugin} from 'taiko';
import {ID, pluginHandler} from 'taiko-plugin';
loadPlugin(IDm pluginHandler);

    setConfig

    Lets you configure global configurations.

    Parameters

    • options object
      • options.observeTime number Option to modify delay time in milliseconds for observe mode. (optional, default 3000)
      • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after performing openTab, goto, reload, goBack, goForward, click, write, clear, press and evaluate. (optional, default 30000)
      • options.retryInterval number Option to modify delay time in milliseconds to retry the search of element existance. (optional, default 1000)
      • options.retryTimeout number Option to modify timeout in milliseconds while retrying the search of element existance. (optional, default 10000)
      • options.waitForNavigation boolean Wait for navigation after performing goto, click, doubleClick, rightClick, write, clear, press and evaluate. (optional, default true)

    Examples

    setConfig( { observeTime: 3000});

    repl

    Starts a REPL when taiko is invoked as a runner with --load option.

    Type: Function

    Examples

    import { repl } from 'taiko/recorder';
await repl();
    taiko --load script.js

    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

    Raspberry Pi with Raspbian

    The download executable is not an arm build and thus won't work with taiko by default. To make it work install the package `chromium-browser`. Then set the env variable `TAIKO_BROWSER_PATH=$(which chromium-browser)`

    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