Selenium has announced a small-looking Java API change with a clear compatibility consequence. Starting with the planned Selenium 4.51 release, ExpectedCondition<T> is intended to stop implementing Guava's com.google.common.base.Function<WebDriver, T> and continue with the JDK's java.util.function.Function<WebDriver, T>.
This is not a reason to panic or upgrade to an artifact that is not yet available. It is an opportunity to identify dependency coupling before the change reaches a normal upgrade pull request.
1. What Selenium has confirmed
The official Selenium announcement distinguishes affected and unaffected usage:
| Usage pattern | Expected impact |
|---|---|
Pass an ExpectedConditions factory result directly to WebDriverWait.until(...) | Not affected |
Implement an ExpectedCondition with a lambda | Not affected |
Store or expose an ExpectedCondition through a Guava Function type | Compile-time incompatibility after the interface is removed |
Use Guava elsewhere without connecting it to Selenium's ExpectedCondition | Outside the scope of this specific change |
At the time of the announcement, the change was targeted for Selenium 4.51 and was not shipping immediately. Treat the version as a planned boundary until an official release artifact and release notes are available.
The current Java API documentation is also useful as a baseline: it shows ExpectedCondition extending both the Guava and JDK functional interfaces. That baseline gives teams something concrete to compare with the future API.
2. Find the real compatibility boundary
Searching the dependency tree for Guava is not enough. A project may legitimately use Guava for unrelated features and still be unaffected. The relevant question is whether Selenium conditions cross a type boundary declared as com.google.common.base.Function.
Start with a narrow code search:
git grep -n "com.google.common.base.Function"
git grep -n "ExpectedCondition\|ExpectedConditions"Review matches in these locations:
- fields that store reusable conditions;
- helper methods that accept or return a functional type;
- test-framework wrappers around
WebDriverWait; - shared libraries consumed by several test repositories;
- extension points exposed to other teams;
- compiled third-party helpers that may expose Guava types in their public signatures.
Record each match with its owner, consumers, and proposed migration. This boundary map is more useful than a raw dependency list because it shows where a source-compatible edit could become a downstream breaking change.
3. Use the smallest safe type change
The official migration direction is straightforward.
Before:
com.google.common.base.Function<WebDriver, WebElement> condition =
ExpectedConditions.elementToBeClickable(By.id("submit"));After:
java.util.function.Function<WebDriver, WebElement> condition =
ExpectedConditions.elementToBeClickable(By.id("submit"));When the value is Selenium-specific, a more expressive option is:
ExpectedCondition<WebElement> condition =
ExpectedConditions.elementToBeClickable(By.id("submit"));For a short local variable, type inference may remove unnecessary coupling:
var condition = ExpectedConditions.elementToBeClickable(By.id("submit"));Do not introduce unchecked adapters merely to preserve the old type. If a public library exposes Guava Function, changing that signature needs normal compatibility planning for its consumers.
4. Prepare before the release without pretending to test it
Before an official compatible artifact exists, teams can complete useful preparation:
- classify every Selenium-related Guava
Functionreference; - refactor private implementation details where the intent is already clear;
- identify public APIs that need consumer coordination;
- add tests around custom wait wrappers and failure behavior;
- document the current known-good Selenium version;
- define the evidence required for the future upgrade.
Do not create a deliberately uncompilable test and exclude it from normal builds. That proves little. The valuable check is compiling the real production and test source sets against the future official artifact.
A long-lived upgrade branch can also become stale. Prefer a short-lived controlled upgrade branch once the release is available, while keeping the inventory and test plan ready in advance.
5. Risk-based verification plan
When an official Selenium version containing the change is available, run the upgrade through layers:
| Risk | Evidence |
|---|---|
| Direct Guava typing prevents compilation | Clean compile of all production, test, fixture, and helper source sets |
| Shared wrapper API breaks consumers | Consumer contract tests or builds of representative downstream projects |
| Custom waits behave differently after refactoring | Focused tests for success, timeout, ignored exceptions, and returned values |
| Dependency resolution changes unexpectedly | Before/after dependency-tree comparison and convergence checks |
| CI passes while an important path is untested | Representative browser smoke tests followed by the normal regression suite |
| Packaged framework still exposes an old signature | Public API or bytecode compatibility report for the built artifact |
The announced interface removal is primarily a compile-time risk. Runtime checks remain valuable because teams may refactor wrappers while fixing compilation, but Selenium's announcement does not itself claim a change to wait timing or exception behavior.
6. CI canary for the actual upgrade
Create a separate upgrade job or temporary branch when the official artifact exists:
- update only the Selenium dependency and the required type fixes;
- perform a clean build with dependency caches controlled;
- compile every relevant source set, not only the main module;
- run focused custom-wait and wrapper tests;
- run a small browser smoke set in a stable environment;
- publish compiler output, dependency reports, and test results as evidence;
- start the full regression suite only after the earlier gates pass.
A canary is most useful when it tests the same build files, Java version, runner image, and shared libraries used by the normal pipeline. A green application test suite from the old dependency is not evidence that the new dependency is compatible.
7. Protect downstream consumers
Internal test frameworks often turn a small upstream change into a larger migration. If a shared method currently returns Guava Function, find its consumers before changing the signature.
For each public boundary, decide whether to:
- release a coordinated breaking version;
- add a new JDK-typed method and deprecate the old method for a defined transition;
- keep the Selenium-specific
ExpectedConditiontype in the contract; - update all controlled consumers in the same change window.
The correct choice depends on ownership and release policy. The key QA requirement is to test the consumer contract rather than only the framework repository.
8. Forward fix and rollback
The durable fix is to remove Selenium-related reliance on the Guava functional interface. Prefer the JDK type, the Selenium-specific type, or local type inference according to the API's intent.
Rollback should be equally explicit. Keep the exact current known-good Selenium version recorded before the upgrade. If the new version causes an unresolved problem, restore that exact version and the matching source changes, then run the clean build and smoke checks again. Avoid an open version range as a safety mechanism: it can select a newer artifact without a deliberate review.
Rollback is temporary risk control, not a substitute for completing the migration.
9. Pre-merge checklist
- All Selenium-related Guava
Functionreferences are inventoried. - Public and private type boundaries are classified separately.
- The upgrade uses an official released artifact.
- Production, test, fixture, and helper source sets compile cleanly.
- Representative downstream consumers are verified.
- Custom wait success and failure paths are tested.
- Dependency resolution is compared before and after the upgrade.
- Browser smoke tests and the required regression scope pass.
- CI evidence is retained with the pull request.
- The exact rollback version and owner are documented.
- Review follows the team's normal approval policy.
10. Five reviewer questions
- Which code paths still connect
ExpectedConditionto GuavaFunction? - Did we test public consumers, or only the repository that owns the wrapper?
- Does the CI job compile every source set that can contain Selenium helpers?
- Which runtime tests cover code changed during the type migration?
- Can we restore the exact known-good dependency and verify the rollback in one controlled run?
11. Where automation helps
Static searches make the initial inventory repeatable. Dependency reports expose transitive changes. CI compilation finds deterministic incompatibilities, and contract tests reveal broken consumers. Browser smoke tests then check the behavior of the refactored wait helpers.
Automation cannot decide whether a public API change is acceptable, which consumers require coordination, or whether the collected evidence is sufficient for the release. Those remain human review decisions.
Conclusion
The planned Selenium 4.51 ExpectedCondition change is narrow, but it illustrates a broader QA lesson: dependency upgrades must test public type boundaries, not only runtime scenarios. An accurate inventory, a controlled upgrade branch, layered CI evidence, and an exact rollback target let teams fix the coupling before it blocks delivery.
Leave a comment
Share your thoughts about the article. No account is required.
Comments
Loading comments…