Taiko: The Node.js Browser Automation Tool for End-to-End Testing

Taiko: The Node.js Browser Automation Tool for End-to-End Testing

Taiko is a free, open-source Node.js library from ThoughtWorks for reliable browser automation. It is built on top of Chrome DevTools Protocol (CDP) and designed to eliminate the flakiness that plagues Selenium-based tests. Its defining features are smart selectors that find elements by visible text and proximity, and implicit waiting that retries actions until they succeed — without explicit waitFor calls scattered through your tests.

Key Takeaways

Smart selectors find elements the way humans do. Instead of CSS selectors or XPath, Taiko lets you click button("Submit") or fill in textBox("Email") — selectors based on what users see, not the DOM structure developers write.

Implicit waiting is built in. Taiko retries every action until it succeeds or times out. You rarely need to write explicit wait calls, which removes a major source of flakiness.

The REPL lets you record tests interactively. Run taiko --observe to open a browser with a REPL, type actions, and Taiko generates a script. It is the fastest way to bootstrap a test.

Gauge is the natural test runner pairing. Taiko was built alongside Gauge — ThoughtWorks' BDD test runner. Gauge specification files call Taiko steps, providing a clean separation between test intent and implementation.

Taiko supports all major browser actions. Navigation, form input, clicks, hovers, drag and drop, file uploads, screenshots, PDF generation, network interception, and multi-tab handling are all covered in the API.

What Is Taiko?

Taiko was created by ThoughtWorks and released in 2018 as a response to the fragility of Selenium-based test suites. The core thesis: tests are flaky primarily because selectors are brittle (tied to class names that change) and because timing is explicit (developers write waitFor(1000) and hope it is enough).

Taiko addresses both problems:

  1. Selectors based on visible text, labels, and proximity — not CSS or XPath
  2. Every interaction retries automatically until the element is actionable

Install Taiko:

npm install --save-dev taiko

Taiko ships with Chromium. No separate driver installation needed.

Your First Taiko Test

const { openBrowser, goto, click, type, closeBrowser, $, text } = require('taiko');

(async () => {
  try {
    await openBrowser();
    await goto('https://example.com/login');
    await click('Username');         // finds the label "Username" and its associated input
    await type('alice@example.com');
    await click('Password');
    await type('s3cret');
    await click('Sign in');          // finds the button with text "Sign in"
    await text('Dashboard').exists();
  } finally {
    await closeBrowser();
  }
})();

Notice there are no CSS selectors, no XPath, no explicit waitForSelector. Taiko infers which element you mean from the visible text.

Smart Selectors

Smart selectors are Taiko's most distinctive feature. They fall into two categories: interactive element selectors and proximity selectors.

Interactive Element Selectors

These match elements by their visible label, placeholder, or text content:

// Buttons
click(button('Submit'))
click(button('Cancel'))

// Links
click(link('Forgot password?'))

// Text inputs — matched by label, aria-label, placeholder, or adjacent text
click(textBox('Email'))
type('user@example.com')

click(textBox('Search...'))   // matches by placeholder
type('Taiko docs')

// Checkboxes and radio buttons
click(checkBox('Accept terms'))
click(radioButton('Monthly billing'))

// Dropdowns
click(dropDown('Country'))
select('Germany')

// File inputs
attach('/path/to/file.pdf', fileField('Upload document'))

Proximity Selectors

When the same text appears multiple times on the page, proximity selectors let you narrow by location relative to another element:

// Click the "Edit" button that is near the text "Alice Johnson"
click(button('Edit'), near('Alice Johnson'))

// Fill in the input that is to the right of the label "Amount"
click(textBox(toRightOf('Amount')))
type('500')

// Select the checkbox above the "Save" button
click(checkBox(above(button('Save'))))

// The element within a container identified by text
click(link('Details'), within($('.user-card', near('Bob Smith'))))

CSS and XPath Fallbacks

When smart selectors are not enough, Taiko supports CSS with $ and XPath with $x:

click($('.submit-button'))
click($x("//button[@data-testid='submit']"))

// Combine: proximity with CSS
click(button('Delete'), near($('.row', near('Charlie'))))

Implicit Waiting

Every Taiko action retries until the element becomes available and the action succeeds. The default timeout is configurable:

const { openBrowser } = require('taiko');

await openBrowser({ timeout: 10000 });  // global timeout in ms

Override per-action:

await click('Submit', { waitForNavigation: true });
await goto('https://example.com', { waitForNavigation: false });

For cases where you genuinely need to wait for something specific:

const { waitFor } = require('taiko');

// Wait for a text to appear
await waitFor(text('Order confirmed'));

// Wait for an element to disappear
await waitFor(async () => !(await $('loading-spinner').exists()));

// Wait for a fixed duration (use sparingly)
await waitFor(500);
const { goto, reload, goBack, goForward, currentURL, title } = require('taiko');

await goto('https://example.com');
await goto('https://example.com', { navigationTimeout: 5000 });

await reload();
await goBack();
await goForward();

const url = await currentURL();
const pageTitle = await title();
console.log(`On: ${pageTitle} (${url})`);

Form Interactions

const { click, type, clear, textBox, dropDown, select, checkBox, radioButton, fileField, attach } = require('taiko');

// Text input
await click(textBox('First name'));
await clear(textBox('First name'));   // clear existing value
await type('Alice');

// Alternatively, using focus()
await focus(textBox('Email'));
await type('alice@example.com');

// Select box
await click(dropDown('Currency'));
await select('EUR');

// Multi-select
await click(dropDown('Tags'));
await select(['Backend', 'API', 'Critical']);

// Checkbox
await click(checkBox('Subscribe to newsletter'));

// Radio
await click(radioButton('Credit card'));

// File upload
await attach('path/to/invoice.pdf', fileField('Upload invoice'));

// Submit with Enter
await press('Enter');

Screenshots and PDFs

const { screenshot, emulateDevice } = require('taiko');

// Take a screenshot
await screenshot({ path: 'screenshots/checkout.png' });

// Screenshot of a specific element
await screenshot({ path: 'error-message.png', encoding: 'base64' });

// Emulate a mobile device
await emulateDevice('iPhone 12');
await goto('https://example.com');
await screenshot({ path: 'mobile-view.png' });

Network Interception

Taiko can intercept and mock network requests:

const { intercept, goto, text } = require('taiko');

// Stub an API response
await intercept('https://api.example.com/users', {
  body: JSON.stringify([{ id: 1, name: 'Test User' }]),
  contentType: 'application/json',
  status: 200
});

await goto('https://example.com/users');
await text('Test User').exists();

// Block a request
await intercept('https://analytics.example.com/**', (req) => req.abort());

Multi-Tab Handling

const { openTab, closeTab, switchTo } = require('taiko');

// Open a new tab
await openTab('https://docs.example.com');

// Switch between tabs by URL
await switchTo(/example.com\/docs/);
await click(link('API Reference'));

// Close the current tab and return to original
await closeTab();

The REPL and Test Recording

Taiko's interactive REPL is one of its best productivity features. Start it with:

npx taiko

This opens a Chromium browser and a REPL. Type actions interactively:

taiko> openBrowser()
taiko> goto('https://example.com/login')
taiko> click('Username')
taiko> type('alice@example.com')
taiko> click('Password')
taiko> type('s3cret')
taiko> click('Sign in')
taiko> .code    // print the generated script
taiko> .save login-test.js
taiko> .exit

With --observe mode, Taiko shows a visible browser and slows down actions so you can follow along:

npx taiko --observe

Integration with Gauge

Gauge is ThoughtWorks' BDD test runner and the natural companion to Taiko. Gauge specs are Markdown files with human-readable steps; Taiko implements those steps.

Install Gauge:

npm install -g @getgauge/cli
gauge install js
gauge init js

A Gauge spec (specs/login.spec):

# Login Flow

## Successful login with valid credentials
* Navigate to the login page
* Enter username "alice@example.com" and password "s3cret"
* Click "Sign in"
* Verify "Dashboard" is displayed

## Login fails with wrong password
* Navigate to the login page
* Enter username "alice@example.com" and password "wrong"
* Click "Sign in"
* Verify "Invalid credentials" error is shown

The step implementations (tests/login.js):

const { goto, click, textBox, type, text } = require('taiko');
const assert = require('assert');

step('Navigate to the login page', async () => {
  await goto(process.env.BASE_URL + '/login');
});

step('Enter username <username> and password <password>', async (username, password) => {
  await click(textBox('Username'));
  await type(username);
  await click(textBox('Password'));
  await type(password);
});

step('Click <buttonText>', async (buttonText) => {
  await click(buttonText);
});

step('Verify <message> is displayed', async (message) => {
  assert.ok(await text(message).exists());
});

step('Verify <message> error is shown', async (message) => {
  assert.ok(await text(message).exists());
});

Run the specs:

gauge run specs/

Running Taiko in CI

// For headless CI, use:
await openBrowser({ headless: true, args: ['--no-sandbox', '--disable-dev-shm-usage'] });

Docker example (.github/workflows/e2e.yml):

- name: Run Taiko tests
  run: |
    npx taiko tests/login.js
  env:
    BASE_URL: https://staging.example.com

Where Taiko Fits in Your Stack

Taiko handles what it was designed for exceptionally well: scripting a browser to perform user actions and verify outcomes. It does not generate test cases, analyse your application for coverage gaps, or adapt tests when your UI changes.

HelpMeTest is a complementary tool that works at a higher level. It uses AI to understand your application's intent and generate, maintain, and run end-to-end tests without you writing every selector and action manually. For teams already invested in Taiko and Gauge, HelpMeTest can cover the exploratory and monitoring layers — continuously testing production and alerting on regressions — while Taiko scripts handle precisely-specified user journeys in CI.

Summary

Taiko's smart selectors and implicit waiting solve the two biggest causes of flaky browser tests. Its REPL makes test authoring fast and accessible, and its Gauge integration provides a clean BDD workflow for teams that want human-readable specifications. If you are building a Node.js automation suite and are frustrated by the fragility of Selenium or the verbosity of raw Puppeteer, Taiko is worth a close look.

Read more

Start now free