Update elements finders python docs

[pmartinez1]

User description

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

Moving code examples from the .md files to the .py files for elements/finders

Motivation and Context

Keeps code in a single place.

Types of changes

• Change to the site (I have double-checked the Netlify deployment, and my changes look good)
• [ x] 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.

---

PR Type

Enhancement, Documentation

---

Description

• Added comprehensive test suite for Selenium element finders in Python:

  • Basic element finding methods
  • Shadow DOM interaction
  • Optimized locators
  • Multiple elements finding
  • Parent-child element relationships
  • Active element handling

• Updated documentation across multiple languages:

  • Replaced inline Python code examples with references to actual test implementations
  • Synchronized changes across English, Japanese, Portuguese and Chinese versions
  • Maintained consistent documentation structure

• Improved code organization by:

  • Moving code examples from markdown files to dedicated test files
  • Ensuring consistent examples across all language versions
  • Adding proper test setup/teardown patterns

---

Changes walkthrough 📝

	Relevant files
Tests	test_finders.py Add comprehensive test suite for Selenium element finders examples/python/tests/elements/test_finders.py Added test functions for various element finding methods in Selenium Implemented tests for basic finders, shadow DOM, optimized locators, and active elements Added examples for finding multiple elements and working with parent elements Each test includes proper setup/teardown with driver initialization and quit +91/-0
Documentation	finders.en.md Update Python code examples in element finders documentation website_and_docs/content/documentation/webdriver/elements/finders.en.md Updated Python code examples to reference actual test implementations Replaced inline code with references to test file examples Maintained documentation structure while updating code blocks +16/-64  finders.ja.md Sync Japanese documentation with updated Python examples  website_and_docs/content/documentation/webdriver/elements/finders.ja.md Updated Python code examples to match English version Replaced inline code with references to test implementations +16/-64  finders.pt-br.md Sync Portuguese documentation with updated Python examples website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md Updated Python code examples to match English version Replaced inline code with references to test implementations +16/-59  finders.zh-cn.md Sync Chinese documentation with updated Python examples    website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md Updated Python code examples to match English version Replaced inline code with references to test implementations +16/-64

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	d025197
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/68a0eac9b615380008416e9c
😎 Deploy Preview	https://deploy-preview-2099--selenium-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Resource Management Multiple test functions create and use WebDriver instances without proper cleanup in case of test failures. Consider using test fixtures or try-finally blocks to ensure driver.quit() is always called. Error Handling Tests lack proper error handling and assertions for element existence before interacting with them. Should add try-catch blocks or explicit waits where needed. Code Duplication Driver initialization and cleanup code is duplicated across all test functions. Should be refactored into setup/teardown methods.

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Score
General	Ensure proper resource cleanup by using try-finally blocks when managing browser sessions Add proper cleanup by using try-finally block to ensure driver.quit() is called even if test fails examples/python/tests/elements/test_finders.py [5-14] def test_basic_finders(): driver = webdriver.Chrome() - driver.get('https://www.selenium.dev/') - - body_on_page = driver.find_element(By.CLASS_NAME, 'td-home') - container_on_page = body_on_page.find_element(By.CLASS_NAME, 'container-fluid') - - assert container_on_page.is_displayed() - - driver.quit() + try: + driver.get('https://www.selenium.dev/') + + body_on_page = driver.find_element(By.CLASS_NAME, 'td-home') + container_on_page = body_on_page.find_element(By.CLASS_NAME, 'container-fluid') + + assert container_on_page.is_displayed() + finally: + driver.quit() Apply this suggestion Suggestion importance[1-10]: 8 Why: Adding try-finally blocks is crucial for proper resource management, ensuring browser sessions are always closed even if tests fail. This prevents resource leaks and hanging browser processes.	8
Possible issue	Add validation for shadow root existence to prevent null pointer exceptions Add error handling for find_element calls to handle cases when elements are not found examples/python/tests/elements/test_finders.py [20-22] def test_evaluating_shadow_DOM(): driver = webdriver.Chrome() - driver.implicitly_wait(5) - driver.get('https://www.selenium.dev/selenium/web/shadowRootPage.html') - - custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element') - shadow_dom_input = custom_element.shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]') + try: + driver.implicitly_wait(5) + driver.get('https://www.selenium.dev/selenium/web/shadowRootPage.html') + + custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element') + if not custom_element.shadow_root: + raise ValueError("Shadow root not found") + shadow_dom_input = custom_element.shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]') Apply this suggestion Suggestion importance[1-10]: 7 Why: Validating shadow root existence before accessing it prevents potential null pointer exceptions that could occur if the shadow DOM is not properly initialized, improving test reliability.	7

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	6eb6f9f
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6a5e46c5ead20e0008753805
😎 Deploy Preview	https://deploy-preview-2099--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 (3) 📘 Rule violations (1) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 10 rules

1. Docs embed wrong Python ✓ Resolved 🐞 Bug ≡ Correctness

Description

The finders docs now embed Python code from examples/python/tests/elements/test_finders.py that does
not implement the behavior described in the surrounding narrative (e.g., locating class "tomatoes"
or "#shadow_host"). This publishes incorrect Python examples across multiple localized docs pages
and misleads readers.

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[R49-50]

+  {{< tab header="Python" text=true >}}
+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L9">}}

Evidence

The docs text describes selecting class "tomatoes" and shadow DOM elements by
"#shadow_host/#shadow_content", but the referenced Python line ranges show different locators and
elements (e.g., 'td-home' and 'custom-checkbox-element'), so the embedded examples no longer match
the documented behavior.

website_and_docs/content/documentation/webdriver/elements/finders.en.md[37-54]
website_and_docs/content/documentation/webdriver/elements/finders.en.md[110-125]
examples/python/tests/elements/test_finders.py[5-12]
examples/python/tests/elements/test_finders.py[21-22]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[36-48]

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 documentation pages for element finders replaced inline Python snippets with `gh-codeblock` references into `examples/python/tests/elements/test_finders.py`, but those referenced lines contain unrelated Selenium.dev homepage/shadow-demo code, not the selectors/variables described in the documentation (e.g., `tomatoes`, `#fruits`, `#shadow_host`).

## Issue Context
The Java/C#/Ruby examples and the prose still describe the original “tomatoes/fruits/shadow_host/google active element” scenarios, but the embedded Python code now shows different locators and different pages, causing incorrect documentation.

## Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[116-125]
- examples/python/tests/elements/test_finders.py[5-92]

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

---

2. Wrong XPath scoping ✓ Resolved 🐞 Bug ≡ Correctness

Description

test_find_elements_from_element states that element-scoped XPath must start with '.', but then uses
header_tag.find_element(By.XPATH, '//ul'), which ignores the header scope. This can select a
different <ul> than intended and teaches the wrong pattern.

Code

examples/python/tests/elements/test_finders.py[R63-71]

+    ## get elements from parent element using XPATH
+    ## NOTE: in order to utilize XPATH from current element, you must add "." to beginning of path
+
+    header_tag = driver.find_element(By.TAG_NAME, 'header')
+    # Get first element of tag 'ul'
+    ul_tag = header_tag.find_element(By.XPATH, '//ul')
+
+    # get children of tag 'ul' with tag 'li'
+    elements  = ul_tag.find_elements(By.XPATH, './/li')

Evidence

The comment explicitly instructs using '.' for element-relative XPath, but the next lookup uses
//ul (absolute), contradicting the guidance and breaking element scoping.

examples/python/tests/elements/test_finders.py[63-71]

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 example claims XPath must be prefixed with `.` when searching from a WebElement, but uses an absolute XPath (`//ul`) from `header_tag`, which is inconsistent and may return an element outside the header.

## Issue Context
This file is used as the canonical source for documentation snippets. The code should demonstrate correct scoping behavior.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[63-72]

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

---

3. Always-skipped tests collected 🐞 Bug ⚙ Maintainability ⭐ New

Description

test_finders.py adds four test_* functions that are unconditionally @pytest.mark.skip, so they
will be collected by pytest and always reported as skipped in the Python examples CI. This creates
persistent test-report noise and makes skipped-test counts less meaningful.

Code

examples/python/tests/elements/test_finders.py[R21-39]

+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_basic_finders(driver):
+    vegetable = driver.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_subset_of_dom(driver):
+    fruits = driver.find_element(By.ID, 'fruits')
+    fruit = fruits.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_optimized_locator(driver):
+    fruit = driver.find_element(By.CSS_SELECTOR, '#fruits .tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_all_matching_elements(driver):
+    plants = driver.find_elements(By.TAG_NAME, 'li')

Evidence

These functions are unconditional @pytest.mark.skip and are named test_*, so pytest will collect
them; the CI workflow runs pytest in examples/python, meaning the skipped tests will be reported
on every CI run.

examples/python/tests/elements/test_finders.py[21-39]
.github/workflows/python-examples.yml[87-90]

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 module defines documentation-only examples as `test_*` functions with unconditional `@pytest.mark.skip`. Pytest still collects them, so they show up as skipped on every run.

### Issue Context
The Python examples workflow runs pytest over the `examples/python` tree, so these will be part of the standard CI signal.

### Fix Focus Areas
- examples/python/tests/elements/test_finders.py[21-39]
- .github/workflows/python-examples.yml[87-90]

### Suggested fix
Convert these illustrative-only snippets into non-collected functions (e.g., rename `test_basic_finders` -> `example_basic_finders` and remove the skip markers) or move them to a non-test module/file dedicated to documentation snippets. If you move/rename code, also update any `gh-codeblock` references that point at the old line numbers.

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

---

4. Python docs require CI token 🐞 Bug ☼ Reliability

Description

The finders docs now embed Python snippets via gh-codeblock, but that shortcode only renders
fetched code when SELENIUM_CI_TOKEN is set; otherwise it renders a “token not set” alert instead
of code. This makes local documentation builds lose the Python examples on the updated pages (and
any environment that doesn’t provide the token).

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[R49-51]

+  {{< tab header="Python" text=true >}}
+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L23">}}
  {{< /tab >}}

Evidence

The updated docs pages call gh-codeblock for Python, and the shortcode implementation gates remote
fetching on SELENIUM_CI_TOKEN; when unset it falls back to a partial that renders an alert instead
of code.

website_and_docs/content/documentation/webdriver/elements/finders.en.md[44-52]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[42-48]
website_and_docs/layouts/shortcodes/gh-codeblock.html[32-41]
website_and_docs/layouts/shortcodes/gh-codeblock.html[178-180]
website_and_docs/layouts/partials/github-content.html[1-18]

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` currently requires `SELENIUM_CI_TOKEN` to fetch and render code; without it, it renders an alert instead of the code snippet. This PR expands `gh-codeblock` usage for Python examples, increasing the number of docs sections that won’t render code in local builds.

### Issue Context
The code being referenced lives in this same repository. A practical fallback is to render from the local filesystem (Hugo `readFile`) when available, or attempt unauthenticated `GetRemote` when the token is missing.

### Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/layouts/shortcodes/gh-codeblock.html[32-41]
- website_and_docs/layouts/partials/github-content.html[1-18]

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

---

5. Skipped examples use undefined driver ✓ Resolved 🐞 Bug ≡ Correctness

Description

examples/python/tests/elements/test_finders.py contains skipped “illustrative” functions that
reference driver without defining it or accepting the existing pytest driver fixture parameter,
so the example code is not internally consistent and will raise NameError if executed/copied
as-is. This is especially risky because the docs now embed these exact lines via gh-codeblock,
making the undefined symbol the canonical snippet source.

Code

examples/python/tests/elements/test_finders.py[R21-39]

+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_basic_finders():
+    vegetable = driver.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_subset_of_dom():
+    fruits = driver.find_element(By.ID, 'fruits')
+    fruit = fruits.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_optimized_locator():
+    fruit = driver.find_element(By.CSS_SELECTOR, '#fruits .tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_all_matching_elements():
+    plants = driver.find_elements(By.TAG_NAME, 'li')

Evidence

The skipped illustrative functions call driver.find_element(...)/driver.find_elements(...)
without defining driver or accepting it as an injected fixture parameter, while the repo’s
conftest.py provides a driver fixture meant to be injected by naming a function parameter
driver.

examples/python/tests/elements/test_finders.py[21-39]
examples/python/tests/conftest.py[25-43]

Agent prompt

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

### Issue description
`test_finders.py` has skipped illustrative functions that reference a `driver` name that is not defined in the function scope. Even though they are skipped, they are still “source of truth” snippets for docs and are one edit away from becoming runnable tests.

### Issue Context
The repo already defines a pytest `driver` fixture that supplies and quits a WebDriver instance. The illustrative examples should either accept this fixture (`def test_x(driver): ...`) or otherwise define `driver` locally to avoid undefined-name examples.

### Fix Focus Areas
- examples/python/tests/elements/test_finders.py[21-39]
- examples/python/tests/conftest.py[25-43]

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

---

View more (4)

6. Shadow root checked too late ✓ Resolved 🐞 Bug ☼ Reliability

Description

In test_evaluating_shadow_DOM, the code queries custom_element.shadow_root before validating it
exists, so the later assertion cannot guard against a missing/unsupported shadow root and the
failure will occur earlier than intended. This also makes the example pattern less robust if the
element/tag changes or the page fixture is updated.

Code

examples/python/tests/elements/test_finders.py[R21-26]

+    custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element')
+    shadow_dom_input = custom_element.shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]')
+
+    assert custom_element.is_displayed()
+    assert custom_element.shadow_root
+    assert shadow_dom_input.is_displayed()

Evidence

The test dereferences custom_element.shadow_root to find an element, and only afterwards asserts
the shadow root exists, so the assertion cannot prevent an earlier failure if shadow_root is
missing or unsupported.

examples/python/tests/elements/test_finders.py[16-26]

Agent prompt

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

### Issue description
`test_evaluating_shadow_DOM` calls `custom_element.shadow_root.find_element(...)` before checking that `shadow_root` is present. If the host element does not have a shadow root (or the driver/page changes), the test will fail before reaching the assertion meant to validate shadow root existence.

### Issue Context
This test file is also referenced by docs via `gh-codeblock`, so the ordering here influences the robustness of the example pattern.

### Fix Focus Areas
- examples/python/tests/elements/test_finders.py[21-26]

### Suggested change
Assign the shadow root to a variable and assert it before using it:

```python
custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element')
shadow_root = custom_element.shadow_root
assert shadow_root
shadow_dom_input = shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]')
```

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

---

7. Indented gh-codeblock shortcode 📘 Rule violation ⚙ Maintainability

Description

gh-codeblock shortcode invocations in finders.en.md, finders.ja.md, finders.pt-br.md, and
finders.zh-cn.md are indented, which can prevent Hugo from parsing the shortcode correctly and
break code example rendering.

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[50]

+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L9">}}

Evidence

Compliance rule 2141348 forbids leading whitespace before {{< gh-codeblock in changed Markdown
files, requiring the shortcode to start at column 1. The cited lines in each of the affected files
show the gh-codeblock invocation preceded by spaces, indicating the rule is being violated and
risking incorrect shortcode parsing/rendering.

Rule 2141348: Disallow indentation before gh-codeblock shortcode in Markdown
website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[46-48]
website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[47-49]
website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[49-51]

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 lines must not have any leading whitespace. In `finders.en.md`, `finders.ja.md`, `finders.pt-br.md`, and `finders.zh-cn.md`, the newly added `gh-codeblock` lines are indented.

## Issue Context
PR Compliance requires `{{< gh-codeblock ... >}}` to start at column 1; indentation can stop the shortcode from being parsed/rendered.

## Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[82-84]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[160-162]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[190-192]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[221-223]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[453-455]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[46-48]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[76-78]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[150-152]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[179-181]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[208-210]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[438-440]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[47-49]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[78-80]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[154-156]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[182-184]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[212-214]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[437-439]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[81-83]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[158-160]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[187-189]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[217-219]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[447-449]

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

---

8. Homepage selectors are brittle ✓ Resolved 🐞 Bug ☼ Reliability

Description

Several new tests depend on https://www.selenium.dev/ homepage structure (e.g., .td-home,
#announcement-banner, .nav-item.dropdown), which can change and create flaky failures unrelated
to Selenium. Existing examples typically use dedicated /selenium/web/... fixture pages designed
for automation stability.

Code

examples/python/tests/elements/test_finders.py[R30-36]

+def test_optimized_locator():
+    driver = webdriver.Chrome()
+    driver.get('https://www.selenium.dev/')
+
+    nested_element = driver.find_element(By.CSS_SELECTOR, '.td-home #announcement-banner')
+
+    assert nested_element.is_displayed()

Evidence

The new tests navigate to the homepage and use selectors tied to that page’s current layout, while
existing tests demonstrate the established pattern of using stable fixture pages under
/selenium/web/....

examples/python/tests/elements/test_finders.py[5-10]
examples/python/tests/elements/test_finders.py[30-36]
examples/python/tests/elements/test_locators.py[6-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
Tests currently target the public Selenium homepage and assert on its layout-specific selectors, making them sensitive to site redesigns and unrelated deployments.

## Issue Context
Other Python example tests in this repo use `https://www.selenium.dev/selenium/web/...` pages that are intended as stable automation fixtures.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[5-92]
- examples/python/tests/elements/test_locators.py[6-10]

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

---

9. Quit not exception-safe 🐞 Bug ☼ Reliability

Description

Each new test constructs a Chrome driver and calls driver.quit() only at the end, so exceptions or
assertion failures before that point will leak browser processes. The repo already provides a pytest
driver fixture that guarantees quit() in teardown, but these tests do not use it.

Code

examples/python/tests/elements/test_finders.py[R5-14]

+def test_basic_finders():
+    driver = webdriver.Chrome()
+    driver.get('https://www.selenium.dev/')
+
+    body_on_page = driver.find_element(By.CLASS_NAME, 'td-home')
+    container_on_page = body_on_page.find_element(By.CLASS_NAME, 'container-fluid')
+
+    assert container_on_page.is_displayed()
+
+    driver.quit()

Evidence

The new tests call driver.quit() after assertions with no finally, so any earlier failure skips
cleanup; the existing driver fixture shows the intended teardown pattern that always quits.

examples/python/tests/elements/test_finders.py[5-15]
examples/python/tests/conftest.py[23-40]

Agent prompt

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

## Issue description
`driver.quit()` is not protected by `try/finally` (or a fixture teardown), so failures can leave Chrome/driver processes running and interfere with later tests or CI stability.

## Issue Context
`examples/python/tests/conftest.py` already defines a `driver` fixture that yields a driver and always calls `quit()` during teardown.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[5-92]
- examples/python/tests/conftest.py[23-40]

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

---

Previous review results

Review updated until commit 6eb6f9f

Results up to commit 6d36b75 ⚖️ Balanced

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Wrong XPath scoping 🐞 Bug ≡ Correctness

Description

test_find_elements_from_element states that element-scoped XPath must start with '.', but then uses
header_tag.find_element(By.XPATH, '//ul'), which ignores the header scope. This can select a
different <ul> than intended and teaches the wrong pattern.

Code

examples/python/tests/elements/test_finders.py[R63-71]

+    ## get elements from parent element using XPATH
+    ## NOTE: in order to utilize XPATH from current element, you must add "." to beginning of path
+
+    header_tag = driver.find_element(By.TAG_NAME, 'header')
+    # Get first element of tag 'ul'
+    ul_tag = header_tag.find_element(By.XPATH, '//ul')
+
+    # get children of tag 'ul' with tag 'li'
+    elements  = ul_tag.find_elements(By.XPATH, './/li')

Evidence

The comment explicitly instructs using '.' for element-relative XPath, but the next lookup uses
//ul (absolute), contradicting the guidance and breaking element scoping.

examples/python/tests/elements/test_finders.py[63-71]

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 example claims XPath must be prefixed with `.` when searching from a WebElement, but uses an absolute XPath (`//ul`) from `header_tag`, which is inconsistent and may return an element outside the header.

## Issue Context
This file is used as the canonical source for documentation snippets. The code should demonstrate correct scoping behavior.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[63-72]

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

---

2. Docs embed wrong Python ✓ Resolved 🐞 Bug ≡ Correctness

Description

The finders docs now embed Python code from examples/python/tests/elements/test_finders.py that does
not implement the behavior described in the surrounding narrative (e.g., locating class "tomatoes"
or "#shadow_host"). This publishes incorrect Python examples across multiple localized docs pages
and misleads readers.

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[R49-50]

+  {{< tab header="Python" text=true >}}
+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L9">}}

Evidence

The docs text describes selecting class "tomatoes" and shadow DOM elements by
"#shadow_host/#shadow_content", but the referenced Python line ranges show different locators and
elements (e.g., 'td-home' and 'custom-checkbox-element'), so the embedded examples no longer match
the documented behavior.

website_and_docs/content/documentation/webdriver/elements/finders.en.md[37-54]
website_and_docs/content/documentation/webdriver/elements/finders.en.md[110-125]
examples/python/tests/elements/test_finders.py[5-12]
examples/python/tests/elements/test_finders.py[21-22]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[36-48]

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 documentation pages for element finders replaced inline Python snippets with `gh-codeblock` references into `examples/python/tests/elements/test_finders.py`, but those referenced lines contain unrelated Selenium.dev homepage/shadow-demo code, not the selectors/variables described in the documentation (e.g., `tomatoes`, `#fruits`, `#shadow_host`).

## Issue Context
The Java/C#/Ruby examples and the prose still describe the original “tomatoes/fruits/shadow_host/google active element” scenarios, but the embedded Python code now shows different locators and different pages, causing incorrect documentation.

## Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[116-125]
- examples/python/tests/elements/test_finders.py[5-92]

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

---

3. Homepage selectors are brittle ✓ Resolved 🐞 Bug ☼ Reliability

Description

Several new tests depend on https://www.selenium.dev/ homepage structure (e.g., .td-home,
#announcement-banner, .nav-item.dropdown), which can change and create flaky failures unrelated
to Selenium. Existing examples typically use dedicated /selenium/web/... fixture pages designed
for automation stability.

Code

examples/python/tests/elements/test_finders.py[R30-36]

+def test_optimized_locator():
+    driver = webdriver.Chrome()
+    driver.get('https://www.selenium.dev/')
+
+    nested_element = driver.find_element(By.CSS_SELECTOR, '.td-home #announcement-banner')
+
+    assert nested_element.is_displayed()

Evidence

The new tests navigate to the homepage and use selectors tied to that page’s current layout, while
existing tests demonstrate the established pattern of using stable fixture pages under
/selenium/web/....

examples/python/tests/elements/test_finders.py[5-10]
examples/python/tests/elements/test_finders.py[30-36]
examples/python/tests/elements/test_locators.py[6-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
Tests currently target the public Selenium homepage and assert on its layout-specific selectors, making them sensitive to site redesigns and unrelated deployments.

## Issue Context
Other Python example tests in this repo use `https://www.selenium.dev/selenium/web/...` pages that are intended as stable automation fixtures.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[5-92]
- examples/python/tests/elements/test_locators.py[6-10]

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

---

4. Indented gh-codeblock shortcode 📘 Rule violation ⚙ Maintainability

Description

gh-codeblock shortcode invocations in finders.en.md, finders.ja.md, finders.pt-br.md, and
finders.zh-cn.md are indented, which can prevent Hugo from parsing the shortcode correctly and
break code example rendering.

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[50]

+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L9">}}

Evidence

Compliance rule 2141348 forbids leading whitespace before {{< gh-codeblock in changed Markdown
files, requiring the shortcode to start at column 1. The cited lines in each of the affected files
show the gh-codeblock invocation preceded by spaces, indicating the rule is being violated and
risking incorrect shortcode parsing/rendering.

Rule 2141348: Disallow indentation before gh-codeblock shortcode in Markdown
website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[46-48]
website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[47-49]
website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[49-51]

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 lines must not have any leading whitespace. In `finders.en.md`, `finders.ja.md`, `finders.pt-br.md`, and `finders.zh-cn.md`, the newly added `gh-codeblock` lines are indented.

## Issue Context
PR Compliance requires `{{< gh-codeblock ... >}}` to start at column 1; indentation can stop the shortcode from being parsed/rendered.

## Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[82-84]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[160-162]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[190-192]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[221-223]
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[453-455]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[46-48]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[76-78]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[150-152]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[179-181]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[208-210]
- website_and_docs/content/documentation/webdriver/elements/finders.ja.md[438-440]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[47-49]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[78-80]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[154-156]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[182-184]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[212-214]
- website_and_docs/content/documentation/webdriver/elements/finders.pt-br.md[437-439]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[49-51]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[81-83]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[158-160]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[187-189]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[217-219]
- website_and_docs/content/documentation/webdriver/elements/finders.zh-cn.md[447-449]

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

---

5. Quit not exception-safe 🐞 Bug ☼ Reliability

Description

Each new test constructs a Chrome driver and calls driver.quit() only at the end, so exceptions or
assertion failures before that point will leak browser processes. The repo already provides a pytest
driver fixture that guarantees quit() in teardown, but these tests do not use it.

Code

examples/python/tests/elements/test_finders.py[R5-14]

+def test_basic_finders():
+    driver = webdriver.Chrome()
+    driver.get('https://www.selenium.dev/')
+
+    body_on_page = driver.find_element(By.CLASS_NAME, 'td-home')
+    container_on_page = body_on_page.find_element(By.CLASS_NAME, 'container-fluid')
+
+    assert container_on_page.is_displayed()
+
+    driver.quit()

Evidence

The new tests call driver.quit() after assertions with no finally, so any earlier failure skips
cleanup; the existing driver fixture shows the intended teardown pattern that always quits.

examples/python/tests/elements/test_finders.py[5-15]
examples/python/tests/conftest.py[23-40]

Agent prompt

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

## Issue description
`driver.quit()` is not protected by `try/finally` (or a fixture teardown), so failures can leave Chrome/driver processes running and interfere with later tests or CI stability.

## Issue Context
`examples/python/tests/conftest.py` already defines a `driver` fixture that yields a driver and always calls `quit()` during teardown.

## Fix Focus Areas
- examples/python/tests/elements/test_finders.py[5-92]
- examples/python/tests/conftest.py[23-40]

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

---

Results up to commit c4c51f6 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Shadow root checked too late ✓ Resolved 🐞 Bug ☼ Reliability

Description

In test_evaluating_shadow_DOM, the code queries custom_element.shadow_root before validating it
exists, so the later assertion cannot guard against a missing/unsupported shadow root and the
failure will occur earlier than intended. This also makes the example pattern less robust if the
element/tag changes or the page fixture is updated.

Code

examples/python/tests/elements/test_finders.py[R21-26]

+    custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element')
+    shadow_dom_input = custom_element.shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]')
+
+    assert custom_element.is_displayed()
+    assert custom_element.shadow_root
+    assert shadow_dom_input.is_displayed()

Evidence

The test dereferences custom_element.shadow_root to find an element, and only afterwards asserts
the shadow root exists, so the assertion cannot prevent an earlier failure if shadow_root is
missing or unsupported.

examples/python/tests/elements/test_finders.py[16-26]

Agent prompt

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

### Issue description
`test_evaluating_shadow_DOM` calls `custom_element.shadow_root.find_element(...)` before checking that `shadow_root` is present. If the host element does not have a shadow root (or the driver/page changes), the test will fail before reaching the assertion meant to validate shadow root existence.

### Issue Context
This test file is also referenced by docs via `gh-codeblock`, so the ordering here influences the robustness of the example pattern.

### Fix Focus Areas
- examples/python/tests/elements/test_finders.py[21-26]

### Suggested change
Assign the shadow root to a variable and assert it before using it:

```python
custom_element = driver.find_element(By.TAG_NAME, 'custom-checkbox-element')
shadow_root = custom_element.shadow_root
assert shadow_root
shadow_dom_input = shadow_root.find_element(By.CSS_SELECTOR, 'input[type=checkbox]')
```

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

---

Results up to commit 9ca4b34 ⚖️ Balanced

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Skipped examples use undefined driver ✓ Resolved 🐞 Bug ≡ Correctness

Description

examples/python/tests/elements/test_finders.py contains skipped “illustrative” functions that
reference driver without defining it or accepting the existing pytest driver fixture parameter,
so the example code is not internally consistent and will raise NameError if executed/copied
as-is. This is especially risky because the docs now embed these exact lines via gh-codeblock,
making the undefined symbol the canonical snippet source.

Code

examples/python/tests/elements/test_finders.py[R21-39]

+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_basic_finders():
+    vegetable = driver.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_subset_of_dom():
+    fruits = driver.find_element(By.ID, 'fruits')
+    fruit = fruits.find_element(By.CLASS_NAME, 'tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_optimized_locator():
+    fruit = driver.find_element(By.CSS_SELECTOR, '#fruits .tomatoes')
+
+
+@pytest.mark.skip(reason="illustrative example, not an executable test")
+def test_all_matching_elements():
+    plants = driver.find_elements(By.TAG_NAME, 'li')

Evidence

The skipped illustrative functions call driver.find_element(...)/driver.find_elements(...)
without defining driver or accepting it as an injected fixture parameter, while the repo’s
conftest.py provides a driver fixture meant to be injected by naming a function parameter
driver.

examples/python/tests/elements/test_finders.py[21-39]
examples/python/tests/conftest.py[25-43]

Agent prompt

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

### Issue description
`test_finders.py` has skipped illustrative functions that reference a `driver` name that is not defined in the function scope. Even though they are skipped, they are still “source of truth” snippets for docs and are one edit away from becoming runnable tests.

### Issue Context
The repo already defines a pytest `driver` fixture that supplies and quits a WebDriver instance. The illustrative examples should either accept this fixture (`def test_x(driver): ...`) or otherwise define `driver` locally to avoid undefined-name examples.

### Fix Focus Areas
- examples/python/tests/elements/test_finders.py[21-39]
- examples/python/tests/conftest.py[25-43]

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

---

2. Python docs require CI token 🐞 Bug ☼ Reliability

Description

The finders docs now embed Python snippets via gh-codeblock, but that shortcode only renders
fetched code when SELENIUM_CI_TOKEN is set; otherwise it renders a “token not set” alert instead
of code. This makes local documentation builds lose the Python examples on the updated pages (and
any environment that doesn’t provide the token).

Code

website_and_docs/content/documentation/webdriver/elements/finders.en.md[R49-51]

+  {{< tab header="Python" text=true >}}
+  {{< gh-codeblock path="/examples/python/tests/elements/test_finders.py#L23">}}
  {{< /tab >}}

Evidence

The updated docs pages call gh-codeblock for Python, and the shortcode implementation gates remote
fetching on SELENIUM_CI_TOKEN; when unset it falls back to a partial that renders an alert instead
of code.

website_and_docs/content/documentation/webdriver/elements/finders.en.md[44-52]
website_and_docs/content/documentation/webdriver/elements/finders.ja.md[42-48]
website_and_docs/layouts/shortcodes/gh-codeblock.html[32-41]
website_and_docs/layouts/shortcodes/gh-codeblock.html[178-180]
website_and_docs/layouts/partials/github-content.html[1-18]

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` currently requires `SELENIUM_CI_TOKEN` to fetch and render code; without it, it renders an alert instead of the code snippet. This PR expands `gh-codeblock` usage for Python examples, increasing the number of docs sections that won’t render code in local builds.

### Issue Context
The code being referenced lives in this same repository. A practical fallback is to render from the local filesystem (Hugo `readFile`) when available, or attempt unauthenticated `GetRemote` when the token is missing.

### Fix Focus Areas
- website_and_docs/content/documentation/webdriver/elements/finders.en.md[49-51]
- website_and_docs/layouts/shortcodes/gh-codeblock.html[32-41]
- website_and_docs/layouts/partials/github-content.html[1-18]

ⓘ 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 c4c51f6

[qodo-code-review]

Code review by qodo was updated up to the latest commit 9ca4b34

[qodo-code-review]

Code review by qodo was updated up to the latest commit 6eb6f9f