DEV Community: Mohammad Saddam Hossain

Parallel Selenium Tests in Java Without Thread-Safety Bugs

Mohammad Saddam Hossain — Mon, 27 Jul 2026 01:44:02 +0000

Your suite is green. Someone sets thread-count="4" to get CI under ten minutes, and now
three tests fail. Re-run: two fail, and not the same two. Run it locally and everything
passes.

That's not flakiness in your application. That's your test framework being unsafe under
concurrency, and it was unsafe the whole time — one thread was just hiding it.

The advice you'll find in ten minutes of searching is "wrap the WebDriver in a
ThreadLocal." That's correct, and it's about a third of the answer. Parallel execution
exposes at least four distinct bugs, and ThreadLocal fixes exactly one of them. This
post covers all four, what the real fix looks like for each, and how to check your own
suite without waiting for CI to tell you.

Why a shared WebDriver breaks

WebDriver is not thread-safe, and the Selenium project has never claimed otherwise. A
driver instance is a stateful handle to one browser session: one current URL, one active
window, one set of cookies. Two threads holding the same reference are two tests driving
one browser.

The classic version looks like this, and almost every home-grown framework has shipped it
at some point:

public class BaseTest {
    protected static WebDriver driver;   // ← the bug

    @BeforeMethod
    public void setUp() {
        driver = new ChromeDriver();
    }

    @AfterMethod
    public void tearDown() {
        driver.quit();
    }
}

On one thread this is fine. On four, setUp() runs four times and the last assignment
wins — so all four tests drive whichever browser was created last, while the other three
sit open and idle until the JVM exits. Then tearDown() fires four times on that one
driver, and three of them throw.

The failures this produces are genuinely confusing, because none of them look like a
concurrency bug:

NoSuchElementException on an element that is definitely on the page — because another thread navigated away between your get() and your findElement().
NoSuchSessionException / SessionNotCreatedException — another thread already called quit() on the session you're using.
Assertions that fail with the other test's data, especially anything reading a logged-in user's name.
Chrome processes surviving the build and slowly eating the agent's RAM.

Making the field non-static doesn't fix it either if anything else in the suite reaches for
a driver statically — listeners and screenshot helpers are the usual culprits, and we'll
come back to those.

Bug 1 — the shared driver: ThreadLocal ownership, done properly

The fix is to give each thread its own driver and make it impossible to reach another
thread's. ThreadLocal<WebDriver> does that: every thread that calls get() sees only the
value that thread set.

public final class DriverFactory {

    private static final ThreadLocal<WebDriver> DRIVER = new ThreadLocal<>();

    private DriverFactory() {}

    public static void create() {
        if (DRIVER.get() != null) return;          // idempotent: safe under retry
        DRIVER.set(new ChromeDriver());
    }

    public static WebDriver get() {
        WebDriver driver = DRIVER.get();
        if (driver == null) {
            throw new IllegalStateException(
                "No WebDriver on thread " + Thread.currentThread().getName()
                + ". create() was never called, or quit() already ran.");
        }
        return driver;
    }

    public static void quit() {
        WebDriver driver = DRIVER.get();
        if (driver != null) {
            try {
                driver.quit();
            } finally {
                DRIVER.remove();                   // ← the line people forget
            }
        }
    }
}

Three details in there matter more than the ThreadLocal itself.

DRIVER.remove() is not optional. This is the single most common way a "thread-safe"
driver factory still breaks. Test runners reuse threads — TestNG's thread pool, JUnit 5's
parallel executor, and every CI agent that runs more than one suite per JVM. If you call
quit() without remove(), the next test scheduled onto that thread inherits a
ThreadLocal entry pointing at a dead session, and you get NoSuchSessionException from a
test that never did anything wrong. Worse, on a long-lived JVM the entries are a genuine
memory leak: ThreadLocalMap keys are weak, values are not.

The null check needs to name the thread. When this does go wrong, the difference
between NullPointerException and a message telling you which thread had no driver is
about forty minutes of debugging.

Idempotent creation buys you retries. If a retry listener re-runs a failed test on the
same thread, create() firing twice must not orphan a browser. Returning early when a
driver already exists is the cheap version; explicitly quitting the old one is the thorough
version. Pick one deliberately.

Bug 2 — shared state that isn't the driver

ThreadLocal on the driver fixes the driver. It does nothing for everything else your
suite shares, and this is where the second wave of failures comes from once the obvious one
is gone.

Look for these three:

Page objects with mutable fields. A page object that caches a WebElement, or stores
"the row I just clicked," is fine on one thread and a race on four. Page objects should
hold a driver reference and nothing else — every piece of per-test state belongs in the
test, or in a thread-scoped context object.

Static test data. A static String orderId written by one test and read by another is
the most common non-driver race. So is a shared SimpleDateFormat (not thread-safe), a
shared HashMap used as a scratchpad, and a static counter used to generate "unique"
usernames without an atomic type.

Anything a listener writes to. A TestNG ITestListener or JUnit 5 extension is invoked
on the test's own thread, which is convenient — but if it accumulates into a plain
ArrayList<Result>, four threads appending concurrently will silently drop entries or
throw ArrayIndexOutOfBoundsException from inside ArrayList.add. Use a concurrent
collection, or a per-thread accumulator merged at the end.

The rule that survives contact with real suites: anything a test writes to must be
thread-scoped or thread-safe. There is no third option. If you can't say which of the two
a field is, it's a bug you haven't hit yet.

Bug 3 — screenshots and reports attributed to the wrong test

This one doesn't fail the build, which is why it survives so long. It corrupts your
evidence instead.

A failure screenshot helper that reaches for a driver via a static field, or writes to a
fixed filename like target/failure.png, will happily capture thread 3's browser for
thread 1's failure. You then spend an afternoon debugging a screenshot of a page the failing
test never visited.

Both halves need fixing:

Capture from the failing thread's driver — the listener runs on the test's thread, so pull from your ThreadLocal, not from a field someone assigned during setup.
Write to a unique path — include the test method name and something disambiguating (a timestamp, or the invocation count for data-driven tests). Two @DataProvider rows of the same method failing at once will otherwise overwrite each other.

The same applies to any report aggregator. If you're using ExtentReports, the per-test node
has to be held in a ThreadLocal too, or your steps interleave across tests into an
unreadable report.

Bug 4 — more browsers than the machine or grid can hold

Thread count and browser count are not the same number, and treating them as one is how
parallel suites go from "flaky" to "the agent fell over."

Chrome is roughly 300–700 MB of RSS per instance with a real page loaded. Eight threads on
a 4 GB CI container is not a thread-safety bug — it's the OOM killer, and it shows up as
SessionNotCreatedException, chrome not reachable, or a build that simply dies with no
useful log. Against a remote Grid or a cloud vendor, the same over-subscription shows up as
queued sessions that time out, or as sessions your plan won't grant.

So cap the concurrency separately from the thread count.

Cap concurrency separately from thread count

The pattern is a semaphore between the test and driver creation. Threads that can't get a
slot wait rather than fail:

private static final Semaphore SLOTS = new Semaphore(4, true);  // fair

public static void create() {
    if (DRIVER.get() != null) return;
    try {
        if (!SLOTS.tryAcquire(30, TimeUnit.SECONDS)) {
            throw new IllegalStateException("No browser slot free after 30s");
        }
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new IllegalStateException("Interrupted waiting for a browser slot", e);
    }
    DRIVER.set(new ChromeDriver());
}

and release the permit in quit(), in a finally. The true argument makes the semaphore
fair, which stops one unlucky thread from starving while others cycle through.

Why wait instead of fail fast? Because a test that waits four seconds for a slot is a
correct test. A test that fails because the machine was momentarily busy is a false red,
and false reds are how teams learn to ignore CI.

Set the cap from what the environment can hold, not from what the suite would like. On CI
that's usually memory divided by ~700 MB, minus one. On a cloud grid it's your plan's
concurrency limit.

The bug ThreadLocal can't touch: waits

Parallel execution doesn't create wait bugs. It exposes the ones you already had.

A sleep is calibrated against a load profile. Thread.sleep(2000) was chosen on an
idle laptop talking to a warm backend. Run four browsers on one agent and that machine no
longer exists — same code, different CPU contention, different response times. Sleeps also
cost you on every green run: forty sleeps × 2 seconds is eighty seconds per thread that you
pay even when the page was ready in 200 ms.

Mixing implicit and explicit waits is undefined behaviour. Selenium says so in its own
docs — set implicitlyWait and then use WebDriverWait, and the two compose in ways
neither one documents. You ask for 5 seconds and wait 15, or you get a NoSuchElementException
before your explicit condition ever polls. Under load that unpredictability widens, because
the driver is retrying against a slower page. Set the implicit wait to zero and use explicit
waits only.

"Visible" is not "loaded." A wait for element visibility tells you something rendered.
It doesn't tell you the table has rows. Under parallel the gap between rendered and
populated gets wider, because your backend is serving four suites at once. Wait for the
condition you actually mean: row count above zero, spinner detached, text equal to what you
expect.

Explicit, condition-based waits are the only kind that degrade gracefully. A polling wait on
a busy machine just takes longer. A sleep tuned for an idle machine simply becomes wrong.

Audit your own suite: seven checks

Run these against your repo before you raise the thread count again. Each one takes a minute
except the last, which takes a CI run and is worth more than the other six.

No static WebDriver anywhere. grep -rn "static WebDriver" src/ — every hit is a bug, including the "temporary" one in a utility class.
Your driver holder calls remove(). Open the class that owns the ThreadLocal and search for .remove(). No hit means stale sessions on reused threads plus a slow leak.
No mutable, non-thread-safe fields on shared objects. Walk your page objects and step-definition classes: a field should be final and thread-safe, or it shouldn't be a field.
Count your sleeps. grep -rn "Thread.sleep" src/ | wc -l — that number is how sensitive your suite is to machine load.
Screenshot paths carry the test name. Look at the artifacts from your last red build. If you see failure.png or screenshot (3).png, your evidence isn't attributable.
The browser cap is a separate number from the thread count. Search your config for both. If there's only one number, the two are coupled and one of them is wrong for your CI box.
Run the whole suite twice at your target thread count. Different failures each time means shared state. The same failures both times means real bugs — or a genuinely flaky application. This single check separates those two categories better than any amount of reading.

One answer: don't own the lifecycle at all

Everything above is roughly two hundred lines of infrastructure that has nothing to do with
your application. A driver holder, a semaphore, a screenshot listener that knows about
threads, a config knob for concurrency. It gets written once, reviewed once, and then
maintained — across Selenium upgrades, across a CI migration, and again at the next company.
That's the maintenance tax, and it's the same argument as
The Hidden Cost of Every Selenium Framework You've Built.

One way out is to not own that layer. Selenium Boot — the Spring Boot of Selenium — ships
these fixes as the default path: DriverManager is a ThreadLocal holder that calls
remove() on quit; concurrent sessions are capped by a fair Semaphore sized from
execution.maxActiveSessions, and a thread that can't get a slot waits up to 30 seconds
instead of failing; screenshots and report nodes resolve from the calling thread. It never
hides Selenium — getDriver() returns the real WebDriver, and you can drop to raw
By / WebElement the moment the conventions don't fit.

The configuration is the whole of the setup — this is all of selenium-boot.yml:

execution:
  mode: local
  baseUrl: https://example.com
  parallel: methods      # none | methods | classes
  threadCount: 4
  maxActiveSessions: 4   # fair semaphore; tests wait up to 30s for a slot

browser:
  name: chrome
  headless: true

timeouts:
  explicit: 10
  pageLoad: 30

One honest limit: this covers the framework's own state. It cannot make your static
orderId thread-safe. Bug 2 stays your job under any framework, including this one.

More detail in the parallel execution guide
and the configuration reference,
or the why it exists page if you want the design argument first.

When building it yourself is the right call

Plenty of teams should just write the code above.

If you have one suite, one team, and no parallel ambition beyond four threads, thirty lines
of ThreadLocal is genuinely enough — adopting a framework to avoid it is a bad trade. If
you have a hard constraint no framework will match, like a bespoke driver provider or an
unusual grid topology, own the layer that touches it. And if your team wants to learn
concurrency properly, building it is a good way to do that; the debugging is the point.

None of this is a Playwright argument. If you're greenfield with no Selenium investment,
evaluate Playwright on its merits. This post is for the suites that already exist.

The failure is in the framework, not the app

"Green on one thread, red on four" is a property of your test framework, not your
application. It's a shared driver, or shared state that isn't the driver, or evidence
captured from the wrong thread, or more browsers than the machine can hold — and now you can
tell which. Fix the four, then raise the thread count on purpose instead of hopefully.

Get started with Selenium Boot in five minutes →

The Hidden Cost of Every Selenium Framework You've Built

Mohammad Saddam Hossain — Fri, 17 Jul 2026 03:11:19 +0000

You didn't set out to build a framework. You set out to test a login form.

But somewhere between the first WebDriver driver = new ChromeDriver() and the fiftieth flaky CI run, you built one anyway. There's a BaseTest. There's a DriverFactory. There's a WaitUtils class that everyone copies, and no one fully trusts. There's a reporting hack bolted onto TestNG listeners, and a block of CI YAML that only one person understands.

That's a framework. You just never called it one — and that's exactly why it's so expensive.

The framework you didn't mean to build

Here's the pattern, repeated at nearly every Java shop:

// The BaseTest that grows a little every sprint
public class BaseTest {
    protected WebDriver driver;

    @BeforeMethod
    public void setUp() {
        driver = new ChromeDriver(/* options someone tuned in 2022 */);
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
        // …plus retries, screenshots, and env switching bolted on over time
    }

    @AfterMethod
    public void tearDown(ITestResult result) {
        if (result.getStatus() == ITestResult.FAILURE) {
            // take a screenshot… somehow… attach it… somewhere
        }
        driver.quit();
    }
}

It looks harmless. It's ten lines. But it never stays ten lines, because production testing keeps asking for more: parallel execution, a second browser, cloud grids, retry-on-flake, a report your manager will actually open. Each request adds a little more plumbing — and every line of that plumbing is code you now own.

The five costs nobody budgets for

1. Maintenance you can't schedule. Selenium 4 lands. ChromeDriver changes its options API. A dependency bump breaks your screenshot logic. None of this is on the roadmap, all of it is on you, and it always arrives the week before a release.

2. Onboarding that lives in someone's head. A new engineer can't just read the docs — there are no docs. Onboarding is "sit with Priya and she'll explain the wait helpers." The framework's real specification is tribal knowledge, and it walks out the door when people leave.

3. Parallelism bugs that only appear under load. Home-grown BaseTest classes are notorious for sharing a WebDriver across threads by accident. It passes locally and on a quiet CI box, then corrupts state the moment you scale to real parallelism. Thread-safety is hard, and you're debugging it on top of your actual product.

4. A reporting and CI layer rebuilt from scratch. Every team re-solves the same problems: parse results into something readable, embed failure screenshots, force headless in CI, tune the thread count, wire up JUnit XML so Jenkins understands it. It's weeks of work that produces nothing your users ever see.

5. The opportunity cost. Every hour spent maintaining the harness is an hour not spent writing tests that catch real bugs. You hired test engineers to improve quality — and a chunk of their time goes to being unpaid framework maintainers instead.

The cost isn't that a home-grown framework is bad. It's that it's infrastructure you're maintaining for free, and the bill compounds with every project that rebuilds it.

"But it's just a BaseTest"

That's the trap. It's just a BaseTest — until it's a BaseTest, a BasePage, a DriverFactory, a ConfigLoader, a RetryAnalyzer, a ScreenshotListener, a ReportBuilder, and a folder of utilities that three other repos have already forked and diverged from.

You didn't decide to maintain a framework. You accreted one. And because it grew a line at a time, nobody ever made the call to ask: should we be building this at all?

What if that framework were just… maintained for you?

This is the entire idea behind Selenium Boot. Your real alternative to a home-grown framework isn't "no framework" — it's someone else's, maintained, tested, and documented. Selenium Boot is that framework: Spring Boot's conventions, applied to Selenium. You add one dependency and the plumbing is handled.

public class LoginTest extends BaseTest {

    @Test
    public void login() {
        open("/login");                       // baseUrl from config
        getByLabel("Username").fill("admin");
        getByRole(Role.BUTTON)
            .withName("Sign in").click();     // auto-waits, no sleep()
        assertThat(getByText("Welcome"))
            .isVisible();                      // web-first, retries until true
    }
}

No driver setup. No teardown. No Thread.sleep(). No brittle CSS selectors. The driver lifecycle is thread-safe by default, retries and reporting are built in, and CI configures itself. The five costs above? They're now someone else's job — and that someone ships the fixes, writes the docs, and tests the parallel path so you don't have to.

Crucially, it never hides Selenium. When the conventions don't fit, drop straight down to raw WebDriver / By / WebElement. It's opinionated, not a cage — and it brings Playwright's best ideas (accessibility-first locators, auto-waiting, web-first assertions) into the Selenium ecosystem you already run, keeping your Grid, your Java, and your team's skills.

It's not a Playwright replacement — the architecture is genuinely different, and if you're greenfield with no Selenium investment, Playwright is a reasonable choice. This is for the many teams with years of Selenium/Java/Grid they can't rip out.

Keep your test code. Delete the plumbing.

Look at your repo. The test intent — the part that says "a valid user can log in" — is genuinely yours, and it's valuable. The BaseTest, the DriverFactory, the wait-utils? That's the part you never wanted to own.

Selenium Boot lets teams focus on testing, not framework engineering. Keep the first part. Delete the second.

If you've built the framework in this post — and most Java teams have — that's not a criticism. It's just a bill you no longer have to pay.

Selenium Boot is open source (Apache-2.0), Java 17+, TestNG and JUnit 5. Full disclosure: it's my project.

Get started in five minutes →

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.

DEV Community: Mohammad Saddam Hossain

Parallel Selenium Tests in Java Without Thread-Safety Bugs

Why a shared WebDriver breaks

Bug 1 — the shared driver: ThreadLocal ownership, done properly

Bug 2 — shared state that isn't the driver

Bug 3 — screenshots and reports attributed to the wrong test

Bug 4 — more browsers than the machine or grid can hold

Cap concurrency separately from thread count

The bug ThreadLocal can't touch: waits

Audit your own suite: seven checks

One answer: don't own the lifecycle at all

When building it yourself is the right call

The failure is in the framework, not the app

The Hidden Cost of Every Selenium Framework You've Built

The framework you didn't mean to build

The five costs nobody budgets for

"But it's just a BaseTest"

What if that framework were just… maintained for you?

Keep your test code. Delete the plumbing.

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