selenium-testing-library


Nameselenium-testing-library JSON
Version 2021.8.4b0 PyPI version JSON
download
home_pagehttps://github.com/Smotko/selenium-testing-library
SummaryA Python Selenium library inspired by the Testing Library
upload_time2021-08-04 02:18:16
maintainer
docs_urlNone
authorAnže Pečar
requires_python>=3.6,<4.0
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            # Selenium Testing Library

[![PyPI version](https://badge.fury.io/py/selenium-testing-library.svg)](https://badge.fury.io/py/selenium-testing-library)
[![test](https://github.com/Smotko/selenium-testing-library/actions/workflows/main.yml/badge.svg)](https://github.com/Smotko/selenium-testing-library/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/Smotko/selenium-testing-library/branch/main/graph/badge.svg?token=L1M7HO3DL7)](https://codecov.io/gh/Smotko/selenium-testing-library)

Slenium Testing Library (STL) is a Python library for Selenium inspired by [Testing-Library](https://testing-library.com/).

## Dependencies

* Python 3.6, 3.7, 3.8, 3.9
* Selenium > 3.0.0

## Installation

```
pip install selenium-testing-library
```

## Quick Start

```python
from selenium import webdriver
from selenium_testing_library import Screen

driver = webdriver.Chrome()
driver.open('https://google.com/')

screen = Screen(driver)
search_input = screen.find_by_title("Search")
search.send_keys("Dogs")
search_button = screen.find_by_text("Google Search")
search_button.click()
screen.wait_for_stale(search_button)
```

## Finding elements

`get_by` returns the element matched and throws an exception if zero or more than one elements matched.
`query_by` returns the element matched or `None` if no element matched. It throws and exception if more than 1 elements matched.
`find_by` behaves like `get_by`, but uses a `WebDriverWait` to wait until the element is present in the DOM.

`get_all_by` returns a list of elements matched. It raises an exception if no elements matched.
`query_all_by` returns a list of elements matched. It returns an empty list when no elements matched.
`find_all_by` behaves like `get_all_by`, but uses a `WebDriverWait` to wait until the elements jare present in the DOM.

Examples:

```python
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium_testing_library import Screen

screen = Screen(webdriver.Chrome())
screen.query_by((By.ID, "my_id")) # you can use regular tuples as if you were using Selenium's find_element()
screen.find_by((By.XPATH, "//div"), timeout=5, poll_frequency=0.5) # locators for searching through text also work
screen.get_by((By.CSS, ".my_class")) # Will throw an exception if the element is not found
```
For a more detail description check out the [Testing-Library](https://testing-library.com/docs/queries/about)'s documentation.

## Helper functions

`get_by_role(role_name)` Queries for elements by given role. Does not currently support default roles.
`get_by_label_text(text)` Queries for label elements that match the the text string and returns the corresponding input element.
`get_by_placeholder_text(text)` Queries elements with the matching placeholder attribute.
`get_by_text(text)` Queries elements where the content matches the provided text.
`get_by_display_value(value)` Queries inputs, textareas, or selects with matching display value.
`get_by_alt_text(text)` Queries elements with the matching alt attribute.
`get_by_title(text)` Queries elements with the matching title attribute.
`get_by_test_id(value)` Queries elements matching the `data-testid` value.
`get_by_css(css)` Queries elements matching the specified css selector.
`get_by_xpath(xpath)` Queries elements matching the specified xpath selector.

Examples:

```python
from selenium import webdriver
from selenium_testing_library import Screen

screen = Screen(webdriver.Chrome())
screen.query_by_role("role_name")
screen.get_by_label_text("label text")
screen.find_all_by_text("my text", timeout=5, poll_frequency=0.5)
screen.get_all_by_alt_text("alt text")
```

## Locators

Locators are utility classes that simplify writing (By.XXX, selector) tuples. They can be used even when using native selenium functions `driver.find_element(locators.Id("my_id"))`.

Available locators:

`Css`, `XPath`, `Id`, `Name`, `TagName`, `LinkText`, `PartialLinkText`, `ClassName`, `Role`, `Text`, `PlaceholderText`, `LabelText`, `AltText`, `Title`, `TestId`, `DisplayValu`

Examples:

```python
from selenium import webdriver
from selenium_testing_library import Screen, locators

screen.query_by(locators.Id("my_id"))
screen.find_by(locators.XPath("//div"), timeout=5, poll_frequency=0.5)
screen.get_by(locators.Css(".my_class"))
screen.get_all_by(locators.Text("my text"))
screen.get_by(locators.LinkText("my link text"))
screen.query_all_by(locators.ClassName("my-class-name"))
```

## Wait functions

`wait_for(condition_function)` Waits until condition function returns a truthy value.
`wait_for_stale(element)` Waits until the element is removed from the DOM.


Examples:

```python
from selenium import webdriver
from selenium_testing_library import Screen, locators

screen = Screen(webdriver.Chrome())

# Wait for the element to be clickable:
element = screen.get_by_text("Submit")
screen.wait_for(lambda _: element.is_enabled(), timeout=5, poll_frequency=0.5)
# Wait for the element to be removed from the page:
screen.wait_for_stale(element)
```

## Querying within elements

`Within(element)` Used to limit the query to the children of the provided element

Example:

```python
from selenium import webdriver
from selenium_testing_library import Screen, Within

screen = Screen(webdriver.Chrome())
parent_element = screen.get_by_css(".container")
Within(parent_element).get_by_title("My title inside the container")
```

# Contributing

Setting up a local development environment

```shell
git clone https://github.com/Smotko/selenium-testing-library.git && cd selenium-testing-library
poetry install && poetry shell
# Make sure `chromedriver` is in your PATH, download from https://chromedriver.chromium.org/downloads
# run tests:
pytest --selenium-headless
# run tests and display coverage info:
pytest --selenium-headless --cov=selenium_testing_library --cov-report html

# To test on multiple Python versions make sure that py37, py38, py39 are
# installed on your system and available through python3.7, python3.8,
# python3.9. (Use pyenv and add the pyenv shims to your path
# `export PATH=$(pyenv root)/shims:$PATH`). Then run tox:
tox
```

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Smotko/selenium-testing-library",
    "name": "selenium-testing-library",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6,<4.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "An\u017ee Pe\u010dar",
    "author_email": "anze@pecar.me",
    "download_url": "https://files.pythonhosted.org/packages/45/74/4f6ffb0ad23347bb48ae0e988bd1e59fe34214096d9016046d50449db7d8/selenium-testing-library-2021.8.4b0.tar.gz",
    "platform": "",
    "description": "# Selenium Testing Library\n\n[![PyPI version](https://badge.fury.io/py/selenium-testing-library.svg)](https://badge.fury.io/py/selenium-testing-library)\n[![test](https://github.com/Smotko/selenium-testing-library/actions/workflows/main.yml/badge.svg)](https://github.com/Smotko/selenium-testing-library/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/Smotko/selenium-testing-library/branch/main/graph/badge.svg?token=L1M7HO3DL7)](https://codecov.io/gh/Smotko/selenium-testing-library)\n\nSlenium Testing Library (STL) is a Python library for Selenium inspired by [Testing-Library](https://testing-library.com/).\n\n## Dependencies\n\n* Python 3.6, 3.7, 3.8, 3.9\n* Selenium > 3.0.0\n\n## Installation\n\n```\npip install selenium-testing-library\n```\n\n## Quick Start\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen\n\ndriver = webdriver.Chrome()\ndriver.open('https://google.com/')\n\nscreen = Screen(driver)\nsearch_input = screen.find_by_title(\"Search\")\nsearch.send_keys(\"Dogs\")\nsearch_button = screen.find_by_text(\"Google Search\")\nsearch_button.click()\nscreen.wait_for_stale(search_button)\n```\n\n## Finding elements\n\n`get_by` returns the element matched and throws an exception if zero or more than one elements matched.\n`query_by` returns the element matched or `None` if no element matched. It throws and exception if more than 1 elements matched.\n`find_by` behaves like `get_by`, but uses a `WebDriverWait` to wait until the element is present in the DOM.\n\n`get_all_by` returns a list of elements matched. It raises an exception if no elements matched.\n`query_all_by` returns a list of elements matched. It returns an empty list when no elements matched.\n`find_all_by` behaves like `get_all_by`, but uses a `WebDriverWait` to wait until the elements jare present in the DOM.\n\nExamples:\n\n```python\nfrom selenium import webdriver\nfrom selenium.webdriver.common.by import By\nfrom selenium_testing_library import Screen\n\nscreen = Screen(webdriver.Chrome())\nscreen.query_by((By.ID, \"my_id\")) # you can use regular tuples as if you were using Selenium's find_element()\nscreen.find_by((By.XPATH, \"//div\"), timeout=5, poll_frequency=0.5) # locators for searching through text also work\nscreen.get_by((By.CSS, \".my_class\")) # Will throw an exception if the element is not found\n```\nFor a more detail description check out the [Testing-Library](https://testing-library.com/docs/queries/about)'s documentation.\n\n## Helper functions\n\n`get_by_role(role_name)` Queries for elements by given role. Does not currently support default roles.\n`get_by_label_text(text)` Queries for label elements that match the the text string and returns the corresponding input element.\n`get_by_placeholder_text(text)` Queries elements with the matching placeholder attribute.\n`get_by_text(text)` Queries elements where the content matches the provided text.\n`get_by_display_value(value)` Queries inputs, textareas, or selects with matching display value.\n`get_by_alt_text(text)` Queries elements with the matching alt attribute.\n`get_by_title(text)` Queries elements with the matching title attribute.\n`get_by_test_id(value)` Queries elements matching the `data-testid` value.\n`get_by_css(css)` Queries elements matching the specified css selector.\n`get_by_xpath(xpath)` Queries elements matching the specified xpath selector.\n\nExamples:\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen\n\nscreen = Screen(webdriver.Chrome())\nscreen.query_by_role(\"role_name\")\nscreen.get_by_label_text(\"label text\")\nscreen.find_all_by_text(\"my text\", timeout=5, poll_frequency=0.5)\nscreen.get_all_by_alt_text(\"alt text\")\n```\n\n## Locators\n\nLocators are utility classes that simplify writing (By.XXX, selector) tuples. They can be used even when using native selenium functions `driver.find_element(locators.Id(\"my_id\"))`.\n\nAvailable locators:\n\n`Css`, `XPath`, `Id`, `Name`, `TagName`, `LinkText`, `PartialLinkText`, `ClassName`, `Role`, `Text`, `PlaceholderText`, `LabelText`, `AltText`, `Title`, `TestId`, `DisplayValu`\n\nExamples:\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen, locators\n\nscreen.query_by(locators.Id(\"my_id\"))\nscreen.find_by(locators.XPath(\"//div\"), timeout=5, poll_frequency=0.5)\nscreen.get_by(locators.Css(\".my_class\"))\nscreen.get_all_by(locators.Text(\"my text\"))\nscreen.get_by(locators.LinkText(\"my link text\"))\nscreen.query_all_by(locators.ClassName(\"my-class-name\"))\n```\n\n## Wait functions\n\n`wait_for(condition_function)` Waits until condition function returns a truthy value.\n`wait_for_stale(element)` Waits until the element is removed from the DOM.\n\n\nExamples:\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen, locators\n\nscreen = Screen(webdriver.Chrome())\n\n# Wait for the element to be clickable:\nelement = screen.get_by_text(\"Submit\")\nscreen.wait_for(lambda _: element.is_enabled(), timeout=5, poll_frequency=0.5)\n# Wait for the element to be removed from the page:\nscreen.wait_for_stale(element)\n```\n\n## Querying within elements\n\n`Within(element)` Used to limit the query to the children of the provided element\n\nExample:\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen, Within\n\nscreen = Screen(webdriver.Chrome())\nparent_element = screen.get_by_css(\".container\")\nWithin(parent_element).get_by_title(\"My title inside the container\")\n```\n\n# Contributing\n\nSetting up a local development environment\n\n```shell\ngit clone https://github.com/Smotko/selenium-testing-library.git && cd selenium-testing-library\npoetry install && poetry shell\n# Make sure `chromedriver` is in your PATH, download from https://chromedriver.chromium.org/downloads\n# run tests:\npytest --selenium-headless\n# run tests and display coverage info:\npytest --selenium-headless --cov=selenium_testing_library --cov-report html\n\n# To test on multiple Python versions make sure that py37, py38, py39 are\n# installed on your system and available through python3.7, python3.8,\n# python3.9. (Use pyenv and add the pyenv shims to your path\n# `export PATH=$(pyenv root)/shims:$PATH`). Then run tox:\ntox\n```\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python Selenium library inspired by the Testing Library",
    "version": "2021.8.4b0",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "1d7b56aa8696779928b7b4faac47f7c3",
                "sha256": "348243005096d50659a4e522cc2637bb1c681eddd084ce044f6165af9bf9e6bf"
            },
            "downloads": -1,
            "filename": "selenium_testing_library-2021.8.4b0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1d7b56aa8696779928b7b4faac47f7c3",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6,<4.0",
            "size": 8125,
            "upload_time": "2021-08-04T02:18:18",
            "upload_time_iso_8601": "2021-08-04T02:18:18.219292Z",
            "url": "https://files.pythonhosted.org/packages/1e/23/fb711b50d32b50bce6d6b52eb8d371e7ccdb628f4e6ff0696bc8623f8f0d/selenium_testing_library-2021.8.4b0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "d9429f2923a64f7acab8e8f9d10c1fd9",
                "sha256": "de15cb9bfc965cc540de852bcbc26c334e73e6dfe5df12037be4e2055c894355"
            },
            "downloads": -1,
            "filename": "selenium-testing-library-2021.8.4b0.tar.gz",
            "has_sig": false,
            "md5_digest": "d9429f2923a64f7acab8e8f9d10c1fd9",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6,<4.0",
            "size": 9396,
            "upload_time": "2021-08-04T02:18:16",
            "upload_time_iso_8601": "2021-08-04T02:18:16.788792Z",
            "url": "https://files.pythonhosted.org/packages/45/74/4f6ffb0ad23347bb48ae0e988bd1e59fe34214096d9016046d50449db7d8/selenium-testing-library-2021.8.4b0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-08-04 02:18:16",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "Smotko",
    "github_project": "selenium-testing-library",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "tox": true,
    "lcname": "selenium-testing-library"
}
        
Elapsed time: 0.34955s