fluent-selectors 0.1.0__tar.gz

fluent_selectors-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.3
+Name: fluent-selectors
+Version: 0.1.0
+Summary: A Python library for creating a readable, fluent API for Selenium browser automation
+Keywords: fluent,selectors,testing,assertions,validation
+Author: vantorrewannes
+Author-email: vantorrewannes <vantorrewannes@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Dist: fluent-checks>=0.1.1
+Requires-Dist: selenium>=4.35.0
+Requires-Python: >=3.12
+Project-URL: Bug Tracker, https://github.com/VantorreWannes/fluent-selectors/issues
+Project-URL: Homepage, https://github.com/VantorreWannes/fluent-selectors
+Description-Content-Type: text/markdown
+
+# Fluent Selectors
+
+A Python library for creating a readable, fluent API for Selenium browser automation.
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install fluent-selectors
+```
+
+## Usage
+
+Here's a simple example of how to use `fluent-selectors`:
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from fluent_selectors import Selector
+
+# Initialize the WebDriver
+driver = webdriver.Chrome()
+driver.get("http://www.python.org")
+
+# Create a Selector instance
+s = Selector(driver)
+
+# Select an element and interact with it
+search_bar = s.select((By.NAME, "q"))
+search_bar.set_text("pycon")
+
+go_button = s.select((By.ID, "submit"))
+go_button.click()
+
+# Perform checks
+s.select((By.CLASS_NAME, "list-recent-events")).is_displayed.is_true()
+
+driver.quit()
+```
+
+## API
+
+### `Selector(driver: WebDriver, *locators: Locator)`
+
+The main class for selecting and interacting with elements.
+
+-   `select(locator: Locator) -> Selector`: Select a descendant of the current element.
+-   `child(index: int) -> Selector`: Select a child by its index.
+-   `children() -> list[Selector]`: Get a list of all children.
+-   `parent() -> Selector | None`: Get the parent selector.
+-   `parents() -> list[Selector]`: Get a list of all parent selectors.
+
+### Element Actions
+
+-   `click()`: Clicks the element.
+-   `type_text(text: str)`: Types text into the element.
+-   `clear()`: Clears the text from the element.
+-   `set_text(text: str)`: Clears the element and then types text into it.
+-   `upload_file(path: Path)`: Uploads a file to a file input element.
+-   `scroll_into_view()`: Scrolls the element into view.
+
+### Element Properties
+
+-   `element() -> WebElement | None`: The Selenium WebElement.
+-   `elements() -> list[WebElement]`: A list of Selenium WebElements.
+-   `text() -> str | None`: The text of the element.
+-   `tag_name() -> str | None`: The tag name of the element.
+-   `accessible_name() -> str | None`: The accessible name of the element.
+-   `aria_role() -> str | None`: The ARIA role of the element.
+-   `id() -> str | None`: The ID of the element.
+-   `location() -> Location | None`: The location of the element.
+-   `size() -> Size | None`: The size of the element.
+-   `attribute(name: str) -> str | None`: The value of an attribute.
+
+### Checks
+
+You can perform checks on selectors using the following properties. These checks are based on the [fluent-checks](https://github.com/VantorreWannes/fluent-checks) library.
+
+-   `is_present()`: Checks if the element is present in the DOM.
+-   `is_displayed()`: Checks if the element is visible.
+-   `is_enabled()`: Checks if the element is enabled.
+-   `is_selected()`: Checks if the element is selected.
+-   `has_text(text: str)`: Checks if the element's text contains the given text.
+-   `has_exact_text(text: str)`: Checks if the element's text exactly matches the given text.
+-   `has_attribute(name: str)`: Checks if the element has the given attribute.
+
+Example of a check:
+
+```python
+s.select((By.ID, "my-element")).is_displayed.is_true()
+s.select((By.ID, "my-element")).has_text("Hello").is_true()
+```
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

fluent_selectors-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Fluent Selectors
+
+A Python library for creating a readable, fluent API for Selenium browser automation.
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install fluent-selectors
+```
+
+## Usage
+
+Here's a simple example of how to use `fluent-selectors`:
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from fluent_selectors import Selector
+
+# Initialize the WebDriver
+driver = webdriver.Chrome()
+driver.get("http://www.python.org")
+
+# Create a Selector instance
+s = Selector(driver)
+
+# Select an element and interact with it
+search_bar = s.select((By.NAME, "q"))
+search_bar.set_text("pycon")
+
+go_button = s.select((By.ID, "submit"))
+go_button.click()
+
+# Perform checks
+s.select((By.CLASS_NAME, "list-recent-events")).is_displayed.is_true()
+
+driver.quit()
+```
+
+## API
+
+### `Selector(driver: WebDriver, *locators: Locator)`
+
+The main class for selecting and interacting with elements.
+
+-   `select(locator: Locator) -> Selector`: Select a descendant of the current element.
+-   `child(index: int) -> Selector`: Select a child by its index.
+-   `children() -> list[Selector]`: Get a list of all children.
+-   `parent() -> Selector | None`: Get the parent selector.
+-   `parents() -> list[Selector]`: Get a list of all parent selectors.
+
+### Element Actions
+
+-   `click()`: Clicks the element.
+-   `type_text(text: str)`: Types text into the element.
+-   `clear()`: Clears the text from the element.
+-   `set_text(text: str)`: Clears the element and then types text into it.
+-   `upload_file(path: Path)`: Uploads a file to a file input element.
+-   `scroll_into_view()`: Scrolls the element into view.
+
+### Element Properties
+
+-   `element() -> WebElement | None`: The Selenium WebElement.
+-   `elements() -> list[WebElement]`: A list of Selenium WebElements.
+-   `text() -> str | None`: The text of the element.
+-   `tag_name() -> str | None`: The tag name of the element.
+-   `accessible_name() -> str | None`: The accessible name of the element.
+-   `aria_role() -> str | None`: The ARIA role of the element.
+-   `id() -> str | None`: The ID of the element.
+-   `location() -> Location | None`: The location of the element.
+-   `size() -> Size | None`: The size of the element.
+-   `attribute(name: str) -> str | None`: The value of an attribute.
+
+### Checks
+
+You can perform checks on selectors using the following properties. These checks are based on the [fluent-checks](https://github.com/VantorreWannes/fluent-checks) library.
+
+-   `is_present()`: Checks if the element is present in the DOM.
+-   `is_displayed()`: Checks if the element is visible.
+-   `is_enabled()`: Checks if the element is enabled.
+-   `is_selected()`: Checks if the element is selected.
+-   `has_text(text: str)`: Checks if the element's text contains the given text.
+-   `has_exact_text(text: str)`: Checks if the element's text exactly matches the given text.
+-   `has_attribute(name: str)`: Checks if the element has the given attribute.
+
+Example of a check:
+
+```python
+s.select((By.ID, "my-element")).is_displayed.is_true()
+s.select((By.ID, "my-element")).has_text("Hello").is_true()
+```
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

fluent_selectors-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "fluent-selectors"
+version = "0.1.0"
+description = "A Python library for creating a readable, fluent API for Selenium browser automation"
+readme = "README.md"
+authors = [{ name = "vantorrewannes", email = "vantorrewannes@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = ["fluent-checks>=0.1.1", "selenium>=4.35.0"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Utilities",
+]
+keywords = ["fluent", "selectors", "testing", "assertions", "validation"]
+
+
+[project.urls]
+Homepage = "https://github.com/VantorreWannes/fluent-selectors"
+"Bug Tracker" = "https://github.com/VantorreWannes/fluent-selectors/issues"
+
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+pythonpath = "."
+testpaths = "tests"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+fixable = ["ALL"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+dev = ["pytest>=8.4.1", "pytest-httpserver>=1.1.3", "webdriver-manager>=4.0.2"]

fluent_selectors-0.1.0/src/fluent_selectors/__init__.py

@@ -0,0 +1,234 @@
+import os
+from abc import ABC
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+from typing import Optional, Union
+
+from fluent_checks import Check
+from selenium.common import NoSuchElementException
+from selenium.webdriver.common.by import By
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.remote.webelement import WebElement
+
+type Locator = tuple[str, str]
+
+SELF_LOCATOR: Locator = (By.XPATH, ".")
+CHILDREN_LOCATOR: Locator = (By.XPATH, "./*")
+
+
+@dataclass
+class Location:
+    x: int
+    y: int
+
+
+@dataclass
+class Size:
+    x: float
+    y: float
+
+
+class Selector(ABC):
+    def __init__(self, driver: WebDriver, *locators: Locator) -> None:
+        super().__init__()
+        self._driver: WebDriver = driver
+        self._locators: tuple[Locator, ...] = locators or (SELF_LOCATOR,)
+        self._locator: Locator = self._locators[-1]
+
+    @cached_property
+    def parent(self) -> Optional["Selector"]:
+        if len(self._locators) > 1:
+            return Selector(self._driver, *self._locators[:-1])
+
+    @cached_property
+    def parents(self) -> list["Selector"]:
+        if parent := self.parent:
+            return [parent, *parent.parents]
+        return []
+
+    @property
+    def _context(self) -> Union[WebDriver, WebElement, None]:
+        if self.parent:
+            return self.parent.element
+        return self._driver
+
+    @property
+    def element(self) -> Optional[WebElement]:
+        try:
+            context = self._context
+            if context:
+                return context.find_element(*self._locator)
+            return None
+        except NoSuchElementException:
+            return None
+
+    @property
+    def elements(self) -> list[WebElement]:
+        try:
+            context = self._context
+            if context:
+                return context.find_elements(*self._locator)
+            return []
+        except NoSuchElementException:
+            return []
+
+    def select(self, locator: Locator) -> "Selector":
+        return Selector(self._driver, *self._locators, locator)
+
+    def child(self, index: int) -> "Selector":
+        locator: Locator = (By.XPATH, f"({CHILDREN_LOCATOR[1]})[{index + 1}]")
+        return Selector(self._driver, *self._locators, locator)
+
+    def children(self) -> list["Selector"]:
+        num_children = len(self.select(CHILDREN_LOCATOR).elements)
+        return [self.child(index) for index in range(num_children)]
+
+    def click(self):
+        if element := self.element:
+            element.click()
+
+    def type_text(self, text: str):
+        if element := self.element:
+            element.send_keys(text)
+
+    def clear(self):
+        if element := self.element:
+            element.clear()
+
+    def set_text(self, text: str):
+        self.clear()
+        self.type_text(text)
+
+    def upload_file(self, path: Path):
+        self.set_text(os.path.abspath(path))
+
+    @property
+    def text(self) -> Optional[str]:
+        if element := self.element:
+            return element.text
+
+    @property
+    def tag_name(self) -> Optional[str]:
+        if element := self.element:
+            return element.tag_name
+
+    @property
+    def accessible_name(self) -> Optional[str]:
+        if element := self.element:
+            return element.accessible_name
+
+    @property
+    def aria_role(self) -> Optional[str]:
+        if element := self.element:
+            return element.aria_role
+
+    @property
+    def id(self) -> Optional[str]:
+        if element := self.element:
+            return element.id
+
+    @property
+    def location(self) -> Optional[Location]:
+        if element := self.element:
+            location = element.location
+            return Location(location["x"], location["y"])
+
+    @property
+    def size(self) -> Optional[Size]:
+        if element := self.element:
+            size = element.size
+            return Size(size["width"], size["height"])
+
+    def scroll_into_view(self) -> None:
+        if element := self.element:
+            self._driver.execute_script("arguments[0].scrollIntoView(true);", element)
+
+    def attribute(self, name: str) -> Optional[str]:
+        if element := self.element:
+            return element.get_attribute(name)
+
+    @property
+    def is_present(self) -> "IsPresentCheck":
+        return IsPresentCheck(self)
+
+    @property
+    def is_displayed(self) -> "IsDisplayedCheck":
+        return IsDisplayedCheck(self)
+
+    @property
+    def is_enabled(self) -> "IsEnabledCheck":
+        return IsEnabledCheck(self)
+
+    @property
+    def is_selected(self) -> "IsSelectedCheck":
+        return IsSelectedCheck(self)
+
+    def has_text(self, text: str) -> "HasTextCheck":
+        return HasTextCheck(self, text)
+
+    def has_exact_text(self, text: str) -> "HasExactTextCheck":
+        return HasExactTextCheck(self, text)
+
+    def has_attribute(self, name: str) -> "HasAttributeCheck":
+        return HasAttributeCheck(self, name)
+
+
+class IsPresentCheck(Check):
+    def __init__(self, selector: Selector) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(lambda: True if element is not None else False)
+        self._selector: Selector = selector
+
+
+class IsDisplayedCheck(Check):
+    def __init__(self, selector: Selector) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(
+            lambda: element.is_displayed() if element is not None else False
+        )
+        self._selector: Selector = selector
+
+
+class IsEnabledCheck(Check):
+    def __init__(self, selector: Selector) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(lambda: element.is_enabled() if element is not None else False)
+        self._selector: Selector = selector
+
+
+class IsSelectedCheck(Check):
+    def __init__(self, selector: Selector) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(
+            lambda: element.is_selected() if element is not None else False
+        )
+        self._selector: Selector = selector
+
+
+class HasTextCheck(Check):
+    def __init__(self, selector: Selector, text: str) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(lambda: text in element.text if element is not None else False)
+        self._selector: Selector = selector
+        self._text: str = text
+
+
+class HasExactTextCheck(Check):
+    def __init__(self, selector: Selector, text: str) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(lambda: text == element.text if element is not None else False)
+        self._selector: Selector = selector
+        self._text: str = text
+
+
+class HasAttributeCheck(Check):
+    def __init__(self, selector: Selector, name: str) -> None:
+        element: WebElement | None = selector.element
+        super().__init__(
+            lambda: bool(element.get_attribute(self._name))
+            if element is not None
+            else False
+        )
+        self._selector: Selector = selector
+        self._name = name