Testing

Taiko + Gauge Integration: BDD Browser Tests in Plain English

23 Oct 2026 — 4 min read

Gauge is a test automation framework built by ThoughtWorks — the same company behind Taiko. They're designed to work together. Gauge provides the specification layer in Markdown, and Taiko handles browser automation. The combination gives you BDD-style tests that non-technical stakeholders can read, backed by reliable browser automation.

What Gauge Adds

Gauge specs are plain English Markdown files:

# Login Feature

## Successful login with valid credentials
* Open the browser and navigate to login page
* Enter email "alice@example.com" and password "password123"
* Click the sign in button
* Verify the user is redirected to the dashboard
* Verify welcome message shows "Welcome, Alice"

Each bullet (*) maps to a "step" — a JavaScript function that implements the action. Gauge matches the text to find the implementation.

Installation

# Install Gauge
npm install -g @getgauge/cli

# Initialize a Gauge + Taiko project
gauge init js

# Install dependencies
npm install

This creates:

specs/           # .spec files (plain English)
tests/           # step implementations
package.json

Project Structure

project/
  specs/
    login.spec
    checkout.spec
  tests/
    step_implementations/
      loginSteps.js
      checkoutSteps.js
    helpers/
      browserSetup.js
  env/
    default/
      default.properties
  package.json
  gauge.config

Writing Specifications

specs/login.spec:

# Login Feature

## Successful login
* Open the login page
* Enter credentials for "alice@example.com" with password "password123"
* Submit the login form
* Verify redirect to "/dashboard"
* Verify page shows "Welcome, Alice"

## Login with invalid credentials
* Open the login page
* Enter credentials for "alice@example.com" with password "wrongpassword"
* Submit the login form
* Verify error message "Invalid credentials"

## Login with empty email
* Open the login page
* Submit the login form without filling in email
* Verify validation error "Email is required"

Parameters in quotes ("alice@example.com") are automatically extracted and passed to the step implementation.

Implementing Steps

tests/step_implementations/loginSteps.js:

const { openBrowser, goto, write, click, text, button, inputField,
        toRightOf, waitFor, $, closeBrowser, currentURL } = require('taiko');
const assert = require('assert');
const { BeforeSuite, AfterSuite, Step } = require('gauge-taiko-steps');

// Suite setup
BeforeSuite(async () => {
    await openBrowser({
        headless: process.env.headless_chrome !== 'false',
        args: ['--no-sandbox', '--disable-dev-shm-usage']
    });
});

AfterSuite(async () => {
    await closeBrowser();
});

// Step implementations
Step('Open the login page', async () => {
    await goto(`${process.env.APP_URL || 'https://example.com'}/login`);
});

Step('Enter credentials for <email> with password <password>', async (email, password) => {
    await write(email, into(inputField(toRightOf('Email'))));
    await write(password, into(inputField(toRightOf('Password'))));
});

Step('Submit the login form', async () => {
    await click(button('Sign In'));
});

Step('Verify redirect to <path>', async (path) => {
    await waitFor(() => currentURL().includes(path));
    assert.ok((await currentURL()).includes(path), `Expected URL to contain "${path}"`);
});

Step('Verify page shows <message>', async (message) => {
    await waitFor(() => text(message).exists());
    assert.ok(await text(message).exists(), `Expected to see "${message}"`);
});

Step('Verify error message <message>', async (message) => {
    await waitFor(() => text(message).exists());
    assert.ok(await text(message).exists(), `Expected error "${message}"`);
});

Step('Submit the login form without filling in email', async () => {
    await click(button('Sign In'));
});

Step('Verify validation error <message>', async (message) => {
    await waitFor(() => text(message).exists());
    assert.ok(await text(message).exists());
});

Running Tests

# Run all specs
gauge run specs/

# Run a specific spec
gauge run specs/login.spec

# Run with a specific scenario
gauge run --scenario "Successful login" specs/login.spec

# Run with tags
gauge run --tags "smoke" specs/

# Run in parallel
gauge run --parallel -n 4 specs/

Tagging Specifications

Tags let you run subsets of tests:

# Login Feature

## Successful login
tags: smoke, login, critical
* Open the login page
* Enter credentials for "alice@example.com" with password "password123"
* Submit the login form
* Verify redirect to "/dashboard"

## Login with invalid credentials
tags: login, negative
* Open the login page
...

gauge run --tags "smoke" specs/    # only smoke tests
gauge run --tags "smoke,login" specs/  # smoke OR login tests
gauge run --tags "smoke & login" specs/  # smoke AND login tests

Data Tables in Specs

Gauge supports inline data tables for parameterized tests:

## Login with multiple user types
tags: login, data-driven

 | email                  | password    | expected_page |
 |------------------------|-------------|---------------|
 | admin@example.com      | adminpass   | /admin        |
 | user@example.com       | userpass    | /dashboard    |
 | viewer@example.com     | viewerpass  | /dashboard    |

* Open the login page
* Enter credentials for <email> with password <password>
* Submit the login form
* Verify redirect to <expected_page>

Gauge runs the scenario once per row, substituting table values as parameters.

Reports

Gauge generates HTML reports automatically:

gauge run specs/ --html-report

Reports include:

Pass/fail status per scenario
Step-by-step execution logs
Screenshots on failure (if configured)
Execution time per scenario

View the report at reports/html-report/index.html.

Environment Configuration

env/default/default.properties:

APP_URL = https://staging.example.com
headless_chrome = true
gauge_reports_dir = reports

Override for CI:

APP_URL=https://staging.example.com headless_chrome=true gauge run specs/

GitHub Actions Integration

name: Gauge + Taiko Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Gauge
        run: npm install -g @getgauge/cli

      - name: Install Chrome
        uses: browser-actions/setup-chrome@v1

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: gauge run specs/
        env:
          APP_URL: ${{ vars.STAGING_URL }}
          headless_chrome: 'true'
          TAIKO_BROWSER_ARGS: '--no-sandbox,--disable-dev-shm-usage'

      - name: Upload reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: gauge-reports
          path: reports/

When to Use Gauge + Taiko vs. Taiko Alone

Use Gauge + Taiko when:

Non-developers need to read or write test scenarios
You want living documentation that matches your test suite
Your team practices BDD and collaborates on specs before implementation
You want formatted reports that product owners can understand

Use Taiko alone when:

Your tests are purely technical — no business stakeholder reads them
You want minimal setup (no Gauge CLI, just Node.js)
You're using an existing test runner (Mocha, Jest) and don't want to switch

Summary

Gauge + Taiko gives you a readable specification layer (Markdown) over reliable browser automation (Taiko + CDP). The step abstraction lets non-technical team members read test scenarios while developers implement the underlying automation. For teams practicing BDD or wanting human-readable test documentation, the combination is a natural fit. For pure developer-owned test suites, Taiko with Mocha or Jest is simpler.