feat(locator): terminal actions wait for presence and re-resolve on every poll by shossain786 · Pull Request #68 · seleniumboot/selenium-boot

shossain786 · 2026-09-20T05:42:11Z

What

Follow-up to #67. Applies the same pattern to every remaining Locator terminal action — type, append, getText, getAttribute, hover, scrollIntoView, jsClick, element() — through one shared whenReady() helper. click() moves onto it too.

Each poll: resolve from scratch → check ready → act. StaleElementReferenceException and "no element found" are retried until timeouts.explicit.

Behaviour change (needs a changelog line at release)

A locator that matches nothing is retried until timeouts.explicit instead of throwing immediately — this makes the "auto-wait" promise in the docs true for presence, not just visibility. It still ends in a LocatorException (message adds (waited Ns), cause is the TimeoutException), so existing catch (LocatorException) keeps working. Tests that expect an absent element to fail fast now fail after the timeout (10 s default).

Unchanged and non-waiting: isVisible(), isHidden(), isEnabled(), count(), elements().

rows() resolves the table through element() so it waits for the table; row/cell reads after that are not stale-proofed (out of scope).

Verification

mvn clean verify: 525 tests, 0 failures.
7 new tests in LocatorStaleElementTest; 6 of the 10 in that class failed on the previous code (stale between check and action, stale during wait, present-later, getText, type, append, jsClick).
Kept getAttribute returning null as a legitimate result (not retried) — covered by a test.
Compatibility: an existing test (rows_throwsLocatorException_whenTableIsNotFound) caught my first version throwing TimeoutException; fixed to keep LocatorException.
Consumer JUnit 5 suite (selenium-boot-test, real browser, uses Locator): 11/11 pass against a local build.
Docs: semantic-locators.md states the presence-wait and non-waiting methods.

🤖 Generated with Claude Code

…very poll Extends the click() stale-proofing (#67) to type, append, getText, getAttribute, hover, scrollIntoView, jsClick and element(), via one shared whenReady() helper. Behaviour change: a locator that matches nothing is now retried until timeouts.explicit instead of throwing immediately. It still ends in a LocatorException (cause: TimeoutException), so existing catches keep working. isVisible/isHidden/isEnabled/count still never wait. rows() resolves through element() and inherits the wait for the table itself. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Covers #66 (zero-config first run), #67/#68 (terminal Locator actions wait and re-resolve on every poll) and #64 (junit-jupiter-api 6.1.3). No version bump: the release decision is the maintainer's. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

BasePage already offers doubleClick/rightClick, but Locator did not, so users had to drop out of the Locator API for these gestures. Both methods perform the gesture with Selenium's Actions API and go through the existing terminal-action helpers, so they follow the same contract as click() and hover() (seleniumboot#67/seleniumboot#68): the element 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 gesture is performed is retried as well, rather than being treated as success. - doubleClick() waits for the element to be visible and enabled, like click(). - rightClick() waits for the element to be visible, like hover(). Each method has Javadoc with a usage example. Tests follow in the next commit. Refs seleniumboot#134

…eleniumboot#134) Add LocatorActionsTest, which checks that doubleClick() and rightClick() honour the same terminal-action contract as click() (seleniumboot#67/seleniumboot#68). The tests mock the driver as Interactive so the Actions sequences can be captured, and set timeouts.explicit to 1s to keep the timeout cases fast. Each pointer action is run through a shared data provider covering: - a ready element: the gesture is performed once on one lookup, and the element is never cleared or plain-clicked - an element that appears later: the locator re-resolves first - an element that is hidden at first: the action waits for it to become visible - an element that goes stale during the readiness check: a fresh element is resolved and used - an element that goes stale during the gesture: the gesture is retried on a freshly resolved element - an element that never appears: LocatorException with a TimeoutException cause, and no gesture is performed - an element that stays stale during the gesture: the action times out instead of reporting success - an element that never becomes visible: times out without acting A separate test checks that doubleClick() waits until the element is enabled. The successful cases also decode the captured gesture to check the target element, the number of press/release pairs (2 for doubleClick, 1 for rightClick) and the mouse button (left for doubleClick, right for rightClick). The data provider is shared so that the keyboard and focus actions can be added to the same matrix. Refs seleniumboot#134

BasePage already offers doubleClick/rightClick, but Locator did not, so users had to drop out of the Locator API for these gestures. Both methods perform the gesture with Selenium's Actions API and go through the existing terminal-action helpers, so they follow the same contract as click() and hover() (seleniumboot#67/seleniumboot#68): the element 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 gesture is performed is retried as well, rather than being treated as success. - doubleClick() waits for the element to be visible and enabled, like click(). - rightClick() waits for the element to be visible, like hover(). Each method has Javadoc with a usage example. Tests follow in the next commit. Refs seleniumboot#134

…eleniumboot#134) Add LocatorActionsTest, which checks that doubleClick() and rightClick() honour the same terminal-action contract as click() (seleniumboot#67/seleniumboot#68). The tests mock the driver as Interactive so the Actions sequences can be captured, and set timeouts.explicit to 1s to keep the timeout cases fast. Each pointer action is run through a shared data provider covering: - a ready element: the gesture is performed once on one lookup, and the element is never cleared or plain-clicked - an element that appears later: the locator re-resolves first - an element that is hidden at first: the action waits for it to become visible - an element that goes stale during the readiness check: a fresh element is resolved and used - an element that goes stale during the gesture: the gesture is retried on a freshly resolved element - an element that never appears: LocatorException with a TimeoutException cause, and no gesture is performed - an element that stays stale during the gesture: the action times out instead of reporting success - an element that never becomes visible: times out without acting A separate test checks that doubleClick() waits until the element is enabled. The successful cases also decode the captured gesture to check the target element, the number of press/release pairs (2 for doubleClick, 1 for rightClick) and the mouse button (left for doubleClick, right for rightClick). The data provider is shared so that the keyboard and focus actions can be added to the same matrix. Refs seleniumboot#134

BasePage already offers doubleClick/rightClick, but Locator did not, so users had to drop out of the Locator API for these gestures. Both methods perform the gesture with Selenium's Actions API and go through the existing terminal-action helpers, so they follow the same contract as click() and hover() (seleniumboot#67/seleniumboot#68): the element 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 gesture is performed is retried as well, rather than being treated as success. - doubleClick() waits for the element to be visible and enabled, like click(). - rightClick() waits for the element to be visible, like hover(). Each method has Javadoc with a usage example. Tests follow in the next commit. Refs seleniumboot#134

…eleniumboot#134) Add LocatorActionsTest, which checks that doubleClick() and rightClick() honour the same terminal-action contract as click() (seleniumboot#67/seleniumboot#68). The tests mock the driver as Interactive so the Actions sequences can be captured, and set timeouts.explicit to 1s to keep the timeout cases fast. Each pointer action is run through a shared data provider covering: - a ready element: the gesture is performed once on one lookup, and the element is never cleared or plain-clicked - an element that appears later: the locator re-resolves first - an element that is hidden at first: the action waits for it to become visible - an element that goes stale during the readiness check: a fresh element is resolved and used - an element that goes stale during the gesture: the gesture is retried on a freshly resolved element - an element that never appears: LocatorException with a TimeoutException cause, and no gesture is performed - an element that stays stale during the gesture: the action times out instead of reporting success - an element that never becomes visible: times out without acting A separate test checks that doubleClick() waits until the element is enabled. The successful cases also decode the captured gesture to check the target element, the number of press/release pairs (2 for doubleClick, 1 for rightClick) and the mouse button (left for doubleClick, right for rightClick). The data provider is shared so that the keyboard and focus actions can be added to the same matrix. Refs seleniumboot#134

BasePage already offers doubleClick/rightClick, but Locator did not, so users had to drop out of the Locator API for these gestures. Both methods perform the gesture with Selenium's Actions API and go through the existing terminal-action helpers, so they follow the same contract as click() and hover() (seleniumboot#67/seleniumboot#68): the element 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 gesture is performed is retried as well, rather than being treated as success. - doubleClick() waits for the element to be visible and enabled, like click(). - rightClick() waits for the element to be visible, like hover(). Each method has Javadoc with a usage example. Tests follow in the next commit. Refs seleniumboot#134

…eleniumboot#134) Add LocatorActionsTest, which checks that doubleClick() and rightClick() honour the same terminal-action contract as click() (seleniumboot#67/seleniumboot#68). The tests mock the driver as Interactive so the Actions sequences can be captured, and set timeouts.explicit to 1s to keep the timeout cases fast. Each pointer action is run through a shared data provider covering: - a ready element: the gesture is performed once on one lookup, and the element is never cleared or plain-clicked - an element that appears later: the locator re-resolves first - an element that is hidden at first: the action waits for it to become visible - an element that goes stale during the readiness check: a fresh element is resolved and used - an element that goes stale during the gesture: the gesture is retried on a freshly resolved element - an element that never appears: LocatorException with a TimeoutException cause, and no gesture is performed - an element that stays stale during the gesture: the action times out instead of reporting success - an element that never becomes visible: times out without acting A separate test checks that doubleClick() waits until the element is enabled. The successful cases also decode the captured gesture to check the target element, the number of press/release pairs (2 for doubleClick, 1 for rightClick) and the mouse button (left for doubleClick, right for rightClick). The data provider is shared so that the keyboard and focus actions can be added to the same matrix. Refs seleniumboot#134

) * feat(locator): add doubleClick() and rightClick() (#134) BasePage already offers doubleClick/rightClick, but Locator did not, so users had to drop out of the Locator API for these gestures. Both methods perform the gesture with Selenium's Actions API and go through the existing terminal-action helpers, so they follow the same contract as click() and hover() (#67/#68): the element 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 gesture is performed is retried as well, rather than being treated as success. - doubleClick() waits for the element to be visible and enabled, like click(). - rightClick() waits for the element to be visible, like hover(). Each method has Javadoc with a usage example. Tests follow in the next commit. Refs #134 * test(locator): pointer actions follow the terminal-action contract (#134) Add LocatorActionsTest, which checks that doubleClick() and rightClick() honour the same terminal-action contract as click() (#67/#68). The tests mock the driver as Interactive so the Actions sequences can be captured, and set timeouts.explicit to 1s to keep the timeout cases fast. Each pointer action is run through a shared data provider covering: - a ready element: the gesture is performed once on one lookup, and the element is never cleared or plain-clicked - an element that appears later: the locator re-resolves first - an element that is hidden at first: the action waits for it to become visible - an element that goes stale during the readiness check: a fresh element is resolved and used - an element that goes stale during the gesture: the gesture is retried on a freshly resolved element - an element that never appears: LocatorException with a TimeoutException cause, and no gesture is performed - an element that stays stale during the gesture: the action times out instead of reporting success - an element that never becomes visible: times out without acting A separate test checks that doubleClick() waits until the element is enabled. The successful cases also decode the captured gesture to check the target element, the number of press/release pairs (2 for doubleClick, 1 for rightClick) and the mouse button (left for doubleClick, right for rightClick). The data provider is shared so that the keyboard and focus actions can be added to the same matrix. Refs #134 * feat(locator): add press(Keys...) and focus() (#134) * test(locator): cover press and focus (#134) * docs(locator): document locator actions (#134) --------- Co-authored-by: Xi Hu <u8183004@anu.edu.au>

shossain786 merged commit 685e22d into master Sep 20, 2026
2 checks passed

shossain786 deleted the feat/locator-auto-wait-all-actions branch September 20, 2026 08:48

shossain786 mentioned this pull request Sep 21, 2026

docs(changelog): draft v3.5.0 entry (unreleased) #69

Merged

shossain786 mentioned this pull request Sep 27, 2026

feat: waitForNetworkIdle / waitForResponse (CDP + BiDi) #85

Merged

This was referenced Oct 10, 2026

feat(locator): add first() and last() narrowing methods (#132) #143

Merged

feat(locator): form actions: clear, check, uncheck, isChecked, select… #147

Merged

feat(locator): waitFor, allTextContents, element screenshot (#135) #150

Merged

shossain786 mentioned this pull request Oct 13, 2026

feat: add focused empty and regex assertions (#136) #151

Closed

crystalmountain666 mentioned this pull request Oct 19, 2026

[internal] feat(locator): doubleClick() and rightClick() for #134 TONGdamy/selenium-boot#1

Merged

crystalmountain666 mentioned this pull request Oct 20, 2026

[Group review] feat(locator): press, focus, doubleClick, rightClick TONGdamy/selenium-boot#3

Open

6 of 10 tasks

TONGdamy mentioned this pull request Oct 21, 2026

feat(locator): add press, focus, doubleClick and rightClick (#134) #188

Merged

7 of 10 tasks

Navigation Menu

Repository navigation

feat(locator): terminal actions wait for presence and re-resolve on every poll - #68

feat(locator): terminal actions wait for presence and re-resolve on every poll#68
shossain786 merged 1 commit into
masterfrom
feat/locator-auto-wait-all-actions

shossain786 commented Sep 20, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

shossain786 commented Sep 20, 2026

What

Behaviour change (needs a changelog line at release)

Verification

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant