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

Note: If you are installing as root user, and it fails with Permission Deniend error. Please refer to the troubleshooting guide

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 (error) {
      console.error(error);
  } 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(textBox({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.

Integrating with Jest

Install Jest using npm 

npm install jest -g

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

Add tests like below

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

You can see how jest and Taiko work together from this sample project.

Implicit wait mechanism

All actions waits for below mentioned events implicitly, `waitForStart` is the time taiko waits to collect all said events and then wait for it to be completed within `navigationTimeout`

  • Network requests
  • Frame Loads/Navigation
  • Frame Navigation
  • New tab/window open
  • New tab/window close

Additionally navigation actions like goto and reload waits for `loadEventFired` which ensures page load. And also waits for the element to be available before the action.

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_HIGHLIGHT_ON_ACTION - set to false to turn off highlighting the element on action
  • 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_EMULATE_NETWORK - set to the network type for Taiko to simulate. Available options are GPRS, Regular2G, Good2G, Regular3G, Good3G, Regular4G, DSL, WiFi, Offline
  • TAIKO_PLUGIN - set to the plugin which you want Taiko to load. Takes comma separated values.

Plugins

  • Taiko-accessibility
    A plugin to test the site accessibility with Taiko.
  • Taiko-android
    A plugin to run web tests on android devices and emulator using Taiko.
  • Taiko-diagnostics
    A plugin for taiko which provides some diagnostics features like measuring speedindex, performance metrics of webpage.
  • Taiko-screencast
    A plugin to record a gif video of a taiko script run.
  • Taiko-storage
    A taiko plugin to interact with browser storages.

Refer https://github.com/getgauge/taiko/wiki/Taiko-Plugin, for more details on how to write your own plugin for taiko.

Taiko API

openBrowser

Launches a browser with a tab. The browser will be closed when the parent node.js process is closed.
Note : openBrowser launches the browser in headless mode by default, but when openBrowser is called from repl it launches the browser in headful mode.

Parameters

  • options Object eg. {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<string> Args to open chromium. Refer https://peter.sh/experiments/chromium-command-line-switches/ for values. (optional, default [])
    • options.host string Remote host to connect to. (optional, default '127.0.0.1')
    • 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 each command after a delay. Useful to observe what is happening in the browser. (optional, default false)
    • options.observeTime number Option to modify delay time for observe mode. Accepts value in milliseconds. (optional, default 3000)
    • options.dumpio boolean Option to dump IO from browser. (optional, default false)

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

Returns Promise

closeBrowser

Closes the browser and along with all of its tabs.

Examples

await closeBrowser()

Returns Promise

client

Gives CRI client object (a wrapper around Chrome DevTools Protocol). Refer https://github.com/cyrus-and/chrome-remote-interface This is useful while writing plugins or if use some API of Chrome DevTools Protocol.

Returns Object

switchTo

Allows switching 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

Returns Promise

intercept

Add interceptor for the network call. Helps in overriding request or to mock response of a network call.

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}) })

Returns Promise

emulateNetwork

Activates emulation of network conditions.

Parameters

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

Examples

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

Returns Promise

emulateDevice

Overrides the values of device screen dimensions according to a predefined list of devices. To provide custom device dimensions, use setViewPort API.

Parameters

Examples

await emulateDevice('iPhone 6')

Returns Promise

setViewPort

Overrides the values of device screen dimensions

Parameters

Examples

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

Returns Promise

openTab

Launches a new tab. If url is provided, the new tab is opened with the url loaded.

Parameters

  • targetUrl string Url of page to open in newly created tab. (optional, default undefined)
  • options Object (optional, default {navigationTimeout:defaultConfig.navigationTimeout})
    • options.waitForNavigation boolean Wait for navigation after the reload. Default navigation timeout is 5000 milliseconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 5000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. Accepts value in milliseconds. (optional, default 5000)
    • options.waitForStart number time to wait to check for occurrence of page load events. Accepts value in milliseconds. (optional, default 100)
    • options.waitForEvents Array<string> Page load events to implicitly wait for. Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint']] (optional, default ['firstMeaningfulPaint'])

Examples

await openTab('https://taiko.gauge.org/')
await openTab() # opens a blank tab.

Returns Promise

closeTab

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

Parameters

  • targetUrl string URL/Page title of the tab to close. (optional, default undefined)

Examples

# Closes the current tab.
await closeTab()
# Closes all the tabs with Title 'Open Source Test Automation Framework | Gauge'.
await closeTab('Open Source Test Automation Framework | Gauge')
# Closes all the tabs with URL 'https://gauge.org'.
await closeTab('https://gauge.org')

Returns Promise

overridePermissions

Override specific permissions to the given origin

Parameters

Examples

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

Returns Promise

clearPermissionOverrides

Clears all permission overrides for all origins.

Examples

await clearPermissionOverrides()

Returns Promise

setCookie

Sets a cookie with the given cookie data. It may overwrite equivalent cookie if it already exists.

Parameters

  • name string Cookie name.
  • value string Cookie value.
  • options Object (optional, default {})
    • options.url string sets cookie with the URL. (optional, default undefined)
    • options.domain string sets cookie with the exact domain. (optional, default undefined)
    • options.path string sets cookie with the exact path. (optional, default undefined)
    • options.secure boolean True if cookie to be set is secure. (optional, default undefined)
    • options.httpOnly boolean True if cookie to be set is http-only. (optional, default undefined)
    • options.sameSite string Represents the cookie's 'SameSite' status: Refer https://tools.ietf.org/html/draft-west-first-party-cookies. (optional, default undefined)
    • options.expires number UTC time in seconds, counted from January 1, 1970. eg: 2019-02-16T16:55:45.529Z (optional, default undefined)

Examples

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

Returns Promise

clearBrowserCookies

Clears browser cookies.

Examples

await clearBrowserCookies()

Returns Promise

Meta

  • deprecated: use deleteCookies api to clear browser cookies.

deleteCookies

Deletes browser cookies with matching name and URL or domain/path pair. If cookie name is not given or empty, all browser cookies are deleted.

Parameters

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

Examples

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

Returns Promise

getCookies

Get browser cookies

Parameters

  • options Object (optional, default {})
    • options.urls Array The list of URLs for which applicable cookies will be fetched (optional, default undefined)

Examples

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

Returns Promise<Array<Object>> Array of cookie objects

setLocation

Overrides the Geolocation Position

Parameters

  • options Object Latitue, logitude and accuracy to set the location.
    • options.latitude number Mock latitude
    • options.longitude number Mock longitude
    • options.accuracy number Mock accuracy

Examples

await setLocation({ latitude: 27.1752868, longitude: 78.040009, accuracy:20 })

Returns Promise

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 (optional, default {navigationTimeout:defaultConfig.navigationTimeout})
    • options.waitForNavigation boolean Wait for navigation after the goto. Default navigationTimeout is 30 seconds to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForEvents Array<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 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.headers Object Map with extra HTTP headers.
    • options.waitForStart number time to wait for navigation to start. Accepts value in milliseconds. (optional, default 100)

Examples

await goto('https://google.com')
await goto('google.com')
await goto({ navigationTimeout:10000, headers:{'Authorization':'Basic cG9zdG1hbjpwYXNzd29y2A=='}})

Returns Promise

reload

Reloads the page.

Parameters

  • url string URL to reload
  • options Object (optional, default {navigationTimeout:defaultConfig.navigationTimeout})
    • options.waitForNavigation boolean Wait for navigation after the reload. Default navigation timeout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForEvents Array<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 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.waitForStart number time to wait for navigation to start. Accepts value in milliseconds. (optional, default 100)

Examples

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

Returns Promise

goBack

Mimics browser back button click functionality.

Parameters

  • options Object (optional, default {navigationTimeout:defaultConfig.navigationTimeout})
    • options.waitForNavigation boolean Wait for navigation after the goBack. Default navigation timeout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForEvents Array<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 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.waitForStart number time to wait for navigation to start. Accepts value in milliseconds. (optional, default 100)

Examples

await goBack()

Returns Promise

goForward

Mimics browser forward button click functionality.

Parameters

  • options Object (optional, default {navigationTimeout:defaultConfig.navigationTimeout})
    • options.waitForNavigation boolean Wait for navigation after the goForward. Default navigation timeout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForEvents Array<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 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.waitForStart number time to wait for navigation to start. Accepts value in milliseconds. (optional, default 100)

Examples

await goForward()

Returns Promise

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
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • 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 Array<string> Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default ['firstMeaningfulPaint'])
    • options.waitForStart number time to wait for navigation to start. Accepts time in milliseconds. (optional, default 100)
  • args Array<relativeSelector>

Examples

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

Returns Promise

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 (optional, default {})
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
  • args Array<relativeSelector>

Examples

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

Returns Promise

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 clicked.
  • options Object Click options. (optional, default {})
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
  • args ...any

Examples

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

Returns Promise

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})

Returns Promise

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

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 (optional, default {})
    • options.waitForEvents Array<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. (optional, default 10)
    • 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. Accepts time in milliseconds. (optional, default 100)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.hideText boolean Prevent given text from being written to log output. (optional, default false)
    • options.waitForEvents Array<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')

Returns Promise

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

Examples

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

Returns Promise

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. 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. (optional, default "")
    • 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 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.waitForStart number wait for navigation to start. (optional, default 100)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.waitForEvents Array<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'])

Returns Promise

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 Array<relativeSelector> Proximity selectors

Examples

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

Returns Promise

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.
  • options Object
    • options.waitForNavigation boolean Wait for navigation after the click. Default navigation timeout is 30 seconds, to override pass { navigationTimeout: 10000 } in options parameter. (optional, default true)
    • options.timeout number DEPRECATED timeout option, use navigationTimeout instead. (optional, default 30000)
    • options.navigationTimeout number Navigation timeout value in milliseconds for navigation after click. (optional, default 30000)
    • options.waitForEvents Array<string> Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default ['firstMeaningfulPaint'])
    • options.waitForStart number time to wait for navigation to start. Accepts time in milliseconds. (optional, default 100)

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

Examples

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

Returns Promise

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)

Returns Promise

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)

Returns Promise

scrollUp

Scrolls up the page/element.

Parameters

Examples

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

Returns Promise

scrollDown

Scrolls down the page/element.

Parameters

Examples

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

Returns Promise

screenshot

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

Parameters

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.

tap

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

Parameters

  • selector selector
  • options Object (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.waitForEvents Array<string> Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default ['firstMeaningfulPaint'])
  • args Array<relativeSelector> Proximity selectors

Examples

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

Returns Promise

$

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

Parameters

Examples

await highlight($(`//*[text()='text']`))
await $(`//*[text()='text']`).exists()
$(`#id`,near('username'),below('login'))

Returns ElementWrapper

image

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

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'))
await image('alt').exists()
await image({id:'imageId'}).exists()
await image({id:'imageId'},below('text')).exists()
await image(below('text')).exists()

Returns ElementWrapper

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

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'))
await link('Get Started').exists()
await link({id:'linkId'}).exists()
await link({id:'linkId'},below('text')).exists()
await link(below('text')).exists()

Returns ElementWrapper

listItem

This selector lets you identify a list item (HTML <li> element) on a web page with label or attribute and value pairs and proximity selectors.

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'))
await listItem('Get Started').exists()
await listItem({id:'listId'}).exists()
await listItem({id:'listItemId'},below('text')).exists()
await listItem(below('text')).exists()

Returns ElementWrapper

button

This selector lets you identify a button on a web page with label or attribute and value pairs and proximity selectors. Tags button and input with type submit, reset and button are identified using this selector

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'))
await button('Get Started').exists()
await button({id:'buttonId'}).exists()
await button({id:'buttonId'},below('text')).exists()
await button(below('text')).exists()

Returns ElementWrapper

inputField

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

Parameters

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

Examples

await focus(inputField({'id':'name'})
await inputField({'id': 'name'}).exists()
await inputField({id:'inputFieldId'},below('text')).exists()
await inputField(below('text')).exists()

Returns ElementWrapper

Meta

  • deprecated: use textBox for input with type text and password, textarea and contenteditable fields.

fileField

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

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

await attach('file.txt', to(fileField('Please select a file:')))
await fileField('Please select a file:').exists()
await fileField({'id':'file'}).exists()
await fileField({id:'fileFieldId'},below('text')).exists()
await fileField(below('text')).exists()

Returns ElementWrapper

textBox

This selector lets you identify a text field(input (with type text, password, url, search, number, email, tel), textarea and contenteditable fields) on a web page either with label or with attribute and value pairs and proximity selectors.

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:'))
await textBox('Username:').exists()
await textBox({id:'textBoxId'},below('text')).exists()
await textBox(below('text')).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 and proximity selectors.

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:'))
await textField('Username:').exists()
await textField({id:'textFieldId'},below('text')).exists()
await textField(below('text')).exists()

Returns ElementWrapper

Meta

  • deprecated: use textBox to select inputField with type text and textarea.

comboBox

This selector lets you identify a comboBox on a web page either with label or with attribute and value pairs and proximity selectors. 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

await comboBox('Vehicle:').select('Car')
await comboBox('Vehicle:').value()
await comboBox('Vehicle:').exists()
await comboBox({id:'comboBoxId'},below('text')).exists()
await comboBox(below('text')).exists()

Returns ElementWrapper

Meta

  • deprecated: Use dropDown API to identify a dropDown on a web page either with label or with attribute and value pairs.

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

Parameters

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

Examples

await dropDown('Vehicle:').select('Car')
await dropDown('Vehicle:').select({index:'0'}) - index starts from 0
await dropDown('Vehicle:').value()
await dropDown('Vehicle:').exists()
await dropDown({id:'dropDownId'},below('text')).exists()
await dropDown(below('text')).exists()

Returns ElementWrapper

checkBox

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

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 check box.

Examples

await checkBox('Vehicle').check()
await checkBox('Vehicle').uncheck()
await checkBox('Vehicle').isChecked()
await checkBox('Vehicle').exists()
await checkBox({id:'checkBoxId'},below('text')).exists()
await checkBox(below('text')).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 and proximity selectors.

Parameters

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

Examples

await radioButton('Vehicle').select()
await radioButton('Vehicle').deselect()
await radioButton('Vehicle').isSelected()
await radioButton('Vehicle').exists()
await radioButton({id:'radioButtonId'},below('text')).exists()
await radioButton(below('text')).exists()

Returns ElementWrapper

text

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

Parameters

Examples

await highlight(text('Vehicle'))
await text('Vehicle').exists()
await text('Vehicle', below('text')).exists()

Returns ElementWrapper

toLeftOf

Search relative HTML elements with this relativeSelector.

Parameters

Examples

await click(link("Block", toLeftOf("name"))
await write(textBox("first name", toLeftOf("last name"))

Returns RelativeSearchElement .

toRightOf

Search relative HTML elements with this relativeSelector.

Parameters

Examples

await click(link("Block", toRightOf("name"))
await write(textBox("last name", toRightOf("first name"))

Returns RelativeSearchElement .

above

Search relative HTML elements with this relativeSelector.

Parameters

Examples

await click(link("Block", above("name"))
await write(textBox("name", above("email"))

Returns RelativeSearchElement .

below

Search relative HTML elements with this relativeSelector.

Parameters

Examples

await click(link("Block", below("name"))
await write(textBox("email", below("name"))

Returns RelativeSearchElement .

near

Search relative HTML elements with this relativeSelector. 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 30px to override set options = {offset:50}

Parameters

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

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 Action to perform. Accept/Dismiss.

Examples

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

prompt

Lets you perform an operation when a prompt with given text is shown.
Note : prompt listener has to be added before it is triggered.
Write something in prompt with accept('Something').

Parameters

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

Examples

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

confirm

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

Parameters

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

Examples

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

beforeunload

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

Parameters

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

Examples

beforeunload('Message', async () => await accept())
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 or root HTML element when selector is not provided.
    NOTE : In callback, we can access only inline css not the one which are define in css files.
  • options Object 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. Accepts value in milliseconds (optional, default 100)
    • 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 Array Arguments to be passed to the provided callback.
    • options.waitForEvents Array<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((element) => {
     element.style.backgroundColor = 'red';
})

await evaluate(() => {
  // Callback function have access to all DOM APIs available in the developer console.
  return document.title;
} )

let options = { args: [ '.main-content', {backgroundColor:'red'}]}

await evaluate(link("something"), (element, args) => {
     element.style.backgroundColor = args[1].backgroundColor;
     element.querySelector(args[0]).innerText = 'Some thing';
}, options)

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.

Meta

  • deprecated: Use milliSeconds for time..

timeoutSecs

Converts seconds to milliseconds.

Parameters

  • secs number Seconds to convert.

Examples

link('Plugins').exists(timeoutSecs(10))

Returns number Milliseconds.

Meta

  • deprecated: Use milliSeconds for time..

to

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

Parameters

  • value

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

  • value

Examples

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

Returns (string | selector)

accept

Action to perform on dialogs

Parameters

  • text (optional, default '')

Examples

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

dismiss

Action to perform on dialogs

Examples

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

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});

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.

waitFor

This function is used to wait for number of milliseconds given or a given element or a given condition.

Parameters

  • element string Element/condition to wait for
  • time (number | time) Time to wait. default to 10s

Examples

waitFor(5000)
waitFor("1 item in cart")
waitFor("Order Created", 2000)
waitFor(async () => !(await $("loading-text").exists()))

Returns promise

repl

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

Examples

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

plugins

This function is used by taiko to initiate the plugin.

Parameters

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

selector

Identifies an element on the page.

Type: Function

Parameters

  • text string Text to identify the element.

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

Examples

above('username')
near('Get Started')

ElementWrapper

Wrapper object for the element present on the web page. Extra methods are available 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(1000)
link('google').description
textField('username').value()
$('.class').text()

Troubleshoot

Installing as root User

When installing taiko globally as a root user, npm explicitly changes the UID and GID, which can cause the installtion to fail with Permission Denied error.

The solution to fix this is to pass --unsafe-perm --allow-root to npm

Example: 
npm install -g taiko --unsafe-perm --allow-root

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 with Docker

To run Taiko in a docker container follow these instructions:

docker pull node

Start a container

docker run -it node /bin/bash

Update packages

apt-get update

Install chromium dependencies

apt-get install -y wget unzip fontconfig locales gconf-service libasound2 libatk1.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

Install Taiko

npm install taiko -g --allow-root --unsafe-perm=true

To launch taiko in headless mode start taiko REPL with taiko and open browser with below arguments:

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

To launch taiko in headful mode install Xvfb

apt-get install xvfb

Start taiko REPL with xvfb-run taiko and open browser with below arguments:

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

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

Wait for right events

Taiko by default waits for any network requests that are triggered as part of the action, frame load, frame navigation and new target navigation events. Navigation actions like goto, reload waits for loadEventFired in addition. There can be scenarios where the action might take time to trigger events, hence could be missed by taiko. Below are few where waiting for appropriate events will improve performance and reduce flakiness in tests.

  • firstMeaningfulPaint - Wait for this event if an action can trigger a page load which has heavy image or fonts to loaded.

  • targetNavigated - Wait for this event if there is a new tab/window open or close that happens because of an action.

  • loadEventFired - Wait for this event if an action triggers a page load which is not instanteneous.

Example:

await click(link('open new tab'),{waitForEvents:['targetNavigated']})