Taiko + Gauge Integration: Writing Human-Readable E2E Tests

Taiko + Gauge Integration: Writing Human-Readable E2E Tests

Taiko and Gauge are both ThoughtWorks projects designed to work together. Gauge provides human-readable specification files written in Markdown. Taiko provides the browser automation that executes those specifications. The combination lets QA analysts write test specifications in plain English while developers write the step implementations in JavaScript. This guide walks through a complete integration from project setup to parallel CI execution.

Browser automation tests often suffer from a communication gap: developers write tests in code that product managers and QA analysts can't read. When requirements change, it's unclear which tests are affected. When tests fail, business stakeholders can't understand what broke.

Taiko + Gauge solves this by separating the specification layer (what the test does) from the implementation layer (how the browser is automated). Product managers write or review the specifications. Developers implement the steps. Tests become living documentation.

Project Setup

Install Gauge and the Node.js plugin:

# Install Gauge CLI
npm install -g @getgauge/cli

# Initialize a new Gauge project with Node.js
gauge init js

# Install Taiko
npm install taiko --save-dev

This creates the project structure:

my-project/
├── specs/
│   └── example.spec      # Gauge specification files
├── tests/
│   └── step_implementation.js  # Taiko step definitions
├── package.json
└── env/
    └── default/
        └── default.properties  # Environment configuration

Writing Gauge Specifications

Gauge specifications are plain Markdown files with a .spec extension. Each specification represents a user workflow:

# User Authentication

## Successful Login
* User navigates to the login page
* User enters email "admin@example.com" and password "securepass"
* User clicks the Sign In button
* User should be redirected to the dashboard
* User should see their name in the navigation

## Login with Invalid Credentials
* User navigates to the login page
* User enters email "wrong@example.com" and password "wrongpass"
* User clicks the Sign In button
* User should see an error message "Invalid email or password"
* User should remain on the login page

## Password Reset Flow
* User navigates to the login page
* User clicks "Forgot Password"
* User enters email "user@example.com"
* User clicks "Send Reset Email"
* User should see a confirmation message

The * marks are steps. Steps in angle brackets (<email>) are parameters that can be passed from the specification to the step implementation.

Implementing Steps with Taiko

Step implementations live in JavaScript files inside the tests/ directory:

// tests/authentication.js
const { step, beforeSuite, afterSuite, beforeScenario } = require('gauge/object');
const { 
  openBrowser, 
  closeBrowser, 
  goto, 
  write, 
  click, 
  textBox, 
  into, 
  currentURL,
  text,
  $
} = require('taiko');

const APP_URL = process.env.APP_URL || 'http://localhost:3000';

// Suite lifecycle
beforeSuite(async () => {
  await openBrowser({ headless: process.env.HEADLESS !== 'false' });
});

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

beforeScenario(async () => {
  // Clear cookies between scenarios for test isolation
  await goto(APP_URL);
});

// Step implementations
step('User navigates to the login page', async () => {
  await goto(`${APP_URL}/login`);
});

step('User enters email <email> and password <password>', async (email, password) => {
  await write(email, into(textBox('Email')));
  await write(password, into(textBox('Password')));
});

step('User clicks the Sign In button', async () => {
  await click('Sign In');
});

step('User should be redirected to the dashboard', async () => {
  await waitFor(async () => (await currentURL()).includes('/dashboard'), 5000);
});

step('User should see their name in the navigation', async () => {
  const nav = await $('[data-testid="user-nav"]').text();
  assert.ok(nav.length > 0, 'Navigation should show user name');
});

step('User should see an error message <message>', async (message) => {
  const errorText = await text(message).exists();
  assert.ok(errorText, `Expected error message: ${message}`);
});

step('User should remain on the login page', async () => {
  const url = await currentURL();
  assert.ok(url.includes('/login'), 'Should still be on login page');
});

Data Tables in Specifications

Gauge supports inline data tables that let you run the same scenario with multiple data sets:

# Product Search

## Search returns correct results

| query          | expected_count | first_result        |
|----------------|----------------|---------------------|
| "laptop"       | 24             | "MacBook Pro 14"    |
| "keyboard"     | 12             | "Mechanical Keyboard Pro" |
| "nonexistent"  | 0              | ""                  |

* User searches for <query>
* Results page shows <expected_count> items
* First result should be <first_result>

The step implementation receives parameters from the table row:

step('User searches for <query>', async (query) => {
  await click('Search');
  await write(query, into(textBox('Search products')));
  await press('Enter');
  await waitFor(async () => await text('results').exists());
});

step('Results page shows <expected_count> items', async (count) => {
  const resultCount = parseInt(count);
  if (resultCount === 0) {
    const empty = await text('No results found').exists();
    assert.ok(empty, 'Should show no results message');
  } else {
    const items = await $$('.product-card');
    assert.strictEqual(items.length, resultCount);
  }
});

Contexts and Teardowns

Gauge supports scenario-level setup and teardown through Contexts — steps that run before every scenario in a specification:

# Shopping Cart

## Context
* User is logged in as "buyer@example.com"
* User is on the products page

## Add item to cart
* User clicks "Add to Cart" on the first product
* Cart badge should show "1"
* Cart total should be updated

## Remove item from cart
* User clicks "Add to Cart" on the first product
* User opens the cart
* User clicks "Remove" next to the first item
* Cart should be empty

The Context steps run automatically before every scenario. This is cleaner than beforeEach hooks in traditional test frameworks because the setup intent is visible in the specification itself.

Concept Files

Gauge concepts are reusable multi-step sequences. When a workflow appears in multiple specifications, extract it into a concept:

# Login as <user_type>

* User navigates to the login page
* User enters credentials for <user_type>
* User clicks the Sign In button
* User should be redirected to the dashboard

Save this as tests/concepts/login.cpt. Now any specification can reuse it:

# Order Management

## Admin can view all orders
* Login as "admin"
* User navigates to "/admin/orders"
* Order list should be visible with at least 1 order

## Buyer can only see their orders
* Login as "buyer"
* User navigates to "/orders"
* User should only see their own orders

This eliminates duplicated login steps across hundreds of specifications.

Environment Configuration

Gauge environments let you run the same specifications against different environments:

env/
├── default/
│   └── default.properties     # Local development
├── staging/
│   └── staging.properties     # Staging environment
└── production/
    └── production.properties  # Read-only smoke tests
# env/staging/staging.properties
APP_URL=https://staging.example.com
HEADLESS=true
SCREENSHOT_ON_FAIL=true

Run against a specific environment:

gauge run specs/ --env staging

Parallel Execution

Gauge supports parallel execution at the specification level. Add a parallel flag to your run command:

gauge run --parallel --n=4 specs/

This spins up 4 workers, each running a separate browser instance. Each worker processes a queue of specifications. A 100-test suite that takes 10 minutes serially typically runs in 3-4 minutes with 4 parallel workers.

For proper parallel execution, each specification must be independent. Use beforeScenario to reset state rather than relying on state from previous specifications:

beforeScenario(async () => {
  // Create a fresh browser context for each scenario
  await goto('about:blank');
  // Clear localStorage if needed
  await evaluate(() => localStorage.clear());
});

Screenshots on Failure

Configure automatic screenshots when tests fail:

// tests/hooks.js
const { afterScenario } = require('gauge/object');
const { screenshot } = require('taiko');
const path = require('path');

afterScenario(async (info) => {
  if (info.currentScenario.isFailed) {
    const screenshotDir = process.env.SCREENSHOT_DIR || 'screenshots';
    const filename = `${info.currentSpec.heading}-${info.currentScenario.heading}-${Date.now()}.png`;
    await screenshot({ path: path.join(screenshotDir, filename) });
  }
});

CI Configuration

GitHub Actions

name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Install Gauge
        run: |
          npm install -g @getgauge/cli
          gauge install js
          gauge install html-report
          
      - name: Install Chromium dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y chromium-browser
          
      - name: Run E2E tests
        env:
          APP_URL: http://localhost:3000
          HEADLESS: true
        run: gauge run --parallel --n=2 specs/
        
      - name: Upload reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: gauge-reports
          path: reports/

Debugging Failing Tests

When a Gauge + Taiko test fails, the stack trace points to the failing step. For deeper debugging, run with the Taiko REPL:

# Run a single specification in headed mode
HEADLESS=false gauge run specs/authentication.spec

# Run a specific scenario
gauge run specs/authentication.spec:"Successful Login"

# Use Taiko REPL to debug a selector
npx taiko
> openBrowser({ headless: false })
> goto('http://localhost:3000/login')
> textBox('Email')  # Inspect what this finds

The Taiko REPL is the fastest way to validate a failing selector without re-running the entire test suite.

Real-World Benefits

Teams that adopt Taiko + Gauge typically report:

Business/QA alignment: Product managers review specification files in pull requests. When a specification changes, it triggers a conversation about whether the implementation needs to change too.

Fewer brittle tests: Smart selectors based on visible text and proximity survive UI refactoring better than CSS selectors. A component redesign that moves elements around doesn't break tests as long as the labels stay the same.

Better test documentation: The specification files replace (or supplement) traditional test case documentation. Running gauge run specs/ is the authoritative answer to "what E2E scenarios do we test?"

The Taiko + Gauge combination isn't the right fit for every team — it requires buy-in from non-technical stakeholders to be worth the overhead. But for teams that want their E2E tests to double as living documentation, it's one of the most effective setups available.

Read more

Start now free