How to Automate Testing with Gauge and Selenium

Gauge and Selenium work together: Gauge organizes acceptance tests as readable Markdown specifications and runs their steps; Selenium WebDriver lets step implementations control a browser. A typical flow is Markdown scenario → Gauge step match → language-specific step code → Selenium WebDriver → browser.

Gauge is an open-source acceptance-test framework. Selenium WebDriver is the browser-control API and protocol. They are complementary components, not alternatives. Gauge’s overview describes browser drivers such as Selenium in step implementations; Selenium’s getting started guide explains the browser-specific driver model.

1. Choose a language and assemble the tools

This guide uses Java for its Gauge step implementations. The same division of responsibility works with other language runners, but setup and step syntax differ. Gauge examples include Selenium implementations in Java, C#, Python, and Ruby; check the current documentation for the runner that matches your team.

A project needs:

• The Gauge runtime and Java language runner.
• The Selenium Java binding.
• A browser, such as Chrome or Firefox.
• The browser driver. Selenium documents Selenium Manager as the default browser and driver management tool used by its bindings; consult the current Selenium setup documentation for platform-specific requirements.

Use the current Gauge installation and Java runner instructions for your operating system, then add Selenium to the project using the dependency mechanism of the project template. Exact installation commands and dependency versions can vary by operating system, runner, and project template. This guide does not claim a particular set of commands has been tested.

2. Write a readable Gauge specification

Gauge specifications use Markdown headings and steps. Keep browser mechanics, CSS selectors, and WebDriver calls out of the specification; describe the behavior a user or product owner can understand.

# Store search

## Search returns matching products
* I open the store
* I search for "notebook"
* I should see products matching "notebook"

The first-level heading names the specification; the second-level heading names a scenario. The step phrases are matched to implementations in the project’s language runner.

3. Implement the steps with Selenium WebDriver

Place Java step implementation code in the location expected by the Java runner in your Gauge project. The following shows the Selenium actions and Gauge step annotations; the project must include the Gauge Java runner and Selenium Java binding.

import com.thoughtworks.gauge.Step;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;

public class StoreSteps {
    private WebDriver driver;

    @Step("I open the store")
    public void openStore() {
        driver = new ChromeDriver();
        driver.get("https://example.com");
    }

    @Step("I search for ")
    public void searchFor(String term) {
        driver.findElement(By.name("q")).sendKeys(term);
        driver.findElement(By.cssSelector("button[type='submit']")).click();
    }

    @Step("I should see products matching ")
    public void shouldSeeProducts(String term) {
        WebElement results = driver.findElement(By.id("search-results"));
        if (!results.getText().toLowerCase().contains(term.toLowerCase())) {
            throw new AssertionError("Search results did not contain: " + term);
        }
        driver.quit();
        driver = null;
    }
}

Replace the example domain and locators with the application under test. A production suite should also close the browser after failed steps, typically through the runner’s teardown or lifecycle hooks, so one assertion failure does not leak a browser process. Follow the lifecycle API documented for your chosen Gauge runner.

WebDriver locators should target stable, user-facing attributes where practical. The assertion checks observable page content rather than implementation details. If an application loads results asynchronously, wait for the result element or expected content instead of relying on a fixed sleep; use Selenium’s wait API and the appropriate timeout for the application.

4. Reuse steps and vary data deliberately

Reuse a step when it expresses the same action and has a clear meaning across scenarios. Avoid turning the specification into a sequence of tiny mechanical actions that only makes sense to the person who wrote the locators.

Gauge supports data-driven execution. A table in a specification can supply values referenced by a step, and Gauge executes the scenario for each row. For example:

# Store search

## Search common terms
| term     |
| notebook |
| calendar |
* I open the store
* I search for <term>
* I should see products matching <term>

Use table rows for meaningful variations of the same behavior. Gauge also describes external CSV data sources; see its overview and execution documentation for the supported data-source workflow.

5. Run tests and inspect reports

From the project directory, run the specs directory (adjust the path if the project uses another location):

gauge run specs

Gauge reports specification pass or fail by default. For step-level console detail, run:

gauge run --verbose specs

Gauge generates reports for the run. In CI, install Gauge and the project’s language runner on the worker, invoke the Gauge CLI as a job or task, then retain or publish the generated report using the CI system’s normal artifact workflow. See the official execution guide and examples.

6. Run specifications in parallel carefully

Gauge supports parallel specification execution using worker processes. Start with independent scenarios, separate browser sessions, and isolated test data. Then increase the number of streams deliberately:

gauge run --parallel -n 4 specs

The execution guide documents -n for setting streams. Lazy allocation is the default; Gauge also documents eager allocation with grouping. Consult the current Gauge execution guide for the configuration details appropriate to the run mode.

Parallel tests can interfere when they share accounts, mutable records, or browser state. Give each worker independent data and a fresh WebDriver session. Thread-based parallelism has additional constraints: the code must be thread-safe, and the language runner must support it. Gauge’s documentation names Java and .NET runners for thread-based execution. Do not assume that enabling parallelism guarantees a fixed speedup; machine capacity, browser startup, network latency, and uneven scenario duration all affect elapsed time.

For execution across machines or a wider browser matrix, Selenium Grid is an option. It distributes browser execution; it does not replace Gauge’s specification and orchestration role. See the Selenium documentation.

7. Troubleshoot common failures

Symptom	Likely cause	What to check
Gauge does not recognize a step	The step text and implementation annotation do not match, or the language runner is not configured.	Compare the phrase in the spec with the runner’s step syntax and confirm the runner is installed for the project.
Browser fails to start	The browser is missing, incompatible, or the driver cannot be resolved.	Confirm the browser installation and consult Selenium’s current setup guide for Selenium Manager and platform requirements.
Element not found	The locator is wrong, the page has not loaded the element, or the element is inside a frame.	Inspect the rendered page, verify the locator, wait for the expected element, and switch to the relevant frame if needed.
Intermittent assertion failure	Results load asynchronously or test data is shared.	Wait for the expected state and isolate accounts and records between scenarios.
Suite fails only in parallel	Scenarios share mutable state, browser sessions, or test data.	Use independent sessions and data, then lower the stream count while identifying the shared resource.
Run output lacks useful detail	Only default summary output is being inspected.	Run with --verbose and review the generated Gauge report.

8. Reliability, performance, and cost

For reliable suites, make each scenario’s starting conditions explicit, clean up test data, and keep browser lifecycle handling resilient to failures. Prefer state-based waits over fixed delays. Browser tests are sensitive to network and application response time, so treat timeouts as an explicit part of the test design.

Parallel workers can reduce elapsed time when scenarios are independent and the machine has capacity, but each worker consumes browser and system resources. Measure your own suite; no fixed speedup follows from enabling parallel mode. Gauge and Selenium are software components. A team that needs remote execution across machines can evaluate Selenium Grid, but it adds infrastructure and configuration work.

Or skip the browser setup

If the task is to capture a page image rather than validate browser behavior, ScreenshotNeo provides a website screenshot API and MCP server. It does not replace Gauge acceptance tests or Selenium interaction assertions. One GET request returns a screenshot or PDF; the API options and setup are in the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners and consent notices, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Can Gauge run Selenium tests in a language other than Java?

Yes. Gauge examples describe Selenium implementations in Java, C#, Python, and Ruby. Install and use the runner and step syntax for your chosen language.

Does Gauge control the browser?

Gauge matches and orchestrates specification steps. The step implementation uses Selenium WebDriver to control the browser.

Should every scenario run in parallel?

Only when scenarios and their test data are independent and the selected runner and execution mode support the concurrency you configure.

Can a screenshot API verify a workflow?

A screenshot can document a rendered page, but it does not perform the interaction and behavioral assertions of a Gauge and Selenium acceptance test.