Added section on ByChained

shbenzer commented 2 weeks ago

User description

Added a section on ByChained to the documentation

Description

Split the By section into two subsections: By and ByChained Added description of ByChained Added code example to ByChained Added to all translations

Motivation and Context

Makes documentation more comprehensive Provides code examples for features

Types of changes

[x] 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

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

PR Type

Documentation

Description

Introduced a new section ByChained in the documentation for multiple languages (English, Japanese, Portuguese, and Chinese).
Provided an HTML example to demonstrate the use of ByChained for element location.
Added a Java code example to illustrate how to implement ByChained.
Enhanced the documentation to make it more comprehensive by explaining the chaining of locators.

Changes walkthrough 📝

Relevant files

Documentation

locators.en.md Add `ByChained` section with example in English documentation website_and_docs/content/documentation/webdriver/elements/locators.en.md Added a new section titled `ByChained`. Provided an HTML example to illustrate usage. Included a Java code example for `ByChained`.	+44/-0
locators.ja.md Add `ByChained` section with example in Japanese documentation website_and_docs/content/documentation/webdriver/elements/locators.ja.md Added a new section titled `ByChained`. Provided an HTML example to illustrate usage. Included a Java code example for `ByChained`.	+42/-0
locators.pt-br.md Add `ByChained` section with example in Portuguese documentation website_and_docs/content/documentation/webdriver/elements/locators.pt-br.md Added a new section titled `ByChained`. Provided an HTML example to illustrate usage. Included a Java code example for `ByChained`.	+44/-0
locators.zh-cn.md Add `ByChained` section with example in Chinese documentation website_and_docs/content/documentation/webdriver/elements/locators.zh-cn.md Added a new section titled `ByChained`. Provided an HTML example to illustrate usage. Included a Java code example for `ByChained`.	+44/-0

💡 PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

netlify[bot] commented 2 weeks ago

Deploy request for selenium-dev pending review.

Visit the deploys page to approve it

Name	Link
Latest commit	be456bf316485d6e64555d425e64e350f5195e4e

codiumai-pr-agent-pro[bot] commented 2 weeks ago

PR Reviewer Guide 🔍

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review

Incomplete Code Examples
The ByChained section only includes a Java code example. Examples for other languages (Python, CSharp, Ruby, JavaScript, Kotlin) are missing. Untranslated Content
The newly added ByChained section is not translated to Japanese. It remains in English, which may confuse Japanese readers. Untranslated Content
The newly added ByChained section is not translated to Portuguese. It remains in English, which may confuse Portuguese readers. Untranslated Content
The newly added ByChained section is not translated to Chinese. It remains in English, which may confuse Chinese readers.

shbenzer commented 2 weeks ago

This PR also covers #1287

codiumai-pr-agent-pro[bot] commented 2 weeks ago

PR Code Suggestions ✨

Category	Suggestion	Score
Enhancement	Add code examples for multiple programming languages to improve documentation comprehensiveness ___ Consider adding examples for other programming languages supported by Selenium, such as Python, C#, Ruby, JavaScript, and Kotlin. This will make the documentation more comprehensive and useful for developers using different languages. [website_and_docs/content/documentation/webdriver/elements/locators.en.md [388-411]](https://github.com/SeleniumHQ/seleniumhq.github.io/pull/1911/files#diff-bad5c08d78f84e8bd7528d1a2a3181973375147d3f8bc5b9678cfce7dbe76aabR388-R411) ```diff {{< tabpane langEqualsHeader=true >}} {{< badge-examples >}} {{< tab header="Java" >}} import org.openqa.selenium.By; import org.openqa.selenium.support.pagefactory.ByChained; By example = new ByChained(By.id("parentDiv"), By.id("phoneNumber")); driver.findElements(example); {{< /tab >}} - {{< tab header="Python" text=true >}} - {{< badge-code >}} + {{< tab header="Python" >}} + from selenium.webdriver.common.by import By + from selenium.webdriver.support.ui import WebDriverWait + from selenium.webdriver.support import expected_conditions as EC + + example = (By.ID, "parentDiv", By.ID, "phoneNumber") + element = WebDriverWait(driver, 10).until( + EC.presence_of_element_located(example) + ) {{< /tab >}} - {{< tab header="CSharp" text=true >}} - {{< badge-code >}} + {{< tab header="CSharp" >}} + using OpenQA.Selenium; + using OpenQA.Selenium.Support.UI; + + var example = new ByChained(By.Id("parentDiv"), By.Id("phoneNumber")); + var element = driver.FindElement(example); {{< /tab >}} - {{< tab header="Ruby" text=true >}} - {{< badge-code >}} + {{< tab header="Ruby" >}} + require 'selenium-webdriver' + + example = [:id, 'parentDiv', :id, 'phoneNumber'] + element = driver.find_element(example) {{< /tab >}} - {{< tab header="JavaScript" text=true >}} - {{< badge-code >}} + {{< tab header="JavaScript" >}} + const { By } = require('selenium-webdriver'); + + const example = By.js('return document.querySelector("#parentDiv #phoneNumber")'); + const element = await driver.findElement(example); {{< /tab >}} - {{< tab header="Kotlin" text=true >}} - {{< badge-code >}} + {{< tab header="Kotlin" >}} + import org.openqa.selenium.By + import org.openqa.selenium.support.pagefactory.ByChained + + val example = ByChained(By.id("parentDiv"), By.id("phoneNumber")) + val element = driver.findElement(example) {{< /tab >}} {{< /tabpane >}} ``` - [ ] Apply this suggestion* Suggestion importance[1-10]: 8 Why: Adding examples for multiple programming languages significantly enhances the documentation's utility for a broader audience, making it more inclusive and comprehensive for developers using different languages.	8
Enhancement	✅ Add an explanation of the ByChained class and its purpose ___ Suggestion Impact: The commit added an explanation of the ByChained class, describing its purpose and how it can be used to chain two By locators together, which aligns with the suggestion to provide context and understanding of the ByChained strategy. code diff: ```diff ### ByChained -Say, for example, you had the following html: ``` ___ Consider adding a brief explanation of the `ByChained` class and its purpose before the HTML example. This will help readers understand why they might want to use this locator strategy. [website_and_docs/content/documentation/webdriver/elements/locators.en.md [371-373]](https://github.com/SeleniumHQ/seleniumhq.github.io/pull/1911/files#diff-bad5c08d78f84e8bd7528d1a2a3181973375147d3f8bc5b9678cfce7dbe76aabR371-R373) ```diff ### ByChained + +The `ByChained` class allows you to chain multiple locator strategies together, creating a more specific and robust way to locate elements. This is particularly useful when you need to find elements within a specific context or when dealing with duplicate IDs or classes in different parts of the page. Say, for example, you had the following html: ``` - [ ] Apply this suggestion Suggestion importance[1-10]: 7 Why: Providing an explanation of the `ByChained` class and its purpose improves the documentation by giving readers context and understanding of when and why to use this strategy, enhancing clarity and educational value.	7
Best practice	Add a note about the performance implications of using ByChained ___ Consider adding a note about the performance implications of using `ByChained` compared to other locator strategies. This will help users make informed decisions about when to use this approach. [website_and_docs/content/documentation/webdriver/elements/locators.en.md [386]](https://github.com/SeleniumHQ/seleniumhq.github.io/pull/1911/files#diff-bad5c08d78f84e8bd7528d1a2a3181973375147d3f8bc5b9678cfce7dbe76aabR386-R386) ```diff and you need to access the input of type text, instead of the input of type number. With ByChained you can access the desired input by chaining two Bys together, first to the div with `id="parentDiv"` and from that div to its child: `id="phoneNumber"`. +Note: While `ByChained` provides a powerful way to locate elements, it may have a performance impact compared to simpler locator strategies. Use it judiciously, especially when dealing with large DOM structures or when performance is a critical concern. + ``` - [ ] Apply this suggestion Suggestion importance[1-10]: 6 Why: Including a note about performance implications is a valuable addition that helps users make informed decisions, although it is not as critical as providing language examples or basic explanations.	6

shbenzer commented 2 weeks ago

If the response to this is positive, I will add a section on ByAll

SeleniumHQ / seleniumhq.github.io