[js] Normalize empty custom locator results

[munawiki]

🔗 Related Issues

Fixes #16671

💥 What does this PR do?

Normalizes the no-match behavior of custom locators in the JavaScript binding:

• findElement() now throws NoSuchElementError when a custom locator returns an empty array.
• findElements() now returns an empty array when a custom locator throws NoSuchElementError.
• Other errors from custom locators continue to propagate.

🔧 Implementation Notes

The normalization lives in the existing shared custom-locator helpers, so the behavior is consistent for WebDriver, WebElement, and ShadowRoot search contexts. Regression tests cover both no-match paths and verify that unexpected errors are not swallowed.

✅ Verification

• bazel test //javascript/selenium-webdriver:small-tests --cache_test_results=no
• bazel test //javascript/selenium-webdriver:prettier-test //javascript/selenium-webdriver:bidi-schema-tests --cache_test_results=no
• Chrome and Firefox element-finding integration targets passed in the full JavaScript test run.

The full bazel test //javascript/selenium-webdriver:all run completed with 136 of 142 targets passing. The six local failures were in unchanged ESLint configuration and unrelated browser integration targets.

🤖 AI assistance

• No substantial AI assistance used
• AI assisted (complete below)
  • Tool(s): OpenAI Codex
  • What was generated: Initial implementation and regression tests
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

None.

🔄 Types of changes

• Bug fix (backwards compatible)

[CLAassistant]

All committers have signed the CLA.

[qodo-code-review]

PR Summary by Qodo

[js] Normalize no-match behavior for custom locators

🐞 Bug fix 🧪 Tests 🕐 10-20 Minutes

AI Description

• Make findElement() throw NoSuchElementError when custom locators return [].
• Make findElements() return [] when custom locators throw NoSuchElementError.
• Add regression tests to prevent swallowing unexpected custom-locator errors.

Diagram

graph TD
  U["Search context"] --> L["Custom locator"] --> FE["findElementInternal_"] --> A1{"Array result?"}
  A1 -->|"no"| OK1["Return WebElement"]
  A1 -->|"yes"| A2{"Empty array?"}
  A2 -->|"no"| OK1
  A2 -->|"yes"| NSE1["Throw NoSuchElementError"]
  U --> LE["findElementsInternal_"] --> T1{"Throws NoSuchElementError?"}
  T1 -->|"yes"| OUT0["Return []"]
  T1 -->|"no"| OUTN["Return list"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Normalize in public findElement/findElements wrappers

• ➕ Keeps internal helpers simpler and reduces branching inside internal code
• ➕ Makes normalization explicitly tied to public API semantics
• ➖ Risks inconsistent behavior across different search contexts if wrappers diverge
• ➖ May duplicate logic across WebDriver/WebElement/ShadowRoot entry points

2. Document stricter custom-locator contract (no normalization)

• ➕ Avoids introducing special-case translation logic
• ➕ Pushes responsibility to custom locator authors
• ➖ Breaks ergonomic expectations vs built-in locator behavior
• ➖ Does not address existing caller ambiguity between [] and NoSuchElementError

Recommendation: Keep the current approach: centralizing normalization in the shared internal custom-locator helpers is the most robust way to guarantee consistent behavior across search contexts and to preserve expected WebDriver semantics. The added tests appropriately lock in both no-match paths while ensuring unexpected errors still propagate.

Files changed (2) +35 / -1

Bug fix (1) +12 / -1

webdriver.jsNormalize custom-locator no-match results in internal find helpers +12/-1

Normalize custom-locator no-match results in internal find helpers

• Updates findElementInternal_ to treat an empty array result from a custom locator as a no-match and throw NoSuchElementError. Updates findElementsInternal_ to translate a NoSuchElementError thrown by a custom locator into an empty result list while rethrowing all other errors.

javascript/selenium-webdriver/lib/webdriver.js

Tests (1) +23 / -0

webdriver_test.jsAdd regression coverage for custom-locator empty/no-such-element behavior +23/-0

Add regression coverage for custom-locator empty/no-such-element behavior

• Adds tests asserting findElement throws NoSuchElementError when a custom locator returns []. Adds tests asserting findElements returns [] when a custom locator throws NoSuchElementError and that unexpected errors still propagate.

javascript/selenium-webdriver/test/lib/webdriver_test.js

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}