[🚀 Feature]: JSpecify Nullness annotations for Java

[mk868]

Feature and motivation

I suggest adding JSpecify Nullness annotations to the Selenium framework code. These annotations allow you to specify which parameters and return values can be null. I'm aware that information about potential null values are already placed in the JavaDoc, but using annotations will be transparent to IDEs and static code analyzers. This will give developers better exposure of potential problems with their code in order to avoid NullPointerExceptions.

Using annotations will also improve interoperability with Kotlin.

Links:

• https://jspecify.dev/
• https://github.com/jspecify/jspecify

Usage example

The annotated method would look like this:

// ...

import org.jspecify.annotations.Nullable;

public interface WebElement extends SearchContext, TakesScreenshot {
// ...

@Nullable String getAttribute(String name);

// ...
}

Then the IDE/static code analyzer will display a warning about unsafe code:

var element = webDriver.findElement(By.tagName("img"));
var cssClasses = element.getAttribute("class").split(" "); // warning here, possible NullPointerException

[github-actions[bot]]

@mk868, thank you for creating this issue. We will troubleshoot it as soon as we can.

---

Info for maintainers

Triage this issue by using labels.

If information is missing, add a helpful comment and then I-issue-template label.

If the issue is a question, add the I-question label.

If the issue is valid but there is no time to troubleshoot it, consider adding the help wanted label.

If the issue requires changes or fixes from an external project (e.g., ChromeDriver, GeckoDriver, MSEdgeDriver, W3C), add the applicable G-* label, and it will provide the correct link and auto-close the issue.

After troubleshooting the issue, please add the R-awaiting answer label.

Thank you!

[github-actions[bot]]

This issue is looking for contributors.

Please comment below or reach out to us through our IRC/Slack/Matrix channels if you are interested.

[mk868]

I can contribute to add these annotations. Can I just create a Pull Request with changes? Or Is additional analysis/confirmation needed for this feature by the Selenium team?

[diemol]

@mk868, yes, please. Focus on small PRs so they can be quickly reviewed and merged. It does not matter if you send many PRs. A PR with 2-3 files changed will be merged rather quickly, but a PR with 20 files changed will take several days.

[github-actions[bot]]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[mk868]

The task is still valid

[iampopovich]

@diemol Since the task is closed as completed: Will newly added Nullable annotations still be considered in PRs?

I noticed internal null checks in class methods, but class fields lack Nullable markers. While not critical, adding annotations would better enforce class contracts. (Not insisting if changes are unwarranted.)

[diemol]

It got closed automatically after merging the PR.

[iampopovich]

@diemol, sorry for a couple of similar PRs. They contain a lot of boilerplate for adding annotations to exception classes. For such trivial changes, is it better to submit them as several small pull requests or one large one?

[iampopovich]

There are quite a lot of classes left without annotations. Should I send larger batches of changes for review? Or are changes of 1-2 classes acceptable for a quick review?

[diemol]

1-2 classes is better