Breaking changes in Selenium

If you are in the business of creating Quality Software, every day can throw up a surprise or two. How one overcomes these day-to-day challenges often defines the course of your success. Here’s one such challenge we recently faced, we thought of sharing with you. We would love to hear your feedback.

During the regression phase of a particular product update release, our QA team reported an issue that all the mouse actions (MouseHover, MouseUp, MouseDown) were not working with the Selenium version 3.6+

We investigated the issue and figured that inside mouse actions (in the Qualitia engine code), we use Locatable APIs. We found that these Locatable API had recently been refactored (as well as deprecated) by Selenium community in SE 3.6+ and the community recommended to use Actions API which they supported since SE 3.0+.

Though the challenge henceforth was going to be maintaining backward compatibility with Selenium versions in Qualitia (at least post SE 3.0), any of the above changes would be simple if we didn’t care about backward compatibility. But then ideally we have users using various Se 3.x versions, hence, we had to fix this issue in Qualitia 5.0 in a manner which works across all the Se 3.x versions.

We also figured that Locatable is a primitive way of accessing mouse actions so the community forced to move to Actions API and hence, they didn’t care refactoring them, which caused breaking changes. After brainstorming, we could come up with a few approaches as solutions for this issue:

Potential Solution 1: The obvious solution was to replace Locatable package statements with new package structure statements (which SE 3.6 had introduced) and compile the code with Selenium 3.6. The code would have successfully compiled but would have thrown the runtime exception for those mouse actions (since Java wouldn’t find the package structure in earlier versions which is meant for SE 3.6). So we dropped this solution.

Potential Solution 2: Use Locatable APIs and write code to handle Mouse actions in Selenium version in an agnostic way. The idea was if mouse actions fail at runtime (due to unexpected package import) catch that Exception (which means the user must be using pre-SE 3.6 version) and explicitly call the Pre SE 3.6 package structure (i.e. older fully qualified Locatable package to invoke Mouse actions on Pre SE 3.6).

The pseudo would look something as follows:



//SE 3.6 handling

Locatable driver = (Locatable) webDriver;

Mouse mouse = driver.getMouse();;


catch(RunTimeException e)


//SE 3.6- handling

com.newstructure.Locatable = (com.newstructure.Locatable) webDriver

Mouse mouse = driver.getMouse();;


But this Selenium version specific exception based code and using deprecated Locatable didn’t seem to be clean and promising way. Hence we finalized on the next approach – Solution 3.

Solution 3: Use Actions API – since Actions API is supported post 3.0+, it was very safe to use them. Moreover, SE community also recommends to use them over a primitive way of using Locatable mouse action. In this way, we achieved backward comparability. There was almost no impact on the user since for him, Qualitia mouse action name and parameters remained the same (although technically parameter got ignored in the latest API that doesn’t break anything for user hence, we ignored that to go ahead with the current release).

The takeaway from this process while on this issue (since the SE community would keep on adding breaking changes and introducing new APIs), we should strive to keep our code future proof and backward compatible as much as possible.

Writing Quality Software is a tough job! Especially so when the environment surrounding you is constantly evolving.

Written by Qualitia Software