diff --git a/py/selenium/webdriver/remote/shadowroot.py b/py/selenium/webdriver/remote/shadowroot.py index c9a5f81d43c05..e78167356f6b5 100644 --- a/py/selenium/webdriver/remote/shadowroot.py +++ b/py/selenium/webdriver/remote/shadowroot.py @@ -40,6 +40,32 @@ def __repr__(self) -> str: ) def find_element(self, by: str = By.ID, value: str = None): + """Find an element inside a shadow root given a By strategy and + locator. + + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') + + Returns: + ------- + WebElement + The first matching `WebElement` found on the page. + """ if by == By.ID: by = By.CSS_SELECTOR value = f'[id="{value}"]' @@ -53,6 +79,31 @@ def find_element(self, by: str = By.ID, value: str = None): return self._execute(Command.FIND_ELEMENT_FROM_SHADOW_ROOT, {"using": by, "value": value})["value"] def find_elements(self, by: str = By.ID, value: str = None): + """Find elements inside a shadow root given a By strategy and locator. + + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') + + Returns: + ------- + WebElement + list of `WebElements` matching locator strategy found on the page. + """ if by == By.ID: by = By.CSS_SELECTOR value = f'[id="{value}"]' diff --git a/py/selenium/webdriver/remote/webdriver.py b/py/selenium/webdriver/remote/webdriver.py index 564fb465369df..d40a98d01b9fc 100644 --- a/py/selenium/webdriver/remote/webdriver.py +++ b/py/selenium/webdriver/remote/webdriver.py @@ -772,12 +772,28 @@ def timeouts(self, timeouts) -> None: def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement: """Find an element given a By strategy and locator. - :Usage: - :: + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') - element = driver.find_element(By.ID, 'foo') - - :rtype: WebElement + Returns: + ------- + WebElement + The first matching `WebElement` found on the page. """ by, value = self.locator_converter.convert(by, value) @@ -792,12 +808,28 @@ def find_element(self, by=By.ID, value: Optional[str] = None) -> WebElement: def find_elements(self, by=By.ID, value: Optional[str] = None) -> List[WebElement]: """Find elements given a By strategy and locator. - :Usage: - :: + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') - elements = driver.find_elements(By.CLASS_NAME, 'foo') - - :rtype: list of WebElement + Returns: + ------- + WebElement + list of `WebElements` matching locator strategy found on the page. """ by, value = self.locator_converter.convert(by, value) diff --git a/py/selenium/webdriver/remote/webelement.py b/py/selenium/webdriver/remote/webelement.py index 08c772eaad56e..f2b672ec17736 100644 --- a/py/selenium/webdriver/remote/webelement.py +++ b/py/selenium/webdriver/remote/webelement.py @@ -397,12 +397,28 @@ def _execute(self, command, params=None): def find_element(self, by=By.ID, value=None) -> WebElement: """Find an element given a By strategy and locator. - :Usage: - :: + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') - element = element.find_element(By.ID, 'foo') - - :rtype: WebElement + Returns: + ------- + WebElement + The first matching `WebElement` found on the page. """ by, value = self._parent.locator_converter.convert(by, value) return self._execute(Command.FIND_CHILD_ELEMENT, {"using": by, "value": value})["value"] @@ -410,12 +426,28 @@ def find_element(self, by=By.ID, value=None) -> WebElement: def find_elements(self, by=By.ID, value=None) -> List[WebElement]: """Find elements given a By strategy and locator. - :Usage: - :: + Parameters: + ---------- + by : selenium.webdriver.common.by.By + The locating strategy to use. Default is `By.ID`. Supported values include: + - By.ID: Locate by element ID. + - By.NAME: Locate by the `name` attribute. + - By.XPATH: Locate by an XPath expression. + - By.CSS_SELECTOR: Locate by a CSS selector. + - By.CLASS_NAME: Locate by the `class` attribute. + - By.TAG_NAME: Locate by the tag name (e.g., "input", "button"). + - By.LINK_TEXT: Locate a link element by its exact text. + - By.PARTIAL_LINK_TEXT: Locate a link element by partial text match. + - RelativeBy: Locate elements relative to a specified root element. + + Example: + -------- + element = driver.find_element(By.ID, 'foo') - element = element.find_elements(By.CLASS_NAME, 'foo') - - :rtype: list of WebElement + Returns: + ------- + WebElement + list of `WebElements` matching locator strategy found on the page. """ by, value = self._parent.locator_converter.convert(by, value) return self._execute(Command.FIND_CHILD_ELEMENTS, {"using": by, "value": value})["value"]