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-devThis 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 configurationWriting 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 messageThe * 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 emptyThe 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 dashboardSave 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 ordersThis 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=trueRun against a specific environment:
gauge run specs/ --env stagingParallel 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 findsThe 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.