Move Design Strategies Java examples into tested gh-codeblock refs

[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

Redo of #2308 by @shbenzer. Moves the inline Java code fences in the "Loadable Component" / "Bot Pattern" walkthrough (design_strategies.en/ja/pt-br/zh-cn.md) into a real, compiling source file (examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java), referenced from the docs via gh-codeblock instead of duplicated inline snippets.

#2308 had the same goal but had drifted out of sync with trunk and had a few issues (a truncated code block, a class renamed mid-narrative, a reference into dead/commented-out code, and an unrelated malformed line-range on the Python tab). This redoes it from scratch against current trunk with those fixed:

• Fixed two bugs that were already present in the old inline snippets: a stray extra ) in setTitle, and setSeleniumVersion writing to the wrong field via a copy-pasted variable name (logOutput instead of seleniumVersion).
• Added a JUnit5 test wiring the full nested-components example (ProjectPage → SecuredPage → EditIssue) end-to-end, so the type-level correctness of the whole example is actually verified by the build. It's marked @Disabled since running it would exercise live GitHub/Google sign-in flows against real external sites.
• Verified with mvn test-compile and mvn test that everything compiles and the disabled test is properly skipped (not silently ignored).
• Hand-checked every new gh-codeblock line range against the final file content to make sure each one shows exactly the intended snippet.

Motivation and Context

Keeps the Java examples in this doc consistent with how other docs in this repo already work (tested source + gh-codeblock, rather than inline snippets that can silently drift or contain uncaught bugs), and fixes latent bugs in the existing content along the way.

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.

[qodo-code-review]

PR Summary by Qodo

Move Design Strategies Java docs to tested gh-codeblock snippets

📝 Documentation 🧪 Tests ✨ Enhancement 🕐 20-40 Minutes

AI Description

• Replace inline Java snippets with gh-codeblock references to a compiling source file.
• Add a JUnit 5 (disabled) end-to-end example test to keep docs type-correct.
• Fix latent snippet bugs (extra paren, wrong variable used in setSeleniumVersion).

Diagram

graph TD
  A["Design strategies docs (en/ja/pt-br/zh-cn)"] --> B["gh-codeblock shortcodes"] --> C["BestPractices.java"] --> D["JUnit/Maven build"] --> E["Selenium WebDriver"] --> F["External sites (GitHub/Google)"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Split examples into multiple Java files

• ➕ Keeps each class focused and easier to navigate
• ➕ More closely resembles real-world project structure
• ➖ Harder to maintain stable snippet line ranges across many files
• ➖ More gh-codeblock references to manage in 4 translations

2. Compile-only verification (no JUnit test method)

• ➕ Avoids any implication of running live flows
• ➕ Still guarantees the code compiles
• ➖ Does not demonstrate the end-to-end wiring of nested components
• ➖ Less obvious to readers how the pieces fit together

3. Use a snippet-extraction preprocessor instead of line ranges

• ➕ More resilient than line-number references (less drift)
• ➕ Could allow named snippets per section
• ➖ Adds tooling/process complexity to the docs build
• ➖ May not match existing project conventions around gh-codeblock

Recommendation: Keep the current approach (single compiling source + gh-codeblock ranges). It aligns with existing doc patterns, prevents snippet drift, and the disabled JUnit test usefully proves the nested-components example remains type-correct without introducing flaky live-network execution.

Files changed (5) +321 / -1268

Tests (1) +289 / -0

BestPractices.javaAdd compiling Design Strategies Java examples + disabled end-to-end test +289/-0

Add compiling Design Strategies Java examples + disabled end-to-end test

• Introduces a single source file containing the Page Object / LoadableComponent and ActionBot examples used in the docs. Includes a JUnit 5 test that wires the nested LoadableComponent example end-to-end and is explicitly @Disabled to avoid live GitHub/Google flows.

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java

Documentation (4) +32 / -1268

design_strategies.en.mdReplace inline Java fences with gh-codeblock references (EN) +8/-318

Replace inline Java fences with gh-codeblock references (EN)

• Removes duplicated inline Java snippets and replaces them with gh-codeblock references into BestPractices.java. Updates multiple sections (basic page object, LoadableComponent methods, nested components, and bot example) to pull exact line ranges.

website_and_docs/content/documentation/test_practices/design_strategies.en.md

design_strategies.ja.mdReplace inline Java fences with gh-codeblock references (JA) +8/-317

Replace inline Java fences with gh-codeblock references (JA)

• Mirrors the English doc restructure by swapping inline Java code blocks for gh-codeblock references into BestPractices.java. Ensures the Japanese page renders the same verified snippets via consistent line ranges.

website_and_docs/content/documentation/test_practices/design_strategies.ja.md

design_strategies.pt-br.mdReplace inline Java fences with gh-codeblock references (PT-BR) +8/-317

Replace inline Java fences with gh-codeblock references (PT-BR)

• Replaces embedded Java example blocks with gh-codeblock includes pointing at BestPractices.java. Keeps the PT-BR narrative while ensuring the displayed Java code stays compiling and consistent.

website_and_docs/content/documentation/test_practices/design_strategies.pt-br.md

design_strategies.zh-cn.mdReplace inline Java fences with gh-codeblock references (ZH-CN) +8/-316

Replace inline Java fences with gh-codeblock references (ZH-CN)

• Updates the Simplified Chinese doc to reference BestPractices.java via gh-codeblock instead of inline Java fences. Aligns snippet content with the tested source and reduces translation-page drift risk.

website_and_docs/content/documentation/test_practices/design_strategies.zh-cn.md

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	4b98ecc
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6a5de9b6cd5f0f00085885dd
😎 Deploy Preview	https://deploy-preview-2732--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]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (3) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 10 rules

1. Nested example not nested ✓ Resolved 🐞 Bug ≡ Correctness

Description

The docs claim EditIssue.get() loads dependencies (by calling securedPage.get() inside
EditIssue.load()), but the referenced Java source constructs EditIssue with no parent component
and calls securedPage.get() manually, so the narrative and code diverge.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[R266-278]

+class NestedComponentsExample {
+
+  @Test
+  @Disabled("Illustrative only: exercises live GitHub sign-in and issue-creation pages")
+  void demonstrateNestedLoadableComponents() {
+    WebDriver driver = new ChromeDriver();
+    try {
+      ProjectPage project = new ProjectPage(driver, "selenium");
+      SecuredPage securedPage = new SecuredPage(driver, project, "example", "top secret");
+      securedPage.get();
+
+      EditIssue editIssue = new EditIssue(driver).get();
+      editIssue.setHowToReproduce("How to Reproduce");

Evidence

The docs explicitly show securedPage.get() inside the EditIssue.load() snippet and state that
EditIssue.get() loads dependencies, but BestPractices.java’s EditIssue.load() only navigates
directly, while the example explicitly calls securedPage.get() before constructing EditIssue
without any parent.

website_and_docs/content/documentation/test_practices/design_strategies.en.md[73-117]
website_and_docs/content/documentation/test_practices/design_strategies.pt-br.md[93-119]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[161-185]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[266-279]

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 “Nested Components” documentation describes a dependency chain where `EditIssue.load()` invokes `securedPage.get()` (so `EditIssue.get()` loads dependencies automatically). The current canonical Java source does not model that nesting: `EditIssue` has no parent component, and the example calls `securedPage.get()` explicitly.

### Issue Context
This mismatch was introduced when the docs were switched from inline Java snippets to `gh-codeblock` references into `BestPractices.java`, but the surrounding narrative (and the inline `securedPage.get()` snippet in the docs) still describes the nested dependency behavior.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[161-185]
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[266-279]
- website_and_docs/content/documentation/test_practices/design_strategies.en.md[73-117]
- website_and_docs/content/documentation/test_practices/design_strategies.ja.md[82-112]
- website_and_docs/content/documentation/test_practices/design_strategies.pt-br.md[93-122]
- website_and_docs/content/documentation/test_practices/design_strategies.zh-cn.md[101-131]

### Suggested fix
Pick one consistent approach and apply it to both the canonical source and docs:

**Option A (recommended): make the code truly nested**
1. Add a `LoadableComponent<?> parent` (or `SecuredPage`) field to `EditIssue`.
2. Add an overload ctor `EditIssue(WebDriver driver, LoadableComponent<?> parent)`.
3. In `EditIssue.load()`, call `parent.get()` before `driver.get(...)`.
4. Update `NestedComponentsExample` to construct `new EditIssue(driver, securedPage).get()` and remove the manual `securedPage.get()`.
5. Replace the docs’ inline `securedPage.get()` load snippet with a `gh-codeblock` slice of the updated `EditIssue.load()`.

**Option B: update docs to describe the manual loading**
If you prefer the current code shape, update the docs (all translations) to remove the claim that `EditIssue.get()` loads dependencies and adjust the shown load snippet accordingly.

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

---

2. Wrong isLoaded URL check ✓ Resolved 🐞 Bug ≡ Correctness

Description

EditIssue.isLoaded() asserts the full URL ends with /new, but load() navigates to an
/issues/new?... URL with a query string, so new EditIssue(driver).get() will fail its load check
at runtime.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[R181-190]

+  @Override
+  protected void load() {
+    driver.get("https://github.com/SeleniumHQ/selenium/issues/new?assignees=&labels=I-defect%2Cneeds-triaging&projects=&template=bug-report.yml&title=%5B%F0%9F%90%9B+Bug%5D%3A+");
+  }
+
+  @Override
+  protected void isLoaded() throws Error {
+    String url = driver.getCurrentUrl();
+    Assertions.assertTrue(url.endsWith("/new"), "Not on the issue entry page: " + url);
+  }

Evidence

load() navigates to an /issues/new?... URL containing ?, but isLoaded() requires the entire
URL string to end in /new, which won’t be true once the query string is present. The example also
calls .get() on EditIssue, which triggers isLoaded().

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[181-190]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[266-279]

Agent prompt

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

### Issue description
`EditIssue.isLoaded()` currently checks `driver.getCurrentUrl().endsWith("/new")`, but `load()` navigates to a URL that includes a query string. This makes the LoadableComponent’s load verification fail when `.get()` is used.

### Issue Context
This file is used as the canonical source for rendered documentation snippets via `gh-codeblock`, so runtime-correctness matters even if the JUnit test is `@Disabled`.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[181-190]

### Suggested fix
Update `isLoaded()` to validate the path rather than the full URL string, e.g.:
- `Assertions.assertTrue(url.contains("/issues/new"), ...)`, **or**
- `URI uri = URI.create(url); Assertions.assertTrue(uri.getPath().endsWith("/new"), ...)`

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

---

3. Hard-coded "top secret" password ✓ Resolved 📘 Rule violation ⛨ Security

Description

The new Java example hard-codes a credential-like value by passing "top secret" to a password
parameter. Even in illustrative/disabled tests, committing hard-coded credentials violates the
project rule and can trigger secret-scanning/audit issues.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[274]

+      SecuredPage securedPage = new SecuredPage(driver, project, "example", "top secret");

Evidence

PR Compliance ID 2141351 disallows hard-coded secrets/credentials in committed code. The added
example test passes a hard-coded string to a password parameter (`new SecuredPage(..., "top
secret")`), which is a credential-like value committed to the repository.

Rule 2141351: Disallow hard-coded secrets and credentials in committed code
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[274-274]

Agent prompt

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

## Issue description
A hard-coded password-like string (`"top secret"`) is committed in the Java example, passed to a `password` parameter.

## Issue Context
Compliance requires that secrets/credentials not be hard-coded in tracked files, even in examples.

## Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[266-276]

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

---

4. EditIssueBasic referenced in prose 📘 Rule violation ✧ Quality ⭐ New

Description

The updated narrative text references Java-specific class names (EditIssueBasic, EditIssue) in
general prose, which contradicts the style guide requirement that code references be
language-independent. This can make the documentation less binding-agnostic for readers using
non-Java tabs/translations.

Code

website_and_docs/content/documentation/test_practices/design_strategies.en.md[R38-39]

+this offers the service of being able to file a new issue. A basic Page Object -- we'll call this
+simple version `EditIssueBasic`, before turning it into the `EditIssue` LoadableComponent below -- would look like:

Evidence

The style guide explicitly states that references to code should be language independent; however,
the modified prose in the design strategies page now names Java-specific types (EditIssueBasic,
EditIssue) in the general narrative.

Rule 2141344: Documentation changes must follow the central style guide file
website_and_docs/content/documentation/test_practices/design_strategies.en.md[38-39]
website_and_docs/content/documentation/about/style.en.md[74-78]

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 prose introduces Java-specific class names (`EditIssueBasic`, `EditIssue`) outside of a Java-only context, conflicting with the documentation style guide’s requirement that references to code be language independent.

## Issue Context
The page is presented with multi-language tabs; naming Java types in the shared narrative reduces binding-neutral clarity.

## Fix Focus Areas
- website_and_docs/content/documentation/test_practices/design_strategies.en.md[38-39]

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

---

5. Missing license header 🐞 Bug ⚙ Maintainability

Description

The new Java example file starts directly with a package declaration and omits the standard
SFC/Apache-2.0 header comment that other Java example tests in this repo include, creating
inconsistency for maintenance/compliance expectations.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[R1-5]

+package dev.selenium.design_strategies;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;

Evidence

BestPractices.java begins immediately with package ... and contains no header comment, while
other Java example tests (e.g., AlertsTest.java) include the SFC/Apache-2.0 header at the top of
the file.

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[1-5]
examples/java/src/test/java/dev/selenium/interactions/AlertsTest.java[1-16]

Agent prompt

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

### Issue description
`BestPractices.java` is missing the standard SFC/Apache-2.0 license header comment that appears at the top of other Java example test files in this repository.

### Issue Context
Keeping headers consistent across Java sources avoids confusion and supports the repo’s existing conventions.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[1-1]

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

---

6. IssueList URL check too broad ✓ Resolved 🐞 Bug ≡ Correctness

Description

IssueList.isLoaded() only asserts the URL contains "/issues", which will also be true on non-list
pages like "/issues/new"; this can incorrectly report the IssueList component as loaded on the wrong
page.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[R91-94]

+  @Override
+  protected void isLoaded() throws Error {
+    Assertions.assertTrue(driver.getCurrentUrl().contains("/issues"));
+  }

Evidence

IssueList.isLoaded() accepts any URL containing /issues, but EditIssue.isLoaded() targets
/issues/new (which also contains /issues), so the IssueList check can pass on the EditIssue page
and other issue routes.

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[78-95]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[196-200]

Agent prompt

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

### Issue description
`IssueList.isLoaded()` uses a substring match (`contains("/issues")`) that is satisfied by other routes such as `/issues/new`. This weak guard can let a `LoadableComponent` appear loaded even when the browser is on a different page.

### Issue Context
The same file has an `EditIssue.isLoaded()` check for `/issues/new`, demonstrating the overlap.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[86-95]

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

---

View more (5)

7. tabpane missing langEqualsHeader 📘 Rule violation ✧ Quality

Description

The updated code tabs use {{< tabpane text=true >}} while only the Java tab uses gh-codeblock
and the other tabs use badge-code, which contradicts the style guide guidance for mixed
gh-codeblock/non-gh-codeblock tab sets. This can lead to inconsistent rendering/formatting
expectations across documentation pages.

Code

website_and_docs/content/documentation/test_practices/design_strategies.en.md[R40-46]

+{{< tabpane text=true >}}
+{{< tab header="Python" >}}
+{{< badge-code >}}
+{{< /tab >}}
+{{< tab header="Java" >}}
+{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java#L14-L76" >}}
+{{< /tab >}}

Evidence

The style guide explicitly distinguishes between (a) all tabs using gh-codeblock (use `tabpane
text=true) and (b) only some tabs using gh-codeblock (keep langEqualsHeader=true` and add
text=true to the specific tab). The updated design strategies page uses tabpane text=true
while only the Java tab contains gh-codeblock and other tabs contain badge-code placeholders.

Rule 2141344: Documentation changes must follow the central style guide file
website_and_docs/content/documentation/about/style.en.md[138-142]
website_and_docs/content/documentation/test_practices/design_strategies.en.md[40-58]

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 design strategies pages use `tabpane text=true` even though only some tabs use `gh-codeblock`, which conflicts with the documented style guide rules for mixed tab contents.

## Issue Context
The style guide states that when only some tabs use `gh-codeblock`, `tabpane` should keep `langEqualsHeader=true` and only the relevant `tab`(s) should set `text=true`.

## Fix Focus Areas
- website_and_docs/content/documentation/test_practices/design_strategies.en.md[40-59]
- website_and_docs/content/documentation/about/style.en.md[138-142]

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

---

8. Snippet class name mismatch ✓ Resolved 🐞 Bug ≡ Correctness

Description

The Design Strategies docs introduce the basic Page Object as the EditIssue page, but the referenced
Java snippet renders EditIssueBasic, creating an unexplained name switch before later sections
discuss/use EditIssue. This breaks narrative continuity for readers trying to follow the Java
example step-by-step.

Code

website_and_docs/content/documentation/test_practices/design_strategies.en.md[R38-46]

this offers the service of being able to file a new issue. A basic Page Object would look like:

-```java
-package com.example.webdriver;
-
-import org.openqa.selenium.By;
-import org.openqa.selenium.WebDriver;
-import org.openqa.selenium.WebElement;
-
-public class EditIssue {
-
-  private final WebDriver driver;
-
-  public EditIssue(WebDriver driver) {
-    this.driver = driver;
-  }
-
-  public void setTitle(String title) {
-    WebElement field = driver.findElement(By.id("issue_title")));
-    clearAndType(field, title);
-  }
-
-  public void setBody(String body) {
-    WebElement field = driver.findElement(By.id("issue_body"));
-    clearAndType(field, body);
-  }
-
-  public void setHowToReproduce(String howToReproduce) {
-    WebElement field = driver.findElement(By.id("issue_form_repro-command"));
-    clearAndType(field, howToReproduce);
-  }
-
-  public void setLogOutput(String logOutput) {
-    WebElement field = driver.findElement(By.id("issue_form_logs"));
-    clearAndType(field, logOutput);
-  }
-
-  public void setOperatingSystem(String operatingSystem) {
-    WebElement field = driver.findElement(By.id("issue_form_operating-system"));
-    clearAndType(field, operatingSystem);
-  }
-
-  public void setSeleniumVersion(String seleniumVersion) {
-    WebElement field = driver.findElement(By.id("issue_form_selenium-version"));
-    clearAndType(field, logOutput);
-  }
-
-  public void setBrowserVersion(String browserVersion) {
-    WebElement field = driver.findElement(By.id("issue_form_browser-versions"));
-    clearAndType(field, browserVersion);
-  }
-
-  public void setDriverVersion(String driverVersion) {
-    WebElement field = driver.findElement(By.id("issue_form_browser-driver-versions"));
-    clearAndType(field, driverVersion);
-  }
-
-  public void setUsingGrid(String usingGrid) {
-    WebElement field = driver.findElement(By.id("issue_form_selenium-grid-version"));
-    clearAndType(field, usingGrid);
-  }
-
-  public IssueList submit() {
-    driver.findElement(By.cssSelector("button[type='submit']")).click();
-    return new IssueList(driver);
-  }
-
-  private void clearAndType(WebElement field, String text) {
-    field.clear();
-    field.sendKeys(text);
-  }
-}
-```
+{{< tabpane text=true >}}
+{{< tab header="Python" >}}
+{{< badge-code >}}
+{{< /tab >}}
+{{< tab header="Java" >}}
+{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java#L14-L76" >}}
+{{< /tab >}}

Evidence

The docs explicitly frame the snippet as the basic Page Object for filing a new issue (EditIssue),
but the referenced snippet’s class declaration is EditIssueBasic, so readers see a different type
name than the narrative uses before transitioning to EditIssue later.

website_and_docs/content/documentation/test_practices/design_strategies.en.md[36-95]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[14-26]
website_and_docs/content/documentation/test_practices/design_strategies.ja.md[31-83]

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 docs text describes the basic Page Object as `EditIssue`, but the `gh-codeblock` range used for the “basic Page Object” section shows `class EditIssueBasic`. This is confusing because the tutorial later refers to `EditIssue` as the evolving object.

### Issue Context
The extracted snippet at `BestPractices.java#L14-L76` begins with `class EditIssueBasic`, while the English (and translated) docs refer to `EditIssue` as the page being modeled.

### Fix Focus Areas
- website_and_docs/content/documentation/test_practices/design_strategies.en.md[36-88]
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[14-76]
- website_and_docs/content/documentation/test_practices/design_strategies.ja.md[31-86]

### Suggested fix approaches (pick one)
1) **Rename for continuity:** Rename `EditIssueBasic` to `EditIssue`, and rename the later `EditIssue` loadable-component class to something like `LoadableEditIssue` (then update `gh-codeblock` line ranges accordingly).
2) **Clarify in docs:** Update the prose to explicitly introduce `EditIssueBasic` as the initial/basic implementation and explain that it will be replaced by `EditIssue` (LoadableComponent version) later.

Also apply the same wording update across the translated design_strategies docs that share this section.

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

---

9. BestPractices.java lacks matching class 📘 Rule violation ⚙ Maintainability

Description

The new file BestPractices.java defines multiple top-level classes but does not define a
BestPractices type, diverging from the existing Java examples convention of matching the primary
public class name to the filename. This makes the examples harder to navigate and can confuse
contributors/readers looking for BestPractices by name.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[14]

+class EditIssueBasic {

Evidence

BestPractices.java starts with class EditIssueBasic and later defines other non-matching
top-level classes (e.g., class NestedComponentsExampleTest), indicating the filename does not
correspond to a type name. In contrast, existing examples like FirstScript.java follow the
convention of public class FirstScript matching the filename.

Rule 2141350: Align new files with existing directory and naming conventions
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[14-16]
examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[276-298]
examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java[10-10]

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/design_strategies/BestPractices.java` does not contain a `BestPractices` class, unlike other Java example files that define a public class matching the filename.

## Issue Context
Java examples in this repo typically use a filename that matches the primary public class (e.g., `FirstScript.java` contains `public class FirstScript`). While package-private multi-class files compile, they do not align with the established naming convention.

## Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[14-298]
- examples/java/src/test/java/dev/selenium/getting_started/FirstScript.java[10-10]

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

---

10. Undiscovered disabled JUnit test ✓ Resolved 🐞 Bug ☼ Reliability

Description

NestedComponentsExample.demonstrateNestedLoadableComponents() is annotated with @Test and
@Disabled, but the containing class name does not match the build’s default test discovery
patterns and the module has no Surefire/Gradle include override, so it won’t be discovered or
reported as skipped. This makes the example’s “tested/verified by build” intent ineffective because
CI will silently ignore it.

Code

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[R276-280]

+class NestedComponentsExample {
+
+  @Test
+  @Disabled("Illustrative only: exercises live GitHub sign-in and issue-creation pages")
+  void demonstrateNestedLoadableComponents() {

Evidence

The example’s only JUnit test is in a class named NestedComponentsExample (not
*Test/*Tests/*TestCase), and the examples module’s Surefire/Gradle configuration shown has no
custom includes to pick it up; therefore the test won’t be discovered and the @Disabled won’t even
be reported as skipped.

examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[276-298]
examples/java/pom.xml[58-76]
examples/java/build.gradle[23-25]

Agent prompt

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

### Issue description
`NestedComponentsExample` contains a JUnit 5 `@Test` method that is also annotated `@Disabled`, but because the class name doesn’t match the default test-class include patterns and there are no explicit includes configured, the test will not be discovered by Maven Surefire/Gradle.

Net effect: the method is not executed **and** not reported as skipped/disabled, so it doesn’t provide any CI signal and can easily drift.

### Issue Context
- The method is intentionally disabled (live external flows), but it should still be discoverable so it shows up as **skipped** rather than being silently ignored.

### Fix Focus Areas
- examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java[276-298]

### Suggested fix
- Rename the class to match test discovery patterns (e.g., `NestedComponentsExampleTest`) while keeping it package-private and keeping `@Disabled`.
- Alternatively, move the class into a separate file named `NestedComponentsExampleTest.java` (still `@Disabled`).

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

---

11. gh-codeblock used outside tabs ✓ Resolved 📘 Rule violation ✧ Quality

Description

The updated design strategies docs embed runnable Java examples via gh-codeblock without placing
them inside code tabs, which conflicts with the documentation style guide requirement that code
examples be in tabs. This can lead to inconsistent presentation and makes it harder to keep a
consistent multi-language documentation structure.

Code

website_and_docs/content/documentation/test_practices/design_strategies.en.md[40]

+{{< gh-codeblock path="/examples/java/src/test/java/dev/selenium/design_strategies/BestPractices.java#L14-L76" >}}

Evidence

The style guide requires that code examples be placed inside code tabs, and it specifically
discusses using gh-codeblock in tabs. The updated docs insert gh-codeblock snippets directly
into the page (outside a tab container), contradicting that documented convention.

Rule 2141344: Documentation changes must follow the central style guide file
website_and_docs/content/documentation/about/style.en.md[74-142]
website_and_docs/content/documentation/test_practices/design_strategies.en.md[34-62]

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 style guide states code examples should be placed inside code tabs, but the newly added `gh-codeblock` snippets in `design_strategies.*.md` are inserted directly into the page (outside any `tabpane`/`tab`).

## Issue Context
The central style guide (`style.en.md`) explicitly says code should be in tabs and provides guidance for using `gh-codeblock` within tab panes (including `text=true` usage).

## Fix Focus Areas
- website_and_docs/content/documentation/test_practices/design_strategies.en.md[34-125]
- website_and_docs/content/documentation/test_practices/design_strategies.ja.md[34-118]
- website_and_docs/content/documentation/test_practices/design_strategies.pt-br.md[40-125]
- website_and_docs/content/documentation/test_practices/design_strategies.zh-cn.md[43-140]

ⓘ 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 54431e9

[qodo-code-review]

Code review by qodo was updated up to the latest commit 2b5636b

[qodo-code-review]

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

[qodo-code-review]

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

[qodo-code-review]

Code review by qodo was updated up to the latest commit 4b98ecc