Fix missing Java examples for ByChained/ByAll locator strategies

[diemol]

Thanks for contributing to the Selenium site and documentation!
A PR well described will help maintainers to review and merge it quickly

Before submitting your PR, please check our contributing guidelines.
Avoid large PRs, and help reviewers by making them as simple and short as possible.

Description

Adds testByAll and testByChained methods to examples/java/src/test/java/dev/selenium/elements/LocatorTest.java, and updates the Locator Strategies documentation (en, ja, pt-br, zh-cn) to reference them with corrected line numbers.

Motivation and Context

Reported in #2620 ("Missing Java examples for Locator strategies").

A prior refactor (#2583) consolidated the Java locator examples into LocatorTest.java and deleted the old LocatorsTest.java, but the "ByChained" and "ByAll" sections of the Locator Strategies doc, in all four languages, were left pointing at the deleted file. Those gh-codeblock references resolved to nothing since the file no longer exists.

This adds real, runnable implementations of ByAll and ByChained (verified against https://www.selenium.dev/selenium/web/login.html) to LocatorTest.java, and repoints the four language docs at the correct file. Adding the new imports shifted every existing line number in the file by 3, so the doc's other Java gh-codeblock references (class name, css selector, id, name, link text, partial link text, tag name, xpath) were also updated to match.

Note: the "Relative Locators" section (above/below/left of/right of/near/chaining) still uses hardcoded snippets rather than gh-codeblock for all languages, not just Java — that's a larger change (needs a fixture page with matching elements) and is left out of this PR to keep it focused.

Types of changes

• Change to the site (I have double-checked the Netlify deployment, and my changes look good)
• Code example added (and I also added the example to all translated languages)
• Improved translation
• Added new translation (and I also added a notice to each document missing translation)

Checklist

• I have read the contributing document.
• I have used hugo to render the site/docs locally and I am sure it works.

Closes #2620.

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	bb430d6
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6a61ebdc2c27050008dc9db8
😎 Deploy Preview	https://deploy-preview-2738--selenium-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[qodo-code-review]

PR Summary by Qodo

Restore Java ByAll/ByChained examples and fix locator docs codeblocks

🐞 Bug fix 📝 Documentation 🧪 Tests 🕐 10-20 Minutes

AI Description

• Add runnable Java examples for ByAll and ByChained locator strategies.
• Repoint Locator Strategies docs to the correct Java file after refactor.
• Update Java gh-codeblock line references across en/ja/pt-br/zh-cn pages.

Diagram

graph TD
D["locators.*.md (en/ja/pt-br/zh-cn)"] -->|"gh-codeblock"| T["LocatorTest.java"] -->|"runs via JUnit"| W["WebDriver"] --> P(("login.html"))
T --> A["ByAll/ByChained"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Switch docs to inline snippets for these sections

• ➕ Avoids brittle line-number coupling to Java source files
• ➕ No risk of future refactors silently breaking embeds
• ➖ Duplication between docs and runnable examples
• ➖ Harder to keep docs in sync with tested code over time

2. Introduce stable snippet markers for gh-codeblock extraction

• ➕ Keeps docs sourced from runnable code while reducing line-number churn
• ➕ Makes refactors less likely to break documentation examples
• ➖ Requires shortcode/tooling support beyond the current line-range mechanism
• ➖ Adds complexity to the docs build/validation pipeline

3. Add CI validation for gh-codeblock targets

• ➕ Catches missing files/invalid line ranges across all translations early
• ➕ Prevents regressions from refactors like the one that deleted LocatorsTest.java
• ➖ Additional CI maintenance and implementation effort
• ➖ Does not eliminate the underlying line-number brittleness

Recommendation: The PR’s approach is the best immediate fix: add the missing runnable Java examples and repoint all translated docs to the new canonical file with corrected line numbers. Longer-term, consider adding gh-codeblock validation (or marker-based extraction) to reduce future breakage from refactors.

Files changed (5) +63 / -40

Tests (1) +23 / -0

LocatorTest.javaAdd ByAll and ByChained Java locator examples as runnable tests +23/-0

Add ByAll and ByChained Java locator examples as runnable tests

• Adds imports for ByAll/ByChained and java.util.List. Introduces two new JUnit tests (testByAll/testByChained) that exercise compound locator strategies against the Selenium login fixture page.

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java

Documentation (4) +40 / -40

locators.en.mdFix English locator docs gh-codeblock Java references and line numbers +10/-10

Fix English locator docs gh-codeblock Java references and line numbers

• Updates Java gh-codeblock line anchors to account for new imports shifting line numbers. Replaces stale references to deleted LocatorsTest.java in the ByChained/ByAll sections with the correct LocatorTest.java ranges.

website_and_docs/content/documentation/webdriver/elements/locators.en.md

locators.ja.mdFix Japanese locator docs gh-codeblock Java references and line numbers +10/-10

Fix Japanese locator docs gh-codeblock Java references and line numbers

• Adjusts Java gh-codeblock line anchors to match the updated LocatorTest.java. Repoints ByChained/ByAll sections away from the removed LocatorsTest.java to the new method locations.

website_and_docs/content/documentation/webdriver/elements/locators.ja.md

locators.pt-br.mdFix Brazilian Portuguese locator docs gh-codeblock Java references and line numbers +10/-10

Fix Brazilian Portuguese locator docs gh-codeblock Java references and line numbers

• Updates Java gh-codeblock anchors to the correct LocatorTest.java line numbers after new imports. Fixes ByChained/ByAll references that previously targeted the deleted LocatorsTest.java file.

website_and_docs/content/documentation/webdriver/elements/locators.pt-br.md

locators.zh-cn.mdFix Simplified Chinese locator docs gh-codeblock Java references and line numbers +10/-10

Fix Simplified Chinese locator docs gh-codeblock Java references and line numbers

• Corrects Java gh-codeblock line anchors to align with the updated LocatorTest.java. Updates ByChained/ByAll sections to reference LocatorTest.java instead of the removed LocatorsTest.java.

website_and_docs/content/documentation/webdriver/elements/locators.zh-cn.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 10 rules

1. Indented gh-codeblock shortcode ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

Modified locator docs include leading whitespace before {{< gh-codeblock ... >}}, which violates
the no-indentation requirement and can prevent the shortcode from being parsed/rendered. This can
cause the Java example snippets to disappear from the documentation pages.

Code

website_and_docs/content/documentation/webdriver/elements/locators.en.md[80]

+   {{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/elements/LocatorTest.java#L34" >}}

Evidence

PR Compliance ID 2141348 forbids any indentation before {{< gh-codeblock lines. The modified
locator documentation pages contain indented gh-codeblock invocations, and the style guide
reiterates that gh-codeblock lines cannot be indented.

Rule 2141348: Disallow indentation before gh-codeblock shortcode in Markdown
website_and_docs/content/documentation/about/style.en.md[138-143]
website_and_docs/content/documentation/webdriver/elements/locators.en.md[80-80]
website_and_docs/content/documentation/webdriver/elements/locators.en.md[354-354]
website_and_docs/content/documentation/webdriver/elements/locators.ja.md[78-78]
website_and_docs/content/documentation/webdriver/elements/locators.pt-br.md[81-81]
website_and_docs/content/documentation/webdriver/elements/locators.zh-cn.md[81-81]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`gh-codeblock` shortcode invocation lines must not be indented, but the updated docs indent them (e.g., with one or more spaces before `{{<`). This can break Hugo shortcode parsing and result in missing code snippets.

## Issue Context
The central documentation style guide explicitly states that the `gh-codeblock` line cannot be indented.

## Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/locators.en.md[73-150]
- website_and_docs/content/documentation/webdriver/elements/locators.en.md[345-399]
- website_and_docs/content/documentation/webdriver/elements/locators.ja.md[72-150]
- website_and_docs/content/documentation/webdriver/elements/locators.ja.md[345-399]
- website_and_docs/content/documentation/webdriver/elements/locators.pt-br.md[75-155]
- website_and_docs/content/documentation/webdriver/elements/locators.pt-br.md[348-400]
- website_and_docs/content/documentation/webdriver/elements/locators.zh-cn.md[75-155]
- website_and_docs/content/documentation/webdriver/elements/locators.zh-cn.md[348-400]

(Ensure every line that starts with whitespace + `{{< gh-codeblock` is moved to column 1.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Extra external fixture dependency 🐞 Bug ☼ Reliability

Description

The new Java tests navigate to https://www.selenium.dev/selenium/web/login.html, adding a second
external fixture page beyond the existing locators_tests/locators.html used by setup and other
language examples. This increases the surface area for flaky failures if the page is unavailable or
its markup changes.

Code

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[R89-100]

+    public void testByAll() {
+        driver.get("https://www.selenium.dev/selenium/web/login.html");
+
+        By locator = new ByAll(By.id("password-field"), By.id("username-field"));
+        List<WebElement> loginInputs = driver.findElements(locator);
+
+        Assertions.assertEquals(2, loginInputs.size());
+    }
+
+    @Test
+    public void testByChained() {
+        driver.get("https://www.selenium.dev/selenium/web/login.html");

Evidence

Java setup consistently uses the locators fixture page, but the new tests add navigation to a
different external page. The Python and JavaScript locator example tests in this repo continue to
use only the locators fixture page, highlighting the incremental dependency increase specific to the
new Java additions.

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[17-22]
examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[88-103]
examples/python/tests/elements/test_locators.py[6-9]
examples/javascript/test/elements/locators.spec.js[5-8]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The Java locator examples now depend on two different live pages on selenium.dev; this increases test fragility and maintenance cost.

### Issue Context
`setUp()` navigates to `locators_tests/locators.html`, but the new `ByAll`/`ByChained` tests navigate to `login.html`. Other language locator example tests shown in this repo use only the `locators_tests/locators.html` page.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[17-22]
- examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[88-106]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Missing final newline 🐞 Bug ⚙ Maintainability

Description

LocatorTest.java is committed without a trailing newline at EOF, which can trigger formatting/lint
warnings and causes noisy diffs when tools normalize line endings.

Code

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[107]

}

Evidence

The file currently ends at the closing brace (line 107) with no additional line after it; the PR
diff also flags the file as missing an end-of-file newline.

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[105-107]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`examples/java/src/test/java/dev/selenium/elements/LocatorTest.java` ends without a final newline, which can trigger formatting/lint warnings and causes avoidable diff churn.

### Issue Context
The PR diff indicates `No newline at end of file` for `LocatorTest.java`.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[107-107]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. ByChained example unclear ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

testByChained chains a parent By.id(...) with a child By.id(...), which doesn’t clearly
demonstrate the practical value of chaining for scoping (the doc text describes parent/child
scoping). This weakens the example and may mislead readers about when ByChained is useful.

Code

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[R102-103]

+        By locator = new ByChained(By.id("login-form"), By.id("username-field"));
+        WebElement usernameInput = driver.findElement(locator);

Evidence

The ByChained docs describe combining a parent element lookup with a child lookup; the Java example
chains a parent id with a child id, which is less illustrative of scoping than using a child locator
that benefits from being evaluated within the parent context.

examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[99-103]
website_and_docs/content/documentation/webdriver/elements/locators.en.md[347-351]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The `ByChained` example uses `By.id` for the child locator, which doesn’t illustrate why chaining helps with parent/child scoping.

### Issue Context
The locator strategies doc text for ByChained explains combining a parent lookup and a child lookup into one call; using an `id` for the child undercuts that narrative.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/elements/LocatorTest.java[99-106]
- website_and_docs/content/documentation/webdriver/elements/locators.en.md[347-351]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit bb430d6