Forem: Mohammad Saddam Hossain

Zero-config Cucumber + Selenium in Java: no @Before, no driver setup, no cleanup

Mohammad Saddam Hossain — Sat, 02 May 2026 15:55:17 +0000

The Cucumber + Selenium boilerplate problem

Every Cucumber + Selenium project in Java starts the same way. Before you write a single step, you write the infrastructure:

public class Hooks {

    private WebDriver driver;

    @Before
    public void setUp() {
        WebDriverManager.chromedriver().setup();
        ChromeOptions options = new ChromeOptions();
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
        driver = new ChromeDriver(options);
        DriverHolder.set(driver);
    }

    @After
    public void tearDown(Scenario scenario) {
        if (scenario.isFailed()) {
            byte[] screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.BYTES);
            scenario.attach(screenshot, "image/png", "Failure screenshot");
        }
        if (driver != null) driver.quit();
        DriverHolder.remove();
    }
}

Then you wire a ThreadLocal for parallel safety. Then you figure out how to get it into step definitions. Then you add a static helper class. Then someone wants screenshots embedded in the Selenium Boot HTML report too, so you add that. Then CI needs headless mode...

By the time the first feature file runs, you've written 200 lines of plumbing that has nothing to do with your tests.

What the step definitions should look like

This is what a step definition file should be:

public class LoginSteps extends BaseCucumberSteps {

    @Given("the user is on the login page")
    public void onLoginPage() {
        open();
    }

    @When("they login as {string} with password {string}")
    public void login(String username, String password) {
        new LoginPage(getDriver()).login(username, password);
    }

    @Then("the dashboard should be visible")
    public void dashboardVisible() {
        assertThat(By.id("dashboard")).isVisible();
    }
}

Pure Gherkin logic. No driver setup. No cleanup. No thread-locals. No screenshot code. The infrastructure should live somewhere else — ideally somewhere you never have to touch.

How to get there

The right place for the infrastructure is a framework-level @Before/@After hook that runs automatically for every project. Cucumber discovers hooks by scanning the glue packages — so if you put your hooks in a published library and include that package in glue, they run without any code in the consumer project.

Here's the structure:

selenium-boot (library)
└── com.seleniumboot.cucumber
    ├── CucumberHooks.java       ← @Before + @After per scenario
    ├── BaseCucumberSteps.java   ← getDriver(), open(), assertThat()
    ├── BaseCucumberTest.java    ← runner base class
    └── CucumberStepLogger.java  ← pipes step names into HTML report

your-test-project
└── com.yourcompany.bdd
    ├── CucumberRunner.java      ← @CucumberOptions + extends BaseCucumberTest
    └── steps/
        └── LoginSteps.java      ← extends BaseCucumberSteps, pure steps only

The framework hook

CucumberHooks is the core of the integration. It runs before and after every scenario — the consumer project never sees it:

public class CucumberHooks {

    @Before(order = 1000)
    public void beforeScenario(Scenario scenario) {
        FrameworkBootstrap.initialize();        // idempotent — safe to call per-scenario
        String testId = buildTestId(scenario);

        CucumberContext.setScenario(scenario);
        SeleniumBootContext.setCurrentTestId(testId);
        ExecutionMetrics.markStart(testId);

        DriverManager.createDriver();           // reads selenium-boot.yml, applies config
        HookRegistry.onTestStart(testId);
    }

    @After(order = 20000)
    public void afterScenario(Scenario scenario) {
        String testId = SeleniumBootContext.getCurrentTestId();

        if (scenario.isFailed()) {
            // Screenshot into Selenium Boot HTML report
            String path = ScreenshotManager.capture(sanitize(scenario.getName()));
            ExecutionMetrics.recordScreenshot(testId, path);

            // Screenshot bytes attached to Cucumber's own HTML report
            String base64 = ScreenshotManager.captureAsBase64();
            if (base64 != null) {
                scenario.attach(Base64.getDecoder().decode(base64), "image/png", "Failure");
            }
            HookRegistry.onTestFailure(testId, new RuntimeException(scenario.getName()));
        }

        ExecutionMetrics.recordStatus(testId, resolveStatus(scenario));
        ExecutionMetrics.markEnd(testId);

        DriverManager.quitDriver();
        CucumberContext.clear();
        SeleniumBootContext.clearCurrentTestId();
    }
}

The @After(order = 20000) runs before any user-defined @After(order = 10000) — so the screenshot is captured while the page is still loaded, before user cleanup hooks navigate away.

The step definition base class

BaseCucumberSteps gives step definitions access to the driver and the framework API without static helpers or thread-local lookups:

public abstract class BaseCucumberSteps {

    protected WebDriver getDriver() {
        return DriverManager.getDriver();       // ThreadLocal — safe for parallel
    }

    protected void open() {
        getDriver().get(SeleniumBootContext.getConfig().getExecution().getBaseUrl());
    }

    protected void open(String path) {
        String base = SeleniumBootContext.getConfig().getExecution().getBaseUrl();
        getDriver().get(base + path);
    }

    protected Locator $(String css)     { return Locator.ofCss(css); }
    protected Locator $(By by)          { return Locator.of(by); }

    protected LocatorAssert assertThat(By locator) {
        return SeleniumAssert.assertThat(locator);   // auto-retrying assertion
    }

    protected Scenario getScenario() {
        return CucumberContext.getScenario();
    }
}

The runner

The runner is the one piece that belongs in the consumer project — it's how you specify where your features and step packages are:

@CucumberOptions(
    features = "src/test/resources/features",
    glue     = {"com.yourcompany.bdd.steps", "com.seleniumboot.cucumber"},
    plugin   = {"pretty", "com.seleniumboot.cucumber.CucumberStepLogger"}
)
public class CucumberRunner extends BaseCucumberTest {}

com.seleniumboot.cucumber in glue is the key — it makes Cucumber discover CucumberHooks automatically.

CucumberStepLogger is a ConcurrentEventListener that intercepts TestStepFinished events and pipes step names and their pass/fail status into the Selenium Boot HTML report step timeline:

public final class CucumberStepLogger implements ConcurrentEventListener {

    private static final ThreadLocal<String> CURRENT_STEP = new ThreadLocal<>();

    @Override
    public void setEventPublisher(EventPublisher publisher) {
        publisher.registerHandlerFor(TestStepStarted.class, this::onStepStarted);
        publisher.registerHandlerFor(TestStepFinished.class, this::onStepFinished);
    }

    private void onStepStarted(TestStepStarted event) {
        if (event.getTestStep() instanceof PickleStepTestStep step) {
            CURRENT_STEP.set(step.getStepText());
        }
    }

    private void onStepFinished(TestStepFinished event) {
        String name = CURRENT_STEP.get();
        CURRENT_STEP.remove();
        if (name == null) return;
        StepLogger.step(name, mapStatus(event.getResult().getStatus()),
                        event.getResult().getStatus() == Status.FAILED);
    }
}

IDE single-scenario execution

When you right-click a scenario in IntelliJ and click Run, the IDE uses its own Cucumber runner — not your CucumberRunner class — so @CucumberOptions is ignored and CucumberHooks is never discovered.

The fix: a cucumber.properties file. Cucumber reads it regardless of which runner launches the scenario:

# src/test/resources/cucumber.properties
cucumber.glue=com.yourcompany.bdd.steps,com.seleniumboot.cucumber
cucumber.plugin=pretty,com.seleniumboot.cucumber.CucumberStepLogger
cucumber.monochrome=true

One file. No IDE configuration needed.

Parallel execution

Parallel safety comes for free. The driver is stored in a ThreadLocal via DriverManager, CucumberContext stores the Scenario in a ThreadLocal, and ExecutionMetrics uses a ConcurrentHashMap keyed by testId. Each scenario thread is fully isolated.

Enable parallel execution in selenium-boot.yml:

execution:
  parallel: methods
  threadCount: 4
  maxActiveSessions: 4

What you get without writing it

By having com.seleniumboot.cucumber in your glue path, every scenario automatically gets:

Chrome or Firefox based on selenium-boot.yml — no WebDriverManager calls
Headless in CI — detected automatically
Screenshot on failure embedded in both the Selenium Boot HTML report and Cucumber's HTML report
Step names in the HTML report step timeline
Metrics tracked — duration, pass/fail, retry count
Parallel-safe ThreadLocal isolation
Self-healing locators if enabled
AI failure analysis if configured

The step definitions contain nothing but business logic.

Using it in Selenium Boot

All of this is built into Selenium Boot. Add the dependency and the two Cucumber JARs:

<dependency>
    <groupId>io.github.seleniumboot</groupId>
    <artifactId>selenium-boot</artifactId>
    <version>1.10.0</version>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>7.20.1</version>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-testng</artifactId>
    <version>7.20.1</version>
</dependency>

Full docs at seleniumboot.github.io/selenium-boot/docs/cucumber.

How does your team currently handle WebDriver setup in Cucumber step definitions? Drop it in the comments.

I built self-healing Selenium locators in Java — here's how it works

Mohammad Saddam Hossain — Mon, 27 Apr 2026 04:26:34 +0000

The problem every Selenium team hits

Your test suite was green last week. Today it's failing on 12 tests. The error is always the same:

org.openqa.selenium.TimeoutException: Expected condition failed:
waiting for visibility of element located by By.cssSelector: #submit-btn

You open the app. The button is right there. You inspect it — the id changed from submit-btn to btn-submit. A frontend developer renamed it during a refactor and didn't tell QA.

This is the #1 cause of flaky, high-maintenance Selenium suites. Locators are brittle by nature. The moment the DOM changes, your tests break — even when the feature itself works perfectly.

The standard advice is "use better locators" (data-testid, aria labels). Good advice. But you're inheriting 300 tests you didn't write, running against an app you don't own, and you need them green today.

What if the framework tried to fix itself?

The idea behind self-healing locators is simple: when a locator times out, don't immediately fail — try a set of fallback strategies derived from the original locator, and if one works, continue the test.

Here's the contract:

The primary locator fails (timeout)
The framework extracts fallback candidates from the locator descriptor
Each fallback is tried in order
If one succeeds, the test continues — and the heal is logged for the developer to review later
If none succeed, the original exception is thrown

The test doesn't silently lie. It passes, but it marks itself as healed so you know a locator needs updating.

Parsing `By.toString()` to extract fallbacks

The interesting engineering problem is: given a By object, what fallback strategies can you derive?

Selenium's By doesn't expose its internals via a clean API — but By.toString() is predictable. By.cssSelector: #submit-btn tells you everything you need.

Here's the core of the parser:

public static List<By> buildFallbacks(By original) {
    String desc = original.toString();
    List<By> fallbacks = new ArrayList<>();

    if (desc.startsWith("By.cssSelector: ")) {
        String css = desc.substring("By.cssSelector: ".length()).trim();

        // #submit-btn → By.id("submit-btn")
        Matcher id = Pattern.compile("#([\\w-]+)").matcher(css);
        if (id.find()) fallbacks.add(By.id(id.group(1)));

        // [name='username'] → By.name("username")
        Matcher name = Pattern.compile("\\[name=['\"]?([\\w-]+)['\"]?]").matcher(css);
        if (name.find()) fallbacks.add(By.name(name.group(1)));

        // .primary-btn → By.className("primary-btn")
        Matcher cls = Pattern.compile("\\.([\\w-]+)").matcher(css);
        if (cls.find()) fallbacks.add(By.className(cls.group(1)));

        // [data-testid='submit'] → By.cssSelector("[data-testid='submit']")
        Matcher testid = Pattern.compile("\\[data-testid=['\"]?([\\w-]+)['\"]?]").matcher(css);
        if (testid.find()) fallbacks.add(By.cssSelector("[data-testid='" + testid.group(1) + "']"));

        // [placeholder='Email'] → By.cssSelector("[placeholder='Email']")
        Matcher ph = Pattern.compile("\\[placeholder=['\"]([^'\"]+)['\"]]").matcher(css);
        if (ph.find()) fallbacks.add(By.cssSelector("[placeholder='" + ph.group(1) + "']"));
    }

    if (desc.startsWith("By.xpath: ")) {
        String xpath = desc.substring("By.xpath: ".length()).trim();

        // @id='submit-btn' → By.id("submit-btn")
        Matcher id = Pattern.compile("@id=['\"]([^'\"]+)['\"]").matcher(xpath);
        if (id.find()) fallbacks.add(By.id(id.group(1)));

        // @name='username' → By.name("username")
        Matcher name = Pattern.compile("@name=['\"]([^'\"]+)['\"]").matcher(xpath);
        if (name.find()) fallbacks.add(By.name(name.group(1)));

        // text()='Submit' → By.xpath("//*[text()='Submit']")
        Matcher text = Pattern.compile("text\\(\\)=['\"]([^'\"]+)['\"]").matcher(xpath);
        if (text.find()) fallbacks.add(By.xpath("//*[text()='" + text.group(1) + "']"));
    }

    return fallbacks;
}

Then the healing attempt:

public static WebElement tryHeal(WebDriver driver, By original) {
    List<By> fallbacks = buildFallbacks(original);
    for (By fallback : fallbacks) {
        try {
            WebElement el = driver.findElement(fallback);
            if (el.isDisplayed()) {
                logHeal(original, fallback); // record for report
                return el;
            }
        } catch (NoSuchElementException ignored) {}
    }
    return null; // all fallbacks failed
}

Where it hooks into the wait layer

Self-healing only makes sense at the wait layer, not raw findElement. You want it to fire after you've already waited the full timeout — otherwise you'd be bailing out of waits too early.

public static WebElement waitForVisible(By locator) {
    try {
        return new WebDriverWait(driver, Duration.ofSeconds(timeout))
            .until(ExpectedConditions.visibilityOfElementLocated(locator));
    } catch (TimeoutException | NoSuchElementException e) {
        // Primary locator failed — try healing
        WebElement healed = SelfHealingLocator.tryHeal(driver, locator);
        if (healed != null) return healed;
        throw e; // nothing worked, surface the real error
    }
}

The rest of your framework calls waitForVisible before every interaction — so every click, type, and assertion gets self-healing automatically.

Logging heals without noise

A healed locator is a warning, not a success. You want to know about it — but you don't want it to drown in test output. The right pattern is to accumulate healed locator records and export them after the suite runs:

// target/healed-locators.json
[
  {
    "test": "LoginTest#submitForm",
    "original": "By.cssSelector: #submit-btn",
    "healed":   "By.id: btn-submit",
    "timestamp": "2026-04-27T10:42:11"
  }
]

A developer reviews this file after the run, updates the locator in the page object, and the test is back to clean. The framework does not silently swallow the problem — it surfaces it in a structured, actionable way.

Using it in Selenium Boot

I built all of this into Selenium Boot, an open-source zero-boilerplate Selenium + TestNG framework. To enable self-healing, you add one line to your config:

# selenium-boot.yml
locators:
  selfHealing: true

That's it. No code changes. Every waitForVisible and waitForClickable call in your tests now has automatic fallback healing.

In the HTML report, healed tests get a ⚠ healed badge so they're immediately visible:

✓ LoginTest#submitForm  [⚠ healed]   1.2s

And target/healed-locators.json gives you the exact diff to fix.

What healing covers (and what it doesn't)

Heals well:

id changed (most common — developers rename IDs during refactors)
name attribute changed
Class name changed (single-class selectors)
data-testid added/renamed
Text-based XPath when the element text is stable

Won't heal:

Structurally removed elements (the feature was deleted — this should fail)
Deep CSS selector chains (div.container > ul > li:nth-child(3))
Dynamic content that changes every render

Self-healing is a safety net for legitimate DOM drift, not a substitute for well-maintained locators. The goal is to keep the suite green through minor frontend changes while giving you a clear log of what needs updating.

The bigger takeaway

Locator brittleness is a maintenance tax, not an inherent property of Selenium. With ~100 lines of By.toString() parsing and a hook in your wait layer, you can cut a significant chunk of false failures — and turn every heal into a clear, actionable signal for the team.

The full implementation is in Selenium Boot on GitHub. If you're building a Selenium framework from scratch or inheriting one that's brittle, it's worth a look.

Example Screenshot Of The Report

What's your current strategy for dealing with locator churn? Drop it in the comments.

Forem: Mohammad Saddam Hossain

Zero-config Cucumber + Selenium in Java: no @Before, no driver setup, no cleanup

The Cucumber + Selenium boilerplate problem

What the step definitions should look like

How to get there

The framework hook

The step definition base class

The runner

IDE single-scenario execution

Parallel execution

What you get without writing it

Using it in Selenium Boot

I built self-healing Selenium locators in Java — here's how it works

The problem every Selenium team hits

What if the framework tried to fix itself?

Parsing By.toString() to extract fallbacks

Where it hooks into the wait layer

Logging heals without noise

Using it in Selenium Boot

What healing covers (and what it doesn't)

The bigger takeaway

Example Screenshot Of The Report

Parsing `By.toString()` to extract fallbacks