Metadata-Version: 2.3
Name: fluent-selectors
Version: 0.1.7
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.2.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.

#### Traversal and Selection

-   `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 selectors.
-   `parent: Selector | None`: The parent selector.
-   `parents: list[Selector]`: 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

These methods return `Check` objects from 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.
-   `is_stale`: Checks if the element is stale.
-   `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.
-   `has_attribute_value(name: str, value: str)`: Checks if the attribute has the given value.

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.