DEV Community: Mohammad Saddam Hossain

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

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