Workflow:Getgauge Taiko Headless Browser Testing
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Headless_Testing, CI_CD |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
End-to-end process for writing, configuring, and running Taiko browser automation scripts in headless mode for CI/CD pipelines and containerized environments.
Description
This workflow covers creating standalone Taiko test scripts that run without a visible browser window. The user writes a JavaScript file that imports Taiko APIs, opens a headless browser, performs navigation and assertions, and closes the browser. The script uses Taiko's smart selectors to find elements by visible text and implicit waits to handle dynamic content, eliminating explicit sleep calls. The workflow includes configuration for Docker containers and CI environments where additional Chrome flags are needed for sandboxing and shared memory.
Usage
Execute this workflow when you need automated browser tests that run in CI/CD pipelines, Docker containers, or any headless environment. This is the standard workflow for production test automation where tests must execute without user interaction and report results programmatically.
Execution Steps
Step 1: Install Taiko and Dependencies
Install Taiko as a project dependency via npm. The installation automatically downloads a compatible Chromium binary. For Docker environments, configure the Dockerfile with appropriate system dependencies (fonts, graphics libraries) and set environment variables for browser arguments like no-sandbox and disable-dev-shm-usage.
Key considerations:
- Taiko bundles a specific Chromium revision; the `TAIKO_BROWSER_PATH` environment variable overrides this to use a different browser
- Docker containers need `TAIKO_BROWSER_ARGS` set with `--no-sandbox --disable-dev-shm-usage`
- The `TAIKO_SKIP_CHROMIUM_DOWNLOAD` environment variable prevents Chromium download when using a pre-installed browser
Step 2: Write the Test Script
Create a JavaScript file that imports required Taiko APIs, wraps all browser interactions in an async IIFE with try/catch/finally, and ensures the browser is closed in the finally block. Use Taiko's smart selectors (text-based element finding) and proximity selectors (near, above, below) to create readable, maintainable test code that does not depend on fragile CSS or XPath selectors.
Key considerations:
- Import only the APIs you use via destructured require
- Always close the browser in a finally block to prevent orphaned processes
- Use text-based selectors for resilience against DOM structure changes
- Set appropriate navigation timeouts for slower CI environments using `setConfig`
Step 3: Add Assertions
Combine Taiko's implicit assertions (actions fail if elements are not found) with explicit assertions from any Node.js assertion library (assert, chai, etc.). Use the `.exists()` method on selectors to check element presence without performing actions. Configure wait times and retry intervals to balance speed and reliability.
Key considerations:
- Taiko actions throw errors if the target element is not visible, providing implicit assertions
- Use `text("...").exists()` or `button("...").exists()` for explicit presence checks
- The default wait timeout is 10 seconds with 100ms polling intervals
- Set `waitForNavigation` and `navigationTimeout` options for pages with slow loads
Step 4: Configure Runtime Options
Set Taiko configuration using `setConfig` for timeouts, retry intervals, and observation settings. For headless execution, configure navigation timeouts, retry counts, and whether to wait for specific page events. Environment variables provide an alternative configuration mechanism for CI systems.
Key considerations:
- `setConfig({ navigationTimeout: 30000 })` adjusts global navigation timeout
- `setConfig({ retryInterval: 500, retryTimeout: 30000 })` controls element search retry behavior
- Environment variable `TAIKO_BROWSER_ARGS` passes Chrome launch flags without code changes
- The `observe` option adds delays between actions for debugging
Step 5: Execute Tests
Run the test script using the Taiko CLI runner (`taiko script.js`) or directly with Node.js (`node script.js`). The Taiko runner provides formatted action logging. For CI pipelines, capture the exit code to determine pass/fail status. Screenshots can be captured on failure for debugging.
Key considerations:
- The Taiko CLI runner logs each action with a checkmark or error indicator
- Exit code 0 indicates success; non-zero indicates failure
- Use `screenshot({ path: 'failure.png' })` in catch blocks for failure diagnosis
- The `--observe` flag enables headful mode with delays for local debugging