DEV Community: Volta Jebaprashanth

The Wait Condition You Actually Need Almost Never Matches the One You Wrote

Volta Jebaprashanth — Sun, 09 Aug 2026 10:35:13 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server built for test automation engineers working in Java, Selenium, and REST Assured. It gives an AI coding agent a real Selenium WebDriver session to drive Chrome, Firefox, or Edge directly — structured element discovery for reliable locators, Chrome DevTools Protocol network/console tooling, and a standalone REST client, all in one server. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Ask any Selenium engineer to name the single biggest source of flaky tests in their suite, and "waits" wins almost every time — not because waiting is conceptually hard, but because picking the right wait condition requires knowing exactly what the page is doing at that moment, and most of the time you're guessing.

You wait for an element to be visible, but the click handler attached to it hasn't finished initializing. You wait for a URL to change, but the page it changed to is still fetching the data it needs to render. You wait for text to appear, but it appears immediately in a loading state and then changes again half a second later. Every one of these produces a test that passes locally nine times out of ten and fails in CI often enough to erode trust in the whole suite.

This piece is about how selenium-mcp's wait tooling — and the CDP-backed network tools sitting next to it — help an AI coding assistant actually diagnose which condition you need, instead of you iterating through Thread.sleep() values by hand.

The full set of wait conditions available

WaitTools covers the standard explicit-wait surface, all with a configurable timeout (default 10s):

waitForVisible / waitForClickable / waitForPresent / waitForInvisible — the core element-state waits.
waitForTextPresent — waits until an element contains specific text, useful for loading-state-to-final-state transitions.
waitForTitleContains / waitForUrlContains — page-level navigation waits.
waitForPageLoad — waits until document.readyState is "complete".
waitForJsCondition — waits until an arbitrary JavaScript expression evaluates truthy, for the cases where none of the built-in conditions quite fit.
waitForElementCount — waits until the number of elements matching a locator equals an expected count, handy for list/table rendering that happens incrementally.
waitForAttributeToBe — waits until an element's attribute or DOM property equals an expected value.
waitForNumberOfWindowsToBe — waits until the open window/tab count matches, for flows that open a new tab.

And critically, sitting in NetworkTools rather than WaitTools because it's CDP-backed: waitForNetworkIdle, which waits until there have been no in-flight HTTP requests for a continuous idle period. This is the condition that actually matches what most engineers mean when they add a sleep "to let things settle" — not an element state, but the absence of pending network activity.

Why having an agent pick the condition is the actual value-add

Any experienced Selenium engineer knows this list already. The hard part was never knowing the API — it's diagnosing, for a specific flaky test, which condition actually corresponds to the real race. That diagnosis normally means reproducing the failure, watching it happen (ideally slowed down or recorded), and reasoning backward from what state the page was actually in when the assertion fired too early.

With an AI agent that has both WaitTools and NetworkTools available in the same session, that diagnosis becomes something you can actually delegate. A reasonable prompt: "This test fails intermittently at the assertOrderConfirmed step. Run it, capture the network log and console output around that assertion, and tell me what's actually still pending when it fails." The agent can drive the flow, pull getNetworkLog and getConsoleLogs scoped to that window, and tell you concretely — "there's a POST /api/orders still in flight when the assertion runs" — instead of you inferring it from a screenshot or a CI video recording.

Once the actual cause is known, the fix is usually obvious and small: swap a blind Thread.sleep(2000) for waitForNetworkIdle, or add waitForElementCount where the UI renders a list in multiple network round trips instead of one. The value isn't that the agent knows an API you didn't — it's that it can run the reproduction and read the evidence faster than you can context-switch into doing it yourself, especially for a test that only fails intermittently and needs a few reproduction attempts to catch in the act.

A pattern worth adopting even without an AI agent in the loop

Independent of whether you're using an agent at all: if you're debugging a flaky Selenium test today, reach for waitForNetworkIdle and a network log before you reach for a longer sleep. A longer sleep treats the symptom and makes your suite slower for everyone, forever, whether or not the race condition is even still there next month. Actually looking at what's in flight when the assertion fires tells you the real cause, and usually the real fix is a more precise wait, not a bigger one.

Full parameter details for every wait condition and the network tools they pair with are on the tool reference. If your suite has a flaky test sitting in a "known issue, don't have time" state right now, it's a reasonable one to try this against first.

I Looked at Every Selenium MCP Server I Could Find Before Building My Own. Here's the Actual Landscape.

Volta Jebaprashanth — Sun, 09 Aug 2026 10:33:07 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives an AI coding assistant a real Selenium WebDriver session to inspect and drive Chrome, Firefox, or Edge directly, built specifically for test automation engineers working in Java, Selenium, and REST Assured. It combines structured element discovery for reliable locators, Chrome DevTools Protocol network/console tooling, and a standalone REST client in one server. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Before writing a single line of selenium-mcp, I did what you're supposed to do before building anything: I checked whether it already existed. It's a reasonable thing to want to verify as a reader too — "another Selenium MCP server" is a fair amount of skepticism to bring to a new one. So here's the honest landscape, from the perspective of the audience this project is actually for: test automation engineers working in Java, Selenium, and REST Assured, evaluating whether any of these tools help with that specific job, not general browser automation.

What's actually out there

There are more Selenium MCP servers than you'd expect — a healthy sign the underlying idea (let an AI agent drive Selenium) is obviously useful. Most cluster around the same shape:

Node.js/TypeScript implementations, several of which expose 15–80+ tools covering browser lifecycle, element interaction, and window/frame/cookie management — the standard Selenium surface. One of the more complete ones even includes an accessibility-tree resource for structured page inspection, which is a genuinely good idea done well. What none of them offer, as far as I found: a REST client for API testing alongside the browser tools, or Chrome DevTools Protocol access for network mocking/blocking. And structurally, they're aimed at general agentic browser automation — the target user is "an agent doing a task in a browser," not specifically a Java engineer maintaining a Selenium test suite.

Python implementations, similar shape — solid coverage of core Selenium actions, locator-based find/click/type tooling, screenshots. Same gap: no structured ancestor/sibling context for disambiguating locators, no CDP-backed network tooling, no adjacent API-testing capability.

Remote/browserless-backed implementations, built for connecting to a Selenium Grid or a browserless service rather than driving a local browser — useful for a specific infrastructure pattern, but orthogonal to the locator-discovery and API-testing gaps this piece is about.

I want to be fair here: several of these are well-built, actively maintained projects solving a real problem — browser automation for AI agents, full stop. That's a legitimate and different goal from what selenium-mcp is for.

What's specifically missing, and it's the same gap every time

Across essentially all of them, three things are consistently absent — and they're the three things that matter most if your actual job is maintaining a Java test suite, not just getting an agent to click through a demo:

Structured, disambiguating element discovery. Most expose a find_element-equivalent plus raw page source. None I found return a match's ancestor chain with sibling position/count the way getPageElementsFiltered does — the specific thing that lets an agent construct a locator that's unique before trying it, instead of hitting NoSuchElementException and iterating.
CDP-backed network and console tooling. Selenium 4 has had HasDevTools/NetworkInterceptor access for a while. Almost nobody wires it up. Network capture shows up occasionally; mocking, blocking, simulated network conditions, and console log capture — the tools that actually help diagnose a flaky test — are rare to absent.
A standalone REST client for API testing. Not one of the general-purpose Selenium MCP servers I found ships an HTTP client alongside the browser tools. Given that REST Assured's own repo has an open issue asking for exactly this kind of AI-driven API testing support, this isn't a niche gap — it's a documented, unaddressed one across the whole Java testing ecosystem, not just among Selenium MCP servers specifically.

Where Playwright MCP fits into this

Playwright MCP deserves its own mention because it's the project that proved the underlying idea — structured page inspection beats raw HTML dumps for agent reliability — at scale, with official backing. It's excellent. It's also Node/Playwright, which means it does nothing for a team whose suite, CI, and team expertise are Java and Selenium, short of a full framework migration. I've written more on that specific trade-off separately — the short version is that selenium-mcp brings the same category of capability natively into Selenium, rather than asking Java teams to leave it.

Where selenium-mcp actually sits

Putting it plainly, without the hedging: selenium-mcp is, as far as I've been able to verify, the only Selenium-based MCP server that combines all three of structured ancestor/sibling-aware element discovery, CDP-backed network/console tooling, and a standalone REST client for API testing — built in Java specifically so it drops into an existing Selenium/Maven toolchain rather than asking a team to adopt a new language or runtime. If you know of another implementation that covers this same combination, I'd genuinely like to hear about it — open an issue or a discussion, comparisons like this are only useful if they stay accurate as the landscape moves.

If you want to check the claims yourself rather than take my word for it, the tool reference lists every one of the 112 tools with parameters, and the repo is MIT-licensed and open for inspection.

Your Bank's QA Team Isn't Rewriting Ten Years of Selenium Tests for Anything. Here's What They Can Actually Adopt.

Volta Jebaprashanth — Sun, 09 Aug 2026 10:30:28 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives an AI coding assistant a real Selenium WebDriver session, built specifically for test automation engineers working in Java, Selenium, and REST Assured. It drives Chrome, Firefox, or Edge directly, finds elements with enough structure to build locators that are unique on the first try, and adds Chrome DevTools Protocol network/console tooling plus a standalone REST client — as a development-time tool that plugs into an existing Selenium/Maven suite. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Enterprise QA doesn't move like a startup. If you're on a test automation team at a bank, an insurer, a healthcare company, or basically anywhere with a compliance department, you've got a Selenium suite that's been growing for years, a Selenium Grid or a cloud grid provider running it in CI, TestNG or JUnit reporting feeding into whatever dashboard your stakeholders check, and a very good reason not to touch any of it lightly: it works, it's audited, and "we rewrote our test framework" is not a sentence anyone wants to say after a compliance-relevant regression slips through.

That's exactly the environment where most "AI-powered testing" pitches fall apart. They assume you're starting fresh, or that you're willing to adopt a new framework, a new language, a new CI integration. Enterprise QA teams correctly don't do that. I built selenium-mcp to be adoptable by teams in exactly this position — because it doesn't ask you to change anything about how your suite runs. It only changes how new tests get written and how existing ones get debugged.

Nothing about your CI pipeline changes

This is worth stating plainly because it's the first question a lead will ask: selenium-mcp is a development-time tool. It runs on an engineer's machine, alongside their MCP-capable coding assistant, while they're writing or debugging a test. The tests it helps produce are plain Java files using plain Selenium and, where relevant, a plain REST client. They get committed to the same repo, run through the same Maven build, execute on the same Selenium Grid, and report through the same TestNG/JUnit pipeline your team already has. Nothing about the CI side of your pipeline needs to know this tool exists.

Compare that to the alternative most teams imagine when they hear "AI-assisted testing" — a hosted platform that runs your tests in its own cloud sandbox, with its own reporting, its own auth model, its own vendor relationship for a compliance team to evaluate. That's a much bigger adoption decision, and for a lot of enterprise teams, a non-starter on procurement grounds alone before anyone even evaluates whether it's good.

Where it actually helps day to day

Two workflows come up constantly on established Selenium teams, and both are exactly what this tool targets:

Writing new tests against pages your team didn't build. Enterprise apps are frequently a patchwork of internal teams, contractors, and acquired products, which means your QA engineers are constantly writing locators against markup nobody on your team wrote and nobody documented. getPageElementsFiltered — the tool that finds every match for a locator and returns its ancestor chain and sibling position — turns that into an inspection an agent can do directly against your actual staging environment, instead of your engineer manually reverse-engineering someone else's <div> soup in DevTools every time.

Debugging flaky tests in an established suite. A suite with years of history has years of accumulated flaky tests nobody's had time to properly fix — the ones with a Thread.sleep() some engineer added years ago as a stopgap that never got revisited. NetworkTools, particularly waitForNetworkIdle and getNetworkLog, gives an agent a way to actually diagnose why a wait was needed in the first place, built on Chrome DevTools Protocol access that Selenium 4 already has but almost nobody wires up by hand.

The audit trail question

If your organization needs to know what changed and why — normal for regulated industries — the answer here is straightforward: every change an agent makes shows up as a normal diff in a normal pull request, same as if an engineer wrote it. There's no separate system generating or modifying tests outside your existing review process. The agent is a tool an engineer uses while writing a PR, not a system with its own write access to your codebase or CI.

Where to start if this is your situation

Don't roll this out to a whole QA org on day one. Pick one engineer, one moderately painful area of the suite — a flaky test nobody's had time to fix, or a page with locators nobody trusts — and let them try selenium-mcp against it for a week. The output is a plain Java diff either way; it's reviewable with exactly the rigor your team already applies to any PR. Quickstart's here if that's the plan.

Full tool reference, including everything mentioned above, is on the docs site.

From Zero to a Working Selenium Test, Written by an AI Agent That Can Actually See the Page

Volta Jebaprashanth — Sun, 09 Aug 2026 10:27:48 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server built for test automation engineers working in Java, Selenium, and REST Assured. It gives an AI coding agent — Claude Code, Cursor, Claude Desktop, anything that speaks MCP — a real Selenium WebDriver session it can drive directly, with structured element discovery, CDP network/console tooling, and a standalone REST client, instead of guessing at locators from pasted HTML. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

This one's a walkthrough, not an argument. If you're a test automation engineer curious about selenium-mcp but haven't tried it yet, here's exactly how to go from nothing to an AI coding assistant writing a real, passing Selenium test against a page it inspected itself.

Prerequisites

Nothing exotic:

Java 21+, with JAVA_HOME pointing at it
Chrome, Firefox, or Edge installed locally — WebDriver binaries are fetched automatically on first use, no manual driver management
An MCP-capable client: Claude Code, Claude Desktop, Cursor, etc.

That's the whole list. No Node toolchain, no separate browser runtime to install — the server drives the actual browser you already have.

Step 1 — Grab the jar

Every push to main publishes a fresh GitHub Release with the jar attached, so there's no build step required:

⬇ Download selenium-mcp.jar (latest release)

If you'd rather build from source:

git clone https://github.com/Volta-Jebaprashanth/selenium-mcp.git
cd selenium-mcp
mvn clean package

Step 2 — Point your MCP client at it

The server talks over stdio, so it's launched by your MCP client rather than run standalone in a terminal. For Claude Code or Claude Desktop, add this to your MCP server config, adjusting the path to wherever you saved the jar:

{
  "mcpServers": {
    "selenium-mcp": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/selenium-mcp.jar"]
    }
  }
}

Restart your client, and you should see selenium-mcp show up as an available tool provider, with all 112 tools across 16 categories ready to call.

Step 3 — Point it at your actual Maven project

This is the part that matters if you're evaluating this for real work rather than just kicking the tires: open your MCP client in the same workspace as your existing Java/Selenium/Maven test project. The agent isn't just driving a throwaway browser session — it's writing Java files directly into your src/test/java tree, using whatever test framework (TestNG, JUnit 5) and structure your project already has.

Step 4 — Ask for a real test

Here's a prompt shape that exercises the actual point of the tool, rather than a toy example:

"Open Chrome and navigate to our staging login page at https://staging.example.com/login. Inspect the email and password fields using the page element tools, then write a LoginPageTest class in our existing LoginPage Page Object style, using TestNG, that logs in with a valid test user and asserts we land on the dashboard."

Watch the tool calls as they happen (most MCP clients show these): openBrowser, navigate, then getPageElementsFiltered against the login form to get real ancestor/sibling-disambiguated locators — not guesses. The agent writes the By selectors from what it actually found on the page, adds a waitForVisible or waitForPageLoad where the flow needs it, and hands you a test file that follows your project's existing conventions because it can see them, same as it can see the page.

Step 5 — Run it, review it like any other PR

The output is a plain Java file using standard Selenium and your existing test framework — nothing proprietary, no runtime dependency on the MCP server itself (see the architecture piece if you want the detail on why that's true by design). Run it with your normal mvn test. Review it the way you'd review any teammate's PR — check the locators are sensible, check the waits are appropriate, ask for changes the same way you would with a human's first draft.

A few things worth trying beyond the first test

Once the basic loop works, a few follow-ups are worth exploring in the same session:

Ask it to add a REST Assured-style verification step using ApiTools, seeding or checking data through the API instead of only through the UI — see the API+UI piece for what that looks like in practice.
Point it at a flaky existing test and ask it to diagnose the timing issue using NetworkTools — waitForNetworkIdle and getNetworkLog in particular.
Ask it to refactor an existing Page Object's brittle locators using getPageElementsFiltered, rather than only writing new ones.

If something doesn't work

The project is MIT-licensed and actively maintained — if a tool call behaves unexpectedly or a locator strategy you need isn't supported, open an issue. The full, searchable tool reference — every parameter, every category — lives on the docs site, worth bookmarking once you're past the first test and exploring what else is available.

No, Your Team Doesn't Need to Rewrite Its Selenium Suite in Playwright to Get AI-Assisted Testing

Volta Jebaprashanth — Sun, 09 Aug 2026 10:24:40 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives an AI coding assistant a real Selenium WebDriver session to drive Chrome, Firefox, or Edge directly, built specifically for test automation engineers working in Java, Selenium, and REST Assured. It covers structured element discovery for reliable locators, Chrome DevTools Protocol network/console debugging, and a standalone REST client for API testing — all inside the Selenium/Maven toolchain teams already run. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Every few months, someone on a Java QA team asks the same question in a different form: "should we just move to Playwright? It's got better AI tooling, better tracing, the MCP server is official." It's a fair question. Playwright MCP is genuinely good — structured accessibility-tree snapshots, official Microsoft backing, tight integration with the framework it's built for.

It's also, for a huge share of enterprise QA teams, not a realistic answer. You don't migrate a decade of Selenium suites, a CI pipeline built around a Selenium Grid, a team of engineers who know Java and TestNG, and every internal utility library built on top of WebDriver, just to get an AI coding assistant that can see the page. That's not a tooling decision, that's a multi-quarter migration project with its own risk, and most teams correctly won't sign up for it just to unlock a developer-experience improvement.

This is the actual reason I built selenium-mcp: so Java/Selenium teams get the same category of capability without the rewrite.

What Playwright MCP actually solved

Worth being precise about this, since it's the thing everyone's actually asking for. Playwright MCP's core contribution is replacing raw DOM dumps with a structured accessibility-tree snapshot — an agent reasons about "the Sign In button" as a distinct, addressable thing instead of parsing markup by eye. That's the capability that made AI-driven browser testing actually reliable instead of a novelty.

selenium-mcp brings the same underlying idea to Selenium — not the identical mechanism (Selenium doesn't expose Playwright's accessibility-snapshot API), but the same outcome: getPageElementsFiltered finds every element matching a locator and returns it with full ancestor-chain and sibling-position context, so an agent builds a locator that's unique by construction instead of by guesswork. Same problem, same category of fix, native to Selenium instead of bolted onto it.

Where the two genuinely differ, past that

Being straight about trade-offs matters more than pretending there aren't any:

Language and existing investment. Playwright MCP is Node.js. If your suite, your CI, and your team's expertise are already Java/Selenium, selenium-mcp runs as a single jar inside that same world — no new language, no new CI toolchain, no new runtime to operationalize.
Browser engine. Playwright drives Chromium, Firefox, and WebKit through its own automation protocol. Selenium drives real Chrome, Firefox, and Edge through WebDriver — the actual browsers your users run, via the actual protocol your existing suite already trusts.
API testing in the same tool. selenium-mcp ships a standalone REST client (ApiTools) alongside the browser tools, so an agent can help write a REST Assured-style verification step in the same session as a UI step. Playwright MCP is scoped to the browser; API testing is a separate concern in that ecosystem.
CDP-backed network and console tooling. Both expose network capture; selenium-mcp additionally offers request mocking/blocking and simulated network conditions via Chrome DevTools Protocol on Chrome/Edge — the same low-level access, made reachable from Selenium instead of requiring you to already be on Playwright to get it.

What this isn't

This isn't "Selenium is better than Playwright" — that's a different, much older debate, and it depends heavily on what you're testing and how your team already works. This is specifically about the AI-assisted testing gap: if your team's stack is already Playwright, you have this solved. If it's Java and Selenium, you didn't, until now, and the honest fix for that gap was never "switch frameworks" — it was "bring the same capability natively to the framework you're already using and already trust."

The actual decision in front of most teams

If you're starting a browser-automation project from zero today, with no existing suite and no team constraints, the Playwright-vs-Selenium conversation is genuinely open and worth having on its own merits. But that's not the situation most QA organizations reading this are in. You have a working Selenium suite, a CI pipeline that runs it, and engineers who are productive in Java. The question was never "is Playwright's tooling nicer" — often, yes. The question is whether that's worth a rewrite. For most teams, it isn't, and now it doesn't have to be a trade-off you make at all.

Full tool reference is on the docs site if you want to see exactly what's available before deciding whether this closes the gap for your team.

I Didn't Want an AI Tool That Pollutes My Test Codebase. Here's How the Architecture Prevents That.

Volta Jebaprashanth — Sun, 09 Aug 2026 10:21:47 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server built for test automation engineers working in Java, Selenium, and REST Assured. It gives an AI coding assistant a real Selenium WebDriver session to drive Chrome, Firefox, or Edge directly — structured element discovery for reliable locators, Chrome DevTools Protocol network/console tooling, and a standalone REST client, all in one server. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

A fair worry, if you're a test automation engineer looking at any AI-adjacent tool: does adopting this mean my codebase now has some framework's fingerprints all over it? Half the "AI-powered testing" tools out there generate code that's obviously generated — proprietary annotations, a runtime dependency on the vendor's SDK, patterns your team wouldn't have chosen on their own. You end up maintaining the AI tool's opinions as much as your actual tests.

That was a hard constraint for me going into selenium-mcp: whatever code an agent writes using this should look exactly like Selenium code a senior engineer on your team would have written by hand. No trace of "an MCP server helped write this." Here's how the architecture makes that true, not just a claim in a README.

Three layers, deliberately kept apart

tools/      @McpTool-annotated classes. MCP-facing only.
webdriver/  Plain-Java Selenium layer. No Spring, no MCP annotations.
http/       Plain-Java REST client. No Selenium/Spring/MCP dependency at all.

The tools/ package is the only place that knows this is an MCP server at all — parameter validation, "is a browser open" precondition checks, translating exceptions into readable strings. Genuinely thin.

webdriver/ is where the real work happens, and it has zero knowledge of MCP, Spring, or an AI agent existing. Tools.java is the facade; BrowserFactory, BrowserSession, Locators, Navigator, ElementInteractor, and the rest are single-responsibility collaborators wired through constructors. This is exactly the shape a hand-written Selenium utility layer would take if you built it from scratch with clean separation of concerns.

http/ mirrors that for the REST client (ApiClient) — standalone, no relationship to the browser session or the MCP layer at all.

Why this matters beyond "clean code"

It's not an aesthetic preference. It has a concrete consequence: webdriver/Tools is usable directly, with no MCP server running at all, as a standalone Selenium utility layer for hand-writing or generating tests. Same for http/ApiClient on the API side. The AI-assisted layer sits on top of a plain Java Selenium library — it isn't a separate thing that happens to also produce Selenium-shaped output. When an agent uses selenium-mcp to explore a page and then writes a LoginPage class for your suite, the Java it writes calls the same kind of APIs — driver.findElement(By.cssSelector(...)), explicit WebDriverWaits — that you'd write yourself, because under the hood, that's genuinely what's running.

That's the difference between "AI tool that happens to output Java" and "Selenium library an AI agent happens to be using." The second one is what you actually want in a codebase your whole team maintains, agent-assisted or not.

The rule that keeps it that way

There's a hard line documented in the project's AGENTS.md, the file that governs how AI coding agents are allowed to modify the project itself: no Selenium calls in tools/, no MCP/Spring types in webdriver/ or http/. It's enforced by convention and code review, not a compiler — but it's the single rule that keeps the Selenium layer honest as a standalone library instead of slowly growing MCP-specific assumptions into itself over time.

There's a second convention worth calling out for anyone auditing this before adopting it: @McpTool methods always return strings, success or failure — exceptions are caught in the tool wrapper and turned into a descriptive message rather than propagating out. That's a deliberate MCP-protocol-compatibility choice at the tools/ boundary, and it stays exactly at that boundary — it doesn't leak into how webdriver/Tools itself is written, which throws normal Java exceptions like any other library.

CDP support gets the same treatment

One more example, because it's a real edge case: NetworkMonitor and ConsoleLogMonitor are built on Selenium 4's Chrome DevTools Protocol support, which Firefox doesn't implement. Their methods throw UnsupportedOperationException on an unsupported driver — that's plain Java behavior, no MCP awareness. It's only the tools/NetworkTools wrapper that catches that specific exception and turns it into an explanatory string for the agent. The distinction matters: the capability boundary is enforced in the Selenium layer, where it belongs; the "make this readable for an AI client" translation happens only at the very top.

What this means if you're evaluating this for your team

If your team is cautious about adopting AI tooling into a shared test codebase — a completely reasonable position — the thing to check isn't "does it generate working tests," it's "what does the generated code actually depend on." Here, the answer is: your test files depend on plain Selenium and a plain REST client, same as if you'd written them by hand. The MCP server is a development-time tool, not a runtime dependency your suite inherits. You can stop using selenium-mcp entirely tomorrow and every test it helped write keeps running exactly as it does today.

Full project structure is documented in the README and AGENTS.md if you want to see the layering rules in full before pointing an agent at your repo.

REST Assured Doesn't Have an Official AI Tool Yet. Here's Why That Matters More Than It Sounds.

Volta Jebaprashanth — Sun, 09 Aug 2026 10:18:43 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives an AI coding assistant a real Selenium WebDriver session — plus a standalone REST client — built specifically for test automation engineers working in Java, Selenium, and REST Assured. It drives Chrome, Firefox, or Edge directly, discovers page elements with enough structure to write locators that are unique on the first try, and exposes Chrome DevTools Protocol tooling alongside plain HTTP request tools for API testing. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Go look at issue #1832 on the REST Assured GitHub repo. Someone's asking, plainly: is there a plan for an official MCP server, so AI agents can drive API test automation the way they've started driving everything else? As of writing, there's no official answer.

That's a small GitHub issue, but it says something real about where the current wave of "AI-assisted testing" tooling has and hasn't reached. If you write UI tests in Playwright and TypeScript, or you're doing general web scraping, there's no shortage of AI tooling aimed at you. If you write Java, Selenium, and REST Assured — which describes a huge share of enterprise QA teams — the tooling gap is real, and it's not just about the browser. It's about the API layer too.

I built selenium-mcp to close both halves of that gap at once, for exactly that audience.

Why a browser tool also needs an API client

Think about how a real end-to-end test actually gets written. You rarely test the UI in total isolation — you seed data through an API first (create a user, create an order), drive the UI flow, and then very often verify the result by calling the API again rather than scraping it back out of the DOM. That's the whole reason REST Assured exists next to Selenium in so many Java test suites in the first place: UI and API testing are two tools for the same job, used together constantly.

An AI coding assistant that can only see the browser is missing half of that picture. It can help you write the UI half of a test and then just... stop, and hand the API half back to you. That's the same "you do the real work, I'll type it up" problem I've written about with locators — just showing up in a different part of the test.

What `ApiTools` gives you

ApiTools is a standalone HTTP client, independent of the browser session entirely — it works whether or not a browser is even open. It gives an agent:

httpGet / httpDelete — GET/DELETE with optional headers.
httpPost / httpPut / httpPatch — send a body plus optional headers.
httpRequest — arbitrary HTTP method, for the odd HEAD or OPTIONS check.

Every response comes back as a consistent JSON shape — {status, headers, body, durationMillis} — which matters more than it sounds like: it means the agent (and you, reading the tool call output) get response and timing back from the same call, useful when you're checking not just correctness but whether an endpoint is meeting a latency expectation as part of the test. Headers go in as a plain JSON object string, e.g. {"Authorization": "Bearer xyz", "Content-Type": "application/json"} — nothing to memorize beyond what you'd already write in REST Assured itself.

What this looks like in a real test

Say you're writing an end-to-end checkout test. The flow is: create a test user via API, log that user in through the UI, add an item to the cart, complete checkout, then verify the order landed correctly by calling the orders API directly rather than trusting a confirmation <div> on screen.

With ApiTools and BrowserTools/PageSourceTools available in the same agent session, you can ask for exactly that end-to-end flow in one request, and the agent writes it as one coherent Java test — httpPost to seed the user, Selenium calls (with correctly discovered locators, via getPageElementsFiltered) to drive the UI, httpGet to verify the order — instead of you assembling the API call yourself and asking the agent to "add this in."

Why this is different from a general-purpose REST client tool

There are plenty of standalone MCP servers that just do HTTP requests — Postman-style tools, generic API testers. What makes this different isn't the HTTP client itself; it's that it lives in the same session as the Selenium tooling, so an agent building a test doesn't have to context-switch between two separate MCP servers to write one test that spans both layers. One conversation, one Java test file, both halves of your suite's actual working pattern reflected in the output.

It's also, notably, not something the Node/Python Selenium MCP servers offer either — most of them are scoped to browser automation alone, aimed at agentic browsing rather than test-suite authoring. Between that and the open question on REST Assured's own repo about official AI tooling, this is a gap that's been sitting unaddressed on the Java/Selenium/REST Assured side specifically, not something everyone else already solved and I just packaged differently.

Full details on request/response shapes are on the tool reference. If you're maintaining a suite that already mixes REST Assured and Selenium, this is the part of selenium-mcp worth trying first — it's the piece that mirrors how you were already structuring tests, not a new pattern to learn.

Your Selenium Test Isn't Flaky. Your Backend Is Just Slower Than Your Thread.sleep().

Volta Jebaprashanth — Sun, 09 Aug 2026 10:13:16 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives an AI coding assistant — Claude Code, Cursor, Claude Desktop — a real Selenium WebDriver session to drive Chrome, Firefox, or Edge directly, built specifically for test automation engineers working in Java, Selenium, and REST Assured. Beyond structured element discovery for reliable locators, it exposes Chrome DevTools Protocol tooling for network capture, mocking, and console log debugging, plus a standalone REST client for API testing. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Every Selenium suite has that one test. It passes locally, fails in CI, passes again if you re-run it, fails again next Tuesday for no obvious reason. Nine times out of ten, when you actually dig in, the cause isn't your locator or your assertion — it's timing. Some XHR call the click triggered hadn't finished when your test tried to read the result.

The usual fixes are all some flavor of unsatisfying: a Thread.sleep(2000) that either wastes time or isn't long enough depending on the day, or an explicit wait on a UI element that only implies the network call behind it has settled. Neither one tells you what's actually happening on the wire.

Selenium 4 quietly shipped access to the Chrome DevTools Protocol — the same low-level API Chrome's own DevTools panel uses — which means you can actually see the network traffic, not just guess at it from what rendered. Most Selenium suites never touch it, because wiring up HasDevTools and NetworkInterceptor by hand is enough ceremony that people reach for Thread.sleep() instead. I wired it into selenium-mcp so an AI coding assistant can use it on your behalf, as part of writing or debugging a Java Selenium test.

What `NetworkTools` actually gives you

This group is built on Selenium 4's CDP support and works against Chrome and Edge (Firefox doesn't expose CDP the same way — every tool in this group returns a clear explanatory message instead of throwing if you call it on an unsupported browser, so it fails loud and readable, not silently).

The tool that solves the flaky-wait problem directly is waitForNetworkIdle — it waits until there have been no in-flight HTTP requests for a continuous idle period. That's the actual condition you meant when you wrote a fixed sleep after a click that triggers an XHR call. Pair it with getPendingRequestCount when you want to assert why a wait is still blocking, instead of just watching it time out.

Beyond that:

startNetworkCapture / stopNetworkCapture — passively record method, URL, headers, bodies, status, and timing for every request, optionally filtered by a URL regex, so you're not drowning in analytics beacons and font requests.
getNetworkLog / clearNetworkLog — pull captured entries back as JSON, filterable by URL pattern or method, most recent last.
mockResponse / clearMockResponses — stub a response for requests matching a URL regex (status, headers, body) without touching the real network. Genuinely useful for testing a UI's error-handling path when you can't easily make the real backend return a 500 on demand.
blockRequests / clearBlockedRequests — block requests matching a URL regex outright (immediate 403). Handy for stripping third-party ad/tracker calls that add flakiness to a test with nothing to do with what you're actually testing.
setNetworkConditions / getNetworkConditions / clearNetworkConditions — simulate offline mode, added latency, or throttled throughput, for testing how your app behaves on a bad connection without needing an actual bad connection.
setBasicAuthCredentials — register HTTP Basic auth so a login popup never blocks navigation in the first place.
startConsoleCapture, getConsoleLogs / clearConsoleLogs — capture browser console output (console.log/warn/error), filterable by type. When a test fails and you can't tell if it's a UI bug or a JS exception, this is usually the fastest way to find out.

Where this actually changes how you debug

Picture the standard flaky-test investigation: a test fails intermittently in CI, passes locally, and you can't reproduce it on demand. Normally that's an afternoon of adding sleeps, staring at video recordings, and guessing.

With an AI agent driving this toolset, you can instead ask it to reproduce the flow, capture the network log around the failing assertion, and check console output for the same window — in one pass, from inside your chat. If the real cause is a request that's still pending when the assertion runs, getNetworkLog and getPendingRequestCount show that directly, instead of you inferring it from a screenshot. If it's an uncaught JS error the UI silently swallowed, getConsoleLogs surfaces it. Either way, you're fixing the actual cause instead of adding another Thread.sleep() and hoping.

Why this matters specifically for a Java/Selenium suite

This isn't a capability unique to browser automation in general — Playwright has had first-class network interception for a while, which is part of why Playwright suites are often less flaky than comparable Selenium ones. The gap has always been on the Java/Selenium side: the capability exists in Selenium 4, but almost nobody uses it because there was no lightweight way to reach for it mid-debugging-session. selenium-mcp doesn't add a new capability to Selenium — it makes the one that was already there, and mostly ignored, actually usable from an AI coding assistant, in the same Java toolchain your suite already runs on.

Full parameter details for every tool in this group are on the tool reference. If you're chasing a flaky test right now, waitForNetworkIdle is the one worth trying first — it's usually a straight swap for whatever Thread.sleep() you were about to write.

How to Get an AI Coding Assistant to Write a Correct Selenium Locator on the First Try

Volta Jebaprashanth — Sun, 09 Aug 2026 10:10:11 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that hands an AI coding agent a real Selenium WebDriver session — it opens Chrome, Firefox, or Edge, inspects the actual live page, and writes the Java locator itself instead of guessing from pasted HTML. Built specifically for test automation engineers working in Java, Selenium, and REST Assured, it also covers CDP network/console debugging and standalone REST API testing. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

Every Selenium engineer has written this line of debugging output at least once:

org.openqa.selenium.NoSuchElementException: no such element: Unable to locate element

or the meaner cousin — the locator does match something, just three of it, and your test clicked the wrong one. You fix it the same way every time: open DevTools, inspect the actual element, walk up the DOM until you find something unique about it, write the real selector, run the test again.

Now hand that same task to an AI coding assistant without giving it eyes on the page, and it does the only thing it can — it guesses from whatever HTML you pasted in, or from a locator pattern that looked right in a similar test elsewhere in your suite. Sometimes it's right. Often it isn't, and you're back to doing the DevTools inspection yourself and feeding the answer back into the chat.

This is the specific problem selenium-mcp exists to solve.

The tool that changes the workflow

It's called getPageElementsFiltered, part of the PageSourceTools group. Instead of finding just the first element that matches a locator, it finds every matching element on the live page and returns each as structured JSON, with three optional context flags:

includeAncestors — the full parent chain up to <html>, with every node annotated with siblingIndex and siblingCount. This is the piece that matters most: it's what lets the agent build a selector that's provably unique instead of one that merely looks specific.
includeSiblings — the other children of the same parent, useful when a locator needs to correlate a <label> with the <input> sitting next to it.
includeDescendants — expand a match's own children, for when you're locating a container rather than a leaf, like a table row you need to then query further.

The response reports totalMatches, returnedMatches, and truncated every time (results capped via limit, default 50), so the agent — and you, reading the tool call log — always know whether you're seeing the whole picture.

What this looks like in a real Page Object

Say you're writing a LoginPage class and the markup gives you nothing helpful — two <input> elements with no id, no name, generic classes shared across the form. This is the exact situation that used to mean tabbing over to the browser yourself.

Instead, point the agent at getPageElementsFiltered with locatorType=xpath, locatorValue=//input, includeAncestors=true. It gets back one JSON entry per <input> on the page, each with its ancestor path and sibling position. For the password field — second input inside the login form — the ancestor chain comes back annotated as siblingIndex: 1, siblingCount: 2 under form#login. From that, the agent writes:

private final By passwordField = By.cssSelector("div.container > form#login > input:nth-of-type(2)");

That selector is unique because the tool told the agent exactly how many sibling inputs exist and where this one sits — not because it looked plausible. It compiles into a working LoginPage method without a single round trip through your browser's DevTools.

The rest of the family

getPageElementsFiltered is what you reach for once you know what you're locating. Three other tools in the same group cover the steps before and around it:

getPageScripts — every <script> on the page as JSON (src for external, content for inline, truncated past 10,000 characters). Handy when you're trying to understand what a page's JS is actually doing before writing a wait condition against it.
getPageStyles — the same idea for stylesheets.
getPageElements — the whole page as a compact JSON tree rooted at <body>, scripts/styles/comments stripped, depth-capped via maxDepth (default 20). This is the "give me an overview" tool, for when you're starting a new Page Object and don't yet know the structure at all.

Why this matters for a test suite specifically, not just "an agent"

A generic browser-automation agent just needs a selector that works once. A test automation engineer needs one that keeps working — through refactors, through a designer swapping a <div> for a <section>, through a QA lead reviewing the PR and asking "why does this selector match three things." Getting the ancestor and sibling context up front, before a selector ever gets written into a By.cssSelector(...) call, is the difference between a Page Object you trust and one you'll be back in six months later, debugging the same NoSuchElementException all over again.

It's also just cheaper. A page with a few hundred DOM nodes routinely produces 30,000+ characters of raw HTML. Reading that into a prompt every time you need one locator is expensive in tokens and slow to iterate on. getPageElementsFiltered, scoped to exactly the elements you're locating, is a fraction of that size — and it comes with the disambiguating context a raw dump never gave you in the first place.

Full parameter list is on the tool reference; the repo has the source if you want to see how the ancestor walk is built (plain Selenium/JS underneath, nothing exotic).

Java and Selenium Test Engineers Have Been Left Out of the AI Coding Wave. Not Anymore.

Volta Jebaprashanth — Sat, 08 Aug 2026 11:41:23 +0000

Quick context: selenium-mcp is a Java-based Model Context Protocol server that gives AI coding assistants — Claude Code, Cursor, Claude Desktop — a real Selenium WebDriver session to drive Chrome, Firefox, or Edge directly, instead of guessing at locators from pasted HTML. It's built specifically for test automation engineers working in Java, Selenium, and REST Assured: structured element discovery for locators that are unique on the first try, Chrome DevTools Protocol tooling for network/console debugging, and a standalone REST client, all in one MCP server. Repo: github.com/Volta-Jebaprashanth/selenium-mcp · Docs: selenium-mcp.xpathy.uk

If you're a test automation engineer working in Java and Selenium, you've probably already tried pointing an AI coding assistant at your test suite. Claude Code, Cursor, Copilot — pick one. They're genuinely good at scaffolding a TestNG class, writing assertions, cleaning up a Page Object Model's structure.

Then you ask for the one thing you actually needed help with — "add a method to click the checkout button on this page" — and it stalls. It can't see the page. It doesn't know if that button is #checkout-btn, .checkout-button, or the third <button> inside a <div> with no id at all. So you do what you always did before AI showed up: open DevTools yourself, inspect the element, copy the selector, paste it back into the chat so the assistant can finish writing the method.

That's not AI-assisted test automation. That's you doing the automation part and the AI doing the typing.

I hit this wall enough times that I built a fix for it — open a browser, inspect the actual live page, find the element itself, then write the Java that clicks it. No more being the copy-paste bridge between DevTools and your chat window.

The gap this fills

The Node/Playwright ecosystem has had this figured out for a while. Playwright MCP lets an agent open a page and reason about it structurally instead of guessing from raw markup. If your team writes Playwright and TypeScript, you already have this.

If your team writes Java, Selenium, TestNG or JUnit, and REST Assured — which is still how most enterprise QA organizations are built, and isn't going anywhere soon — there's been nothing equivalent. I went looking before I built this, because duplicating an existing tool is a waste of everyone's time, and what I found were a handful of Selenium MCP servers, mostly in Node.js and Python, aimed at general browser-automation agents: booking a flight, scraping a page, filling out a form on someone's behalf. None of them are built around the actual day-to-day job of a test automation engineer — writing and maintaining a Java test suite, needing correct locators for a Page Object Model, needing API calls to seed and verify test data alongside the UI flow.

There's an even more direct signal that this gap is real: REST Assured's own GitHub repo has an open issue asking, essentially, "when do we get an MCP server for AI-driven API test automation?" As of writing, there isn't an official answer. The Java/Selenium/REST Assured ecosystem — the one a huge share of enterprise QA runs on — has been sitting outside the current wave of AI-assisted testing tooling almost entirely.

What selenium-mcp actually gives you

At its core, it's Selenium WebDriver exposed as MCP tools: open Chrome, Firefox, or Edge, navigate, click, type, read state — all through the same locator strategies (id, css, xpath, name, linkText, and so on) you already write by hand. Nothing exotic there. The part that actually changes your workflow is PageSourceTools, and specifically getPageElementsFiltered — a tool that finds every element matching a locator on the live page and hands back each one's ancestor chain and sibling position, so the agent can construct a selector that's unique on the first try instead of guessing and hitting NoSuchElementException against your test target. I'll go deep on exactly how that works, with a real Page Object example, in the next piece.

Past locator discovery, it covers the rest of what a real Selenium suite needs: explicit waits, alert and frame handling, window/tab management, cookies, screenshots, drag-and-drop, dropdown handling, file upload, PDF printing. It also exposes Selenium 4's Chrome DevTools Protocol support — network capture, request mocking/blocking, simulated network conditions, console log capture — useful for the kind of flaky-test diagnosis every automation engineer has lost an afternoon to. And because so much real test-suite work is API plus UI together, there's a standalone REST client built in, so an agent can help you write a REST Assured-style verification step and a Selenium UI step as part of the same test, without leaving your Java toolchain.

That's 112 tools across 16 categories at last count — full reference on the docs site.

Why it had to be Java

This is the question I get asked most, so let me be direct: because the people who need this don't want to leave Java. Rewriting a decade of Selenium suites in Playwright and TypeScript just to get an AI coding assistant that can see the page isn't a realistic option for most enterprise QA teams, and it shouldn't have to be. selenium-mcp ships as a single jar. Point Claude Code or Cursor at it alongside your existing Maven project, and the agent is driving the same WebDriver your suite already runs on — not a different automation stack bolted on next to it.

What's next

This is the first in a set of notes on the specific problems this solves for test automation engineers — locator discovery in depth, using the CDP network tools to debug flaky tests, combining REST Assured-style API checks with Selenium UI flows in one agent session, and the architecture decisions that keep the underlying Selenium layer usable on its own, independent of MCP, so it fits into a codebase you'd actually want to maintain.

If you want to try it now: quickstart on the docs site, grab the jar, point your MCP client at it, and ask it to write a Page Object method against a real page. It's MIT-licensed, and if something's rough, open an issue — that's genuinely the fastest way to make it better.

The AI-Native Frontier: Redefining the Future of Quality Engineering

Volta Jebaprashanth — Mon, 02 Mar 2026 06:33:23 +0000

Recently, within the AT + GSC&MS division at Sysco LABS, our Quality Engineering community gathered for an event that felt less like a standard technical conference and more like a bold step into a new reality. QE Spark 2026 was a resounding success — not just as a showcase of cutting-edge technology, but as a declaration of a new strategy designed to fundamentally change how we think about scale, growth, and the role of the modern engineer.

This transformative milestone wouldn’t have been possible without the two pillars of this event: Sujith Thushara, our Senior Manager Quality Engineering and Kasun de Silva, our Architect — Quality Engineering. It was their coordination, leadership, and forward-thinking vision that laid the groundwork for this strategic shift. As a speaker at QE Spark 2026, I was incredibly proud to help bring their vision to life on stage and share our roadmap with an energized, forward-looking community.

Sujith Thushara, Senior Manager Quality Engineering

Kasun de Silva, Architect — Quality Engineering

The Vision: Breaking the Linear Curve

For decades, the technology industry has operated under a predictable, yet limiting, law of physics: as business demand and revenue grow, headcount and operational costs must rise in parallel. This linear model is a hurdle to true innovation and velocity.

The core strategy we unveiled at QE Spark is the creation of a “Growth Delta.” By integrating intelligence into the very fabric of our delivery lifecycle, our goal is to empower business value to soar while keeping our operational footprint lean, agile, and efficient. We are successfully moving away from traditional, effort-based scaling and embracing intelligent growth.

The Journey: From AI-Assisted to AI-Native

A major highlight of the event was outlining our concrete roadmap. We aren’t just talking about the future; we are building it. The transition from legacy methods to an entirely AI-Native ecosystem is broken down into three distinct phases:

Traditional QE

The baseline. This phase is defined by human-driven quality, heavy manual validation, and reactive defect detection.

AI-Assisted QE

Our current state of the art. Here, AI tools actively enhance human effort. We are operating with an automation-first mindset, utilizing tool-enhanced test creation, and driving dramatically faster feedback cycles.

AI-Native QE

The true frontier. This future state moves far beyond mere “assistance” and into a world of Digital Twins, autonomous test evolution, and real-time quality intelligence. In this phase, AI isn’t just a tool; it is a predictive partner that identifies risks and evolves tests before a developer even pushes code.

A Mindset Shift: The Strategic Engineer

One of the most profound takeaways from QE Spark 2026 was that this transformation isn’t just about software — it’s about people. As we move aggressively toward an AI-Native world, the role of the engineer is getting a massive upgrade.

We are successfully breaking the “Regression Bottleneck,” where engineers historically spent half their time executing tests simply because those tests existed. Instead, the future Sysco Labs engineer is a systems thinker and a quality strategist. We are shifting from merely coordinating tests to reviewing intelligent decisions, architecting solutions, and validating complex business logic.

The Engine Room: A Collective Force of Builders

While the vision set on stage was ambitious, the most exciting part of this transformation is what is happening off stage. This isn’t just a top-down mandate; it is a grassroots revolution driven by our entire engineering team.

Our people are in the trenches right now, turning this AI-Native vision into a tangible reality. Across the floor, teams are deeply immersed in hands-on experimentation. We are spinning up rapid prototypes, stress-testing intelligent agents, and deploying cutting-edge Proofs of Concept that challenge the status quo of Quality Engineering. There is an electric culture of innovation taking hold, where every engineer is empowered to become a builder and a disruptor. We aren’t just waiting for the future of QE to arrive — we are actively coding it into existence today.

Looking Ahead

The overwhelming success of QE Spark 2026 was rooted in its clarity of purpose. By shifting from reactive detection to intelligent prevention, our team is actively clearing the path for a future where quality is a continuous, autonomous stream rather than a late-cycle hurdle.

As the event concluded, the atmosphere was electric. We are no longer just asking, “How can we test this?” We are asking, “How can we do this smarter?” The journey toward an AI-Native future at Sysco Labs has officially begun, and the results promise to redefine the very boundaries of Quality Engineering.

Tharushika Rathnayake, Sachini Karunarathne, Nuwanga Arambawela, Tharindu Dias, Dinithra Thantilage, Pasan Somarathna, Iresha Wijesinghe, Thanya Withanachchi, Shanaz Nabeel, Chiran Govinnage, Akila Rangalla, Mohamed Yaseen, Sujith Thushera, Kasun De Silva, Ruzaik Refai, Dineth Mendis, Volta Jebaprashanth.

Raw XPath is Dead: How XPathy's Fluent API Solves Your Flaky Test Problem

Volta Jebaprashanth — Fri, 17 Oct 2025 18:53:19 +0000

One of the most frequent causes of flaky tests is when a front-end change inadvertently alters the casing or spacing of an HTML attribute or text content. A CSS class might change from active to Active, or an error message might gain an extra space: " Error Message " vs. "Error Message". These minor variations are enough to break an exact-match XPath, leading to frustrating test failures.

XPathy's Value Transformation feature provides a fluent, built-in mechanism to address these issues. By applying transformations like case-folding and space-normalization before the locator comparison, XPathy ensures your locators match the intended value, regardless of the developer's formatting choices.

1. Achieving Case-Insensitive Matching

Raw XPath requires the complex use of the translate() function to achieve case-insensitivity. You must provide the entire alphabet twice: once for upper-case characters to replace, and once for the lower-case equivalents to replace them with.

Raw, Error-Prone XPath
`//div[contains(translate(@class, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), 'menu-item')]`

XPathy simplifies this into a single, declarative method call using the Case enum.

The `.withCase(IGNORED)` Method

The most common transformation is to ignore case for stable attributes like id or class.

import static com.xpathy.Case.*;

XPathy locator = div.byAttribute(class_)
                    .withCase(IGNORED)
                    .equals("active-tab");

// Result:
//div[translate(@class, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='active-tab']

This locator will successfully match elements with class="active-tab", class="Active-Tab", or class="ACTIVE-TAB". This small addition instantly makes the locator bulletproof against casing inconsistencies.

Force Casing (`UPPER` and `LOWER`)

You can also force the element's value to a specific case before comparison, which is helpful for standardizing text content:

XPathy locator = label.byText()
                    .withCase(UPPER)
                    .equals("USERNAME");

// Result:
//label[translate(text(), 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')='USERNAME']

This ensures the locator matches any variation of "Username," "username," or "USERNAME."

2. Whitespace and Symbol Cleanup

Inconsistent spacing in text nodes is a rampant source of locator flakiness. Similarly, needing to compare numeric values (like prices) often requires removing currency symbols.

Normalize Space with `.withNormalizeSpace()`

The XPath normalize-space() function strips leading and trailing whitespace and replaces sequences of internal whitespace with a single space. XPathy exposes this critical utility directly.

XPathy locator = div.byText()
                    .withNormalizeSpace()
                    .equals("Invalid password");

// Result:
//div[normalize-space(text())='Invalid password']

This locator will match text nodes that contain "Invalid password", " Invalid password ", or even "Invalid password".

Filtering Characters for Consistency

When dealing with dynamic content like prices or order IDs, you often only care about the alphanumeric parts. XPathy allows you to explicitly keep or remove sets of characters.

Scenario	XPathy Code	Function
Numeric Value Check	`span.byText().withRemoveOnly(SPECIAL_CHARACTERS).contains("1999")`	Removes `$` or `,` to stabilize price comparison.
ID Clean-up	`td.byText().withKeepOnly(ENGLISH_ALPHABETS, NUMBERS).equals("ORD123")`	Removes hyphens or spaces from Order IDs like `ORD-123` before checking.

These transformations allow you to focus on the meaningful data rather than the superficial presentation or formatting characters, making the locator invariant to regional currency or spacing differences.

3. Combining Transformations for Ultimate Resilience

The true power of XPathy lies in chaining these operations to clean up a value thoroughly before comparison.

Imagine a product title that might have inconsistent spacing, numbers (which should be ignored), and mixed casing.

XPathy locator = div.byText()
                    .withNormalizeSpace()
                    .withRemoveOnly(NUMBERS)
                    .withCase(IGNORED)
                    .contains("premium feature");

// Result:
//div[contains(translate(translate(normalize-space(text()), '0123456789', ''), 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), 'premium feature')]

By stacking .withNormalizeSpace(), .withRemoveOnly(), and .withCase(), the XPath is comprehensively cleaned up. The final result is a locator that will reliably find the element, regardless of how many formatting inconsistencies are introduced by the UI layer.

These fluent transformations are the key to building locators that are truly bulletproof against the casing, spacing, and formatting issues that plague Selenium test stability.

XPathy provides a lot more: Read the Full Documentation:

https://dev.to/volta_jebaprashanth_ac7af/xpathy-a-fluent-api-for-writing-smarter-cleaner-xpath-in-selenium-5753

The Repository:

https://github.com/Volta-Jebaprashanth/xpathy

Happy Testing! 🚀