Use Gauge to describe acceptance-test scenarios in Markdown and organize their execution; use Selenium WebDriver in the step code to control a real browser. A working project also needs Gauge’s runtime and language runner, a Selenium binding, a browser, and its driver. The pattern below uses Java and shows how to structure, run, diagnose, and scale the tests.
What Gauge and Selenium each do
Gauge and Selenium are complementary, not competing, tools. Gauge connects a readable scenario to executable step implementations; Selenium performs browser actions from those implementations.
As an Amazon Associate I earn from qualifying purchases.
Flow: Markdown specification → Gauge step match → Java step implementation → Selenium WebDriver → browser.
Free tools Windows power users keep installed
One-click scans. No signup required.
Gauge is an open-source acceptance-test framework whose specifications use Markdown headings and business-readable steps. Its step implementations can use a browser driver such as Selenium. Selenium WebDriver is a language-neutral API and protocol for controlling browsers, with browser-specific driver implementations. Gauge overview · Selenium getting started
#1 Best Overall
Choose a language and install the project components
This example uses Java so the specification and implementation stay aligned. Gauge examples also cover Selenium implementations in C#, Python, and Ruby, but runner setup and syntax vary; follow the current instructions for the language runner you choose. Gauge examples
Install Gauge, its Java language runner, the Java Selenium binding, and a target browser. Selenium says its bindings use Selenium Manager by default for browser and driver management; consult the setup page for the chosen binding and environment for exact installation commands. Selenium documentation
Gauge’s command-line syntax below assumes Gauge and the appropriate runner are installed and available to the project. Browser availability, Java version, and runner setup are environment-specific; this guide does not claim a live-tested compatibility matrix.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteRank #2
Write a Gauge specification
Create a Markdown specification file such as specs/search.spec. Keep it focused on what a user does and observes, rather than embedding browser mechanics or selectors in the scenario.
# Search
## Search returns matching results
* Open the search page
* Search for "Gauge Selenium"
* The results page shows "Gauge Selenium"
The heading identifies the specification, the scenario heading names the behavior, and each bullet is a step Gauge must match to an implementation. Write steps so a product teammate can understand the expected behavior without knowing Selenium.
Implement the steps with Selenium WebDriver
Gauge Java step definitions use annotations to bind implementation methods to specification text. The following illustrates the shape of a Java implementation; adapt package, dependency, imports, and annotation API to the Java runner version installed in your project. Selectors and assertions must match the page under test. This example uses Selenium’s Java WebDriver API and a JUnit assertion.
import com.thoughtworks.gauge.Step;
import org.junit.jupiter.api.Assertions;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class SearchSteps {
private WebDriver driver;
@Step("Open the search page")
public void openSearchPage() {
driver = new ChromeDriver();
driver.get("https://example.com/search");
}
@Step("Search for ")
public void searchFor(String query) {
driver.findElement(By.name("q")).sendKeys(query);
driver.findElement(By.cssSelector("button[type='submit']")).click();
}
@Step("The results page shows ")
public void resultsPageShows(String text) {
String pageText = driver.findElement(By.tagName("body")).getText();
Assertions.assertTrue(pageText.contains(text),
"Expected results page to contain: " + text);
driver.quit();
driver = null;
}
}
Replace the example URL, field selector, and submit selector with stable locators from your application. The assertion checks observable page content rather than merely checking that a click did not throw. Ensure browser cleanup also runs if an earlier step fails—for example, use the lifecycle hooks supported by your Gauge runner to quit any active driver after each scenario. Otherwise, a failure can leave browser processes behind and contaminate later runs.
Gauge’s annotation and parameter-binding syntax is runner-specific. Keep the exact Java step API consistent with the installed runner rather than copying syntax from another language’s plugin. Selenium’s browser and driver setup likewise depends on the binding and environment. Gauge overview · Selenium getting started
Keep scenarios readable and data-driven
Reuse a step when it represents the same action across scenarios, but do not hide a scenario’s intent behind a chain of overly generic steps. Use a data table when several meaningful inputs exercise the same behavior; Gauge can execute the scenario once per row, and its documentation also describes external CSV data sources. Gauge overview · Gauge execution
# Search
## Search returns results for each query
| query |
| Gauge Selenium |
| browser tests |
* Open the search page
* Search for <query>
* The results page shows <query>
Each row should represent a useful variation, not a way to inflate the number of cases. Keep data independent where possible: tests that change shared account state or depend on order become harder to run reliably in parallel.
Run tests and inspect reports
- Run the specifications: from the project root, execute
gauge run specs, replacingspecswith your actual specification directory if different. - See step-level console detail: execute
gauge run --verbose specsto inspect step-level output when a scenario fails. - Review the generated report: Gauge reports specification pass or fail by default and generates reports for execution. Check the output for your installed version and retain or publish the resulting report as part of your team’s workflow.
- Run in CI: install Gauge and the project’s language runner on the CI machine, invoke the Gauge CLI in a job or task, and preserve or display the generated report. Gauge’s examples describe this general CI pattern. Gauge execution · Gauge examples
Run Gauge scenarios in parallel carefully
Gauge supports parallel specification execution. Start with independent scenarios, isolated browser sessions, and test data that does not collide; then increase concurrency while watching stability and resource use. Machine capacity, browser startup, network conditions, and how evenly work is distributed affect the result, so parallel mode does not imply a fixed speedup.
Parallel worker streams
Run specifications with gauge run --parallel specs. Use -n to set the number of streams, for example gauge run --parallel -n 4 specs. Gauge documents lazy allocation as the default and also describes eager allocation with grouping. Consult the execution documentation for the configuration details and select the allocation mode that fits your suite. Gauge execution
Thread-based execution
Thread-based parallelism is a separate option from worker streams. Gauge documents it for Java and .NET runners; it requires thread-safe test code. Do not enable it just because a runner is written in a language that can use threads: verify that the Gauge runner supports the configuration and ensure driver instances and mutable test data are not shared unsafely across threads. Gauge execution
When browser infrastructure becomes the limit
Local parallel sessions consume local browser and machine resources. Selenium Grid is an option when execution needs to span machines and browsers; it adds infrastructure to configure and maintain rather than making test scenarios independent automatically. Selenium documentation
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting common failures
- Gauge says a step is unimplemented: check that the specification wording matches the Java step annotation, that the implementation class is discoverable by the configured runner, and that the correct runner is installed.
- The browser does not start: confirm the browser is installed and usable in the environment, and check the Selenium binding’s setup guidance for driver management. Selenium Manager is the default browser and driver management tool used by Selenium bindings, but environment-specific setup may still matter. Selenium documentation
- An element cannot be found: inspect whether the page has loaded the expected content, whether the selector matches the current page, and whether a wait for the relevant element is needed. Prefer a stable user-facing or application-supported locator over brittle positional selectors.
- The assertion fails despite a successful click: verify the asserted behavior is actually visible in the page, and distinguish a failed application outcome from a timing issue. Add an explicit wait for the expected result rather than relying on an arbitrary short sleep.
- Tests pass alone but fail in parallel: look for shared accounts, reused files, stateful test data, or shared WebDriver objects. Isolate each session and its data; reduce stream count until the interference is fixed.
- CI behaves differently from a local run: verify the CI job installs Gauge and the same language runner, provides a browser-capable environment, invokes the intended specification path, and retains the generated report for diagnosis. Browser and operating-system setup details vary.
Or skip the browser setup
For a screenshot rather than an interactive acceptance test, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. It does not replace Gauge scenarios or Selenium interactions; it is useful when the task is simply to capture a page. Its capture options include full-page shots, CSS-selector element capture, device and viewport settings, waits, custom CSS and JavaScript, and more. See the ScreenshotNeo API documentation.
Recommended Free Tools
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Yearly billing gives two months free, and every feature is on every plan.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Can Gauge run without Selenium?
Yes. Gauge organizes acceptance tests and supports step implementations using other tools; Selenium is one possible browser-control layer.
Does Gauge parallel execution guarantee faster tests?
No. The outcome depends on machine capacity, browser startup, network conditions, and scenario balance.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
