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

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(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.

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`

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

Plugins

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