# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "fluent-selectors",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "fluent, selectors, testing, assertions, validation",
"author": "vantorrewannes",
"author_email": "vantorrewannes <vantorrewannes@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dc/a4/0d9f63eec7dfc6bdee9b79eec4de1624201c39baca61b5f303be821a8b0b/fluent_selectors-0.1.7.tar.gz",
"platform": null,
"description": "# Fluent Selectors\n\nA Python library for creating a readable, fluent API for Selenium browser automation.\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install fluent-selectors\n```\n\n## Usage\n\nHere's a simple example of how to use `fluent-selectors`:\n\n```python\nfrom selenium import webdriver\nfrom selenium.webdriver.common.by import By\nfrom fluent_selectors import Selector\n\n# Initialize the WebDriver\ndriver = webdriver.Chrome()\ndriver.get(\"http://www.python.org\")\n\n# Create a Selector instance\ns = Selector(driver)\n\n# Select an element and interact with it\nsearch_bar = s.select((By.NAME, \"q\"))\nsearch_bar.set_text(\"pycon\")\n\ngo_button = s.select((By.ID, \"submit\"))\ngo_button.click()\n\n# Perform checks\ns.select((By.CLASS_NAME, \"list-recent-events\")).is_displayed.is_true()\n\ndriver.quit()\n```\n\n## API\n\n### `Selector(driver: WebDriver, *locators: Locator)`\n\nThe main class for selecting and interacting with elements.\n\n#### Traversal and Selection\n\n- `select(locator: Locator) -> Selector`: Select a descendant of the current element.\n- `child(index: int) -> Selector`: Select a child by its index.\n- `children() -> list[Selector]`: Get a list of all children selectors.\n- `parent: Selector | None`: The parent selector.\n- `parents: list[Selector]`: A list of all parent selectors.\n\n#### Element Actions\n\n- `click()`: Clicks the element.\n- `type_text(text: str)`: Types text into the element.\n- `clear()`: Clears the text from the element.\n- `set_text(text: str)`: Clears the element and then types text into it.\n- `upload_file(path: Path)`: Uploads a file to a file input element.\n- `scroll_into_view()`: Scrolls the element into view.\n\n#### Element Properties\n\n- `element: WebElement | None`: The Selenium WebElement.\n- `elements: list[WebElement]`: A list of Selenium WebElements.\n- `text: str | None`: The text of the element.\n- `tag_name: str | None`: The tag name of the element.\n- `accessible_name: str | None`: The accessible name of the element.\n- `aria_role: str | None`: The ARIA role of the element.\n- `id: str | None`: The ID of the element.\n- `location: Location | None`: The location of the element.\n- `size: Size | None`: The size of the element.\n- `attribute(name: str) -> str | None`: The value of an attribute.\n\n#### Checks\n\nThese methods return `Check` objects from the [fluent-checks](https://github.com/VantorreWannes/fluent-checks) library.\n\n- `is_present`: Checks if the element is present in the DOM.\n- `is_displayed`: Checks if the element is visible.\n- `is_enabled`: Checks if the element is enabled.\n- `is_selected`: Checks if the element is selected.\n- `is_stale`: Checks if the element is stale.\n- `has_text(text: str)`: Checks if the element's text contains the given text.\n- `has_exact_text(text: str)`: Checks if the element's text exactly matches the given text.\n- `has_attribute(name: str)`: Checks if the element has the given attribute.\n- `has_attribute_value(name: str, value: str)`: Checks if the attribute has the given value.\n\nExample of a check:\n\n```python\ns.select((By.ID, \"my-element\")).is_displayed.is_true()\ns.select((By.ID, \"my-element\")).has_text(\"Hello\").is_true()\n```\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for creating a readable, fluent API for Selenium browser automation",
"version": "0.1.7",
"project_urls": {
"Bug Tracker": "https://github.com/VantorreWannes/fluent-selectors/issues",
"Homepage": "https://github.com/VantorreWannes/fluent-selectors"
},
"split_keywords": [
"fluent",
" selectors",
" testing",
" assertions",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "45ba07e247bbe9896bb8ab252e810ee7bf74f1e197e46ae54d447bd578d913db",
"md5": "245b22d9453e6d64a9ef3daeb6fbf120",
"sha256": "e0f6c2ec67995f0f62a5eae6274977370d2ed5e6da92eec755a91b87b107b347"
},
"downloads": -1,
"filename": "fluent_selectors-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "245b22d9453e6d64a9ef3daeb6fbf120",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 4500,
"upload_time": "2025-08-30T13:39:22",
"upload_time_iso_8601": "2025-08-30T13:39:22.369010Z",
"url": "https://files.pythonhosted.org/packages/45/ba/07e247bbe9896bb8ab252e810ee7bf74f1e197e46ae54d447bd578d913db/fluent_selectors-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dca40d9f63eec7dfc6bdee9b79eec4de1624201c39baca61b5f303be821a8b0b",
"md5": "cba15bb5f907d9aca7cc6e6d5487faad",
"sha256": "b2030781491d320e48300b4869dfdd14b97064cb927d3e9c7c85c63a9f38b16c"
},
"downloads": -1,
"filename": "fluent_selectors-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "cba15bb5f907d9aca7cc6e6d5487faad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 3790,
"upload_time": "2025-08-30T13:39:23",
"upload_time_iso_8601": "2025-08-30T13:39:23.478652Z",
"url": "https://files.pythonhosted.org/packages/dc/a4/0d9f63eec7dfc6bdee9b79eec4de1624201c39baca61b5f303be821a8b0b/fluent_selectors-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 13:39:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "VantorreWannes",
"github_project": "fluent-selectors",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fluent-selectors"
}
JSON
