[crystalmountain666]

Internal group review before opening the PR to seleniumboot/selenium-boot. Please approve or leave comments. This PR should not be merged into master, so that master stays in sync with upstream.

The branch is rebased onto the current upstream master and contains the five commits already reviewed in the internal PRs #1 (pointer actions) and #2 (keyboard actions and docs). The draft upstream PR description is below.

@May-Mei6 @Lisr-iiil could you review this when you have time? Thanks!

---

What & why

Locator had no doubleClick(), rightClick(), focus() or press(Keys...), so tests had to drop back to BasePage or raw WebDriver for these interactions. This PR adds all four so the Locator API is the only place users need to look.

All four are terminal actions and follow the contract from seleniumboot#67/seleniumboot#68: the locator is re-resolved from scratch on every poll, and stale or not-yet-present elements are retried until timeouts.explicit. A StaleElementReferenceException thrown while the action is performed is retried as well, so a stale reference is never treated as success.

• doubleClick() waits for the element to be visible and enabled, like click() and BasePage.doubleClick().
• rightClick() waits for the element to be visible, like hover() and BasePage.rightClick().
• press(Keys...) sends the keys to the element without clearing it.
• focus() moves focus to the element with JavaScript.

Closes seleniumboot#134.

Type of change

• Bug fix
• New feature (opt-in, aligned with the framework philosophy)
• Documentation
• Internal refactor / test coverage

Checklist

• All existing tests pass (mvn clean verify) (see Verification)
• New behaviour is covered by unit tests
• No new external dependencies introduced without prior discussion
• Code follows existing conventions (no new frameworks, minimal abstraction)
• No breaking changes to @SeleniumBootApi public APIs (or a major version bump is justified below)
• Docs updated if user-facing behaviour changed (docs-site/)

Notes for reviewers

Commits. The change is split into five commits: doubleClick()/rightClick(), their tests, press(Keys...)/focus(), their tests, and the docs (changelog entry in docs-site/docs/changelog.md and one line in the locators guide).

Tests. The new LocatorActionsTest runs all four actions through a shared data provider covering eight scenarios: a ready element, an element that appears later, an element that is hidden at first, staleness during the readiness check, staleness during the action, an element that never appears, an element that stays stale (must time out instead of succeeding), and an element that never becomes visible. A separate test checks that doubleClick() waits until the element is enabled. For the pointer actions, the tests also decode the captured gesture to check the target element, the number of press/release pairs and the mouse button. The tests are in their own file, following LocatorDragToTest.

Verification. mvn clean verify on the rebased branch (macOS, IntelliJ): [TOTAL] tests, [FAILURES] failures. [Describe the failures here, or delete this sentence if there are none.] All LocatorActionsTest tests pass.

Co-authored by @crystalmountain666 and @TONGdamy.

[May-Mei6]

Thanks @crystalmountain666 and @TONGdamy, this looks good. The diff only touches the files the issue needs. doubleClick(), rightClick(), press() and focus() are added to Locator.java with Javadoc and a dedicated test class. The related documentation is updated, and the description follows the upstream template.

Happy to approve. Just make sure the Verification section is filled in with the test numbers before opening the upstream PR.

Minor note: could remove the Closes seleniumboot#134 line from this internal PR's description, so it doesn't show up as linked on the upstream issue. It should stay in the description we post upstream.

[Lisr-iiil]

Thanks for putting this together. I reviewed the implementation, unit tests, Javadoc, and documentation against seleniumboot#134 and the maintainer’s guidance.

The four methods follow the existing terminal-action contract through whenReady() / whenVisible(): the element is resolved again on every poll, and missing or stale elements are retried until timeouts.explicit. Action execution remains inside the retry loop, so staleness during the action is also retried.

The tests cover eight scenarios for each action, plus the enabled-state check for doubleClick(). The cases for staleness during an action and persistent staleness address the maintainer’s concern about stale references being treated as success. The pointer tests also check the target element, mouse button, and click count. The Javadoc, guide, and changelog are consistent with the implementation.

This review is based on inspecting the code, tests, and documentation. I have not independently run the test suite or performed local browser verification.

I have two questions about the verification notes:

1. Issue seleniumboot#134 mentions a real-page case in the sample project if browser testing is needed. The mock tests check the retry logic and action construction, but actual focus changes, keyboard behaviour, and mouse events depend on the browser. Could you clarify whether a real-page case was also run and include its assertions and results?
2. CONTRIBUTING.md describes running the official consumer project against the local framework build. Could you confirm whether this was completed and add the results to the notes?

I couldn’t find these details in the current description, so I’m asking for clarification rather than assuming the checks haven’t been done.

This internal PR should remain unmerged as requested.