Skip to content

[java] JSpecify annotations for org.openqa.selenium.interactions #16462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 2 commits into from
Oct 20, 2025
Merged

[java] JSpecify annotations for org.openqa.selenium.interactions #16462

merged 2 commits into from
Oct 20, 2025
+14 −3

Conversation

@mk868
Copy link
Contributor

@mk868 mk868 commented Oct 18, 2025 •
edited by qodo-merge-pro bot
Loading

User description

🔗 Related Issues

Related #14291

💥 What does this PR do?

JSpecify annotations added to the:

  • org.openqa.selenium.interactions.CompositeAction
  • org.openqa.selenium.interactions.Interaction
  • org.openqa.selenium.interactions.Locatable
  • org.openqa.selenium.interactions.MoveTargetOutOfBoundsException

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

  • New feature (non-breaking change which adds functionality and tests!)

PR Type

Enhancement

Description

  • Add JSpecify @NullMarked annotations to interactions package classes

  • Mark nullable parameters in MoveTargetOutOfBoundsException constructors

  • Improve null-safety documentation for CompositeAction, Interaction, Locatable

  • Enable compile-time null-safety checking for interactions API

Diagram Walkthrough

flowchart LR
  A["Interactions Package Classes"] -->|"Add @NullMarked"| B["CompositeAction"]
  A -->|"Add @NullMarked"| C["Interaction"]
  A -->|"Add @NullMarked"| D["Locatable"]
  A -->|"Add @NullMarked + @Nullable params"| E["MoveTargetOutOfBoundsException"]
  B --> F["Null-safety Annotations Applied"]
  C --> F
  D --> F
  E --> F
Loading

File Walkthrough
Relevant files
Enhancement
CompositeAction.java
Add JSpecify @NullMarked annotation to CompositeAction     

java/src/org/openqa/selenium/interactions/CompositeAction.java

  • Added @NullMarked annotation import from org.jspecify.annotations
  • Applied @NullMarked class-level annotation to CompositeAction
  • Enables null-safety checking for the composite action aggregator
 +2/-0     
Interaction.java
Add JSpecify @NullMarked annotation to Interaction             

java/src/org/openqa/selenium/interactions/Interaction.java

  • Added @NullMarked annotation import from org.jspecify.annotations
  • Applied @NullMarked class-level annotation to abstract Interaction
    class
  • Marks all methods and fields as non-null by default
 +3/-0     
Locatable.java
Add JSpecify @NullMarked annotation to Locatable interface

java/src/org/openqa/selenium/interactions/Locatable.java

  • Added @NullMarked annotation import from org.jspecify.annotations
  • Applied @NullMarked interface-level annotation to Locatable
  • Establishes null-safety contract for coordinate retrieval
 +3/-0     
MoveTargetOutOfBoundsException.java
Add JSpecify annotations with nullable parameters to exception

java/src/org/openqa/selenium/interactions/MoveTargetOutOfBoundsException.java

  • Added imports for @NullMarked and @Nullable annotations
  • Applied @NullMarked class-level annotation
  • Marked String message and Throwable cause parameters as @Nullable in
    all three constructors
  • Explicitly documents that exception constructors accept null arguments
 +6/-3     

@selenium-ci selenium-ci added the C-java Java Bindings label Oct 18, 2025
@qodo-merge-pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 18, 2025 •
edited
Loading

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪
Nullable exception args

Description: Marking both constructors' String message and Throwable cause as @nullable may propagate
null messages/causes, potentially reducing diagnostic information and complicating error
handling where non-null messages are expected; verify consumers tolerate nulls.
MoveTargetOutOfBoundsException.java [29-40]

Referred Code 
public class MoveTargetOutOfBoundsException extends WebDriverException {
  public MoveTargetOutOfBoundsException(@Nullable String message) {
    super(message);
  }

  public MoveTargetOutOfBoundsException(@Nullable Throwable cause) {
    super(cause);
  }

  public MoveTargetOutOfBoundsException(@Nullable String message, @Nullable Throwable cause) {
    super(message, cause);
  }
Ticket Compliance
🟡
🎫 #14291
🟢 Add JSpecify Nullness annotations to Selenium framework code to indicate nullable
parameters and return values.
Prefer annotations over JavaDoc so IDEs and static analyzers can surface nullability
issues.
Improve interoperability with Kotlin via explicit nullness annotations.
🔴 Example usage suggests marking nullable methods/params with @nullable and adopting
package/class-level annotations as appropriate.
Codebase Duplication Compliance
⚪
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
⚪
No custom compliance provided

Follow the guide to enable custom compliance check.

  • Update
Compliance status legend 🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

@qodo-merge-pro
Copy link
Contributor

qodo-merge-pro bot commented Oct 18, 2025 •
edited
Loading

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
Learned
best practice
Clarify constructor nullability in Javadoc

Ensure nullability annotations match the superclass API and document the
nullability behavior in Javadoc. Add brief Javadoc to each constructor
clarifying that null messages/causes are allowed.

java/src/org/openqa/selenium/interactions/MoveTargetOutOfBoundsException.java [28-41]

+/**
+ * Indicates that the target provided to the actions move() method is invalid - outside of the size
+ * of the window.
+ */
 @NullMarked
 public class MoveTargetOutOfBoundsException extends WebDriverException {
+  /**
+   * Creates the exception with an optional detail message; a null message is allowed.
+   */
   public MoveTargetOutOfBoundsException(@Nullable String message) {
     super(message);
   }
 
+  /**
+   * Creates the exception with an optional cause; a null cause is allowed.
+   */
   public MoveTargetOutOfBoundsException(@Nullable Throwable cause) {
     super(cause);
   }
 
+  /**
+   * Creates the exception with optional message and cause; null values are allowed.
+   */
   public MoveTargetOutOfBoundsException(@Nullable String message, @Nullable Throwable cause) {
     super(message, cause);
   }
 }
  • Apply / Chat
Suggestion importance[1-10]: 6

__

Why:
Relevant best practice - Keep API and documentation accurate and consistent by aligning annotations with superclass contracts and documenting nullability intent.

Low
  • Update

@mk868 mk868 force-pushed the jspecify-interactions branch 2 times, most recently from be56861 to f2b7a59 Compare October 18, 2025 12:42
@mk868 mk868 force-pushed the jspecify-interactions branch from f2b7a59 to 91a55a5 Compare October 19, 2025 17:17
@diemol diemol merged commit 13b63f6 into SeleniumHQ:trunk Oct 20, 2025
38 checks passed
@mk868 mk868 deleted the jspecify-interactions branch October 20, 2025 11:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

C-java Java Bindings Review effort 2/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@mk868 @selenium-ci @diemol