{"id":15043973,"url":"https://github.com/anze3db/selenium-testing-library","last_synced_at":"2025-10-23T15:30:37.828Z","repository":{"id":36952580,"uuid":"366223843","full_name":"anze3db/selenium-testing-library","owner":"anze3db","description":"Selenium Testing Library (STL) is a Python library implementing Testing-Library in Selenium.","archived":false,"fork":false,"pushed_at":"2024-10-08T10:46:57.000Z","size":966,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-29T21:10:13.544Z","etag":null,"topics":["python","selenium","selenium-python","selenium-webdriver","test-automation","testing","testing-library"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anze3db.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-11T01:41:28.000Z","updated_at":"2024-10-08T10:46:59.000Z","dependencies_parsed_at":"2023-12-05T00:27:56.318Z","dependency_job_id":"db0d2bcf-f196-4817-93f5-8b9db51eff7b","html_url":"https://github.com/anze3db/selenium-testing-library","commit_stats":{"total_commits":287,"total_committers":6,"mean_commits":"47.833333333333336","dds":0.3693379790940766,"last_synced_commit":"a22eb11ae9f1231b338defca60cbf6fe33e27e9f"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anze3db%2Fselenium-testing-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anze3db%2Fselenium-testing-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anze3db%2Fselenium-testing-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anze3db%2Fselenium-testing-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anze3db","download_url":"https://codeload.github.com/anze3db/selenium-testing-library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237843858,"owners_count":19375218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","selenium","selenium-python","selenium-webdriver","test-automation","testing","testing-library"],"created_at":"2024-09-24T20:49:53.995Z","updated_at":"2025-10-23T15:30:32.526Z","avatar_url":"https://github.com/anze3db.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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/anze3db/selenium-testing-library/actions/workflows/main.yml/badge.svg)](https://github.com/anze3db/selenium-testing-library/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/anze3db/selenium-testing-library/branch/main/graph/badge.svg?token=L1M7HO3DL7)](https://codecov.io/gh/anze3db/selenium-testing-library)\n\nSelenium Testing Library (STL) is a Python library implementing [Testing-Library](https://testing-library.com/) in Selenium.\n\n## Dependencies\n\n- Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13-dev\n- [`selenium`](https://pypi.org/project/selenium/) \u003e= 3.0.0\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\nSTL implements the [Queries API](https://testing-library.com/docs/queries/about) from the Testing Library. The Testing Library queries `get_by`, `query_by`, `find_by`, and the multiple element equivalents `get_all_by`, `query_all_by`, `find_all_by` are used in places where you would normally use Selenium's `find_element` and `find_elements` functions.\n\n The difference between the different queries (`get_by`, `query_by`, `find_by`) is whether the query will throw an error if the element was not found (`get_by`), return `None` (`query_by`) or block, wait and retry until the element is found (`find_by`).\n\n * `get_by` returns the element matched and throws an exception if zero or more than one element matches. This is the main function that we should be using to locate elements on a page.\n * `query_by` returns the element matched or `None` if no element match. It throws an exception if more than one element matches. Mostly used for asserting that an element is **not** present: `assert not screen.query_by_text(\"not on page\")`.\n * `find_by` behaves like `get_by`, but uses a `WebDriverWait` to wait until the element is present in the DOM.\n * `get_all_by` returns a list of elements matched. It raises an exception if no elements match.\n * `query_all_by` returns a list of elements matched. It returns an empty list when no elements match.\n * `find_all_by` behaves like `get_all_by`, but uses a `WebDriverWait` to wait until the elements are present in the DOM.\n\n When an element is found the queries return a Selenium [`WebElement`](https://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement) or a list containing Selenium [WebElement](https://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement)s when using `get_all_by`, `query_all_by`, `find_all_by`.\n\nThe queries accept a tuple containing the [By class identifier](https://selenium-python.readthedocs.io/api.html#locate-elements-by) and the search query, so they can be used with XPath, Css or any other native Selenium selector:\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.get_by((By.CSS, \".my_class\")) # Will throw an exception if the element is not found\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\n```\n\n## Locator Classes\n\nFor convenience Locator classes can be used instead of the tuples:\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen, locators\n\nscreen = Screen(webdriver.Chrome())\nscreen.get_by(locators.Css(\".my_class\")) # Will throw an exception if the element is not found\nscreen.query_by(locators.Id(\"my_id\")) # you can use regular tuples as if you were using Selenium's find_element()\nscreen.find_by(locators.XPath(\"//div\"), timeout=5, poll_frequency=0.5) # locators for searching through text also work\n```\n\n## Testing Library Selectors\n\nBesides all the Selenium native By selectors, the queries also support Testing Library's selectors:\n * [Role](https://testing-library.com/docs/queries/byrole)\n * [LabelText](https://testing-library.com/docs/queries/bylabeltext)\n * [PlaceholderText](https://testing-library.com/docs/queries/byplaceholdertext)\n * [Text](https://testing-library.com/docs/queries/bytext)\n * [DisplayValue](https://testing-library.com/docs/queries/bydisplayvalue)\n * [AltText](https://testing-library.com/docs/queries/byalttext)\n * [Title](https://testing-library.com/docs/queries/bytitle)\n * [TestId](https://testing-library.com/docs/queries/bytestid)\n\n```python\nfrom selenium import webdriver\nfrom selenium_testing_library import Screen, locators\n\nscreen = Screen(webdriver.Chrome())\nscreen.get_by(locators.Text(\"My Text\"))\nscreen.query_by(locators.Role(\"button\", pressed=True))\nscreen.find_by(locators.TestId(\"my-test\"), timeout=5, poll_frequency=0.5) # locators for searching through text also work\n```\n## Helper functions\n\nFor convenience helper functions on the screen class are available to avoid instantiating locator classes all over the place:\n\n[`screen.get_by_role(role_name)`](https://testing-library.com/docs/queries/byrole) Queries for elements with the given role.\n[`screen.get_by_label_text(text)`](https://testing-library.com/docs/queries/bylabeltext) Queries for label elements that match the text string and return the corresponding input element.\n[`screen.get_by_placeholder_text(text)`](https://testing-library.com/docs/queries/byplaceholdertext) Queries elements with the matching placeholder attribute.\n[`screen.get_by_text(text)`](https://testing-library.com/docs/queries/bytext) Queries elements where the content matches the provided text.\n[`screen.get_by_display_value(value)`](https://testing-library.com/docs/queries/bydisplayvalue) Queries inputs, textareas, or selects with matching display value.\n[`screen.get_by_alt_text(text)`](https://testing-library.com/docs/queries/byalttext) Queries elements with the matching alt attribute.\n`screen.get_by_title(text)` Queries elements with the matching title attribute.\n`screen.get_by_test_id(value)` Queries elements matching the `data-testid` value.\n`screen.get_by_css(css)` Queries elements matching the specified css selector.\n`screen.get_by_xpath(xpath)` Queries elements matching the specified xpath selector.\n\nThere are also `query_by_*`, `find_by_*`, `get_all_by_*`, `query_all_by_*`, `find_all_by_*`  equivalents.\n\n**Note:** The selenium project has removed the `find_element_by_*` and `find_elements_by_*` helper functions in the [Selenium 4.3.0](https://github.com/SeleniumHQ/selenium/releases/tag/selenium-4.3.0) release, so I just want to state that the `screen` helper functions will never be deprecated or removed.\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## Wait functions\n\n`wait_for(condition_function)` Waits until the condition function returns a truthy value.\n`wait_for_stale(element)` Waits until the element is removed from the DOM.\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# Testing Playground URLs\n\nFor debugging using [testing-playground](https://testing-playground.com/), `screen` exposes `log_testing_playground_url()` which prints end returns a URL that can be opened in the browser.\n\n```python\n# log entire document to testing-playground\nurl = screen.log_testing_playground_url()\n# log a single element\nurl = screen.log_testing_playground_url(screen.get_by_text(\"test\"))\n```\n\n# Contributing\n\nSetting up a local development environment\n\n```shell\ngit clone https://github.com/anze3db/selenium-testing-library.git \u0026\u0026 cd selenium-testing-library\npoetry install \u0026\u0026 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\n# Releasing a new version\n\n1. Update Changelog\n2. Update npm dependencies\n```shell\nnpm run deploy\n```\nIf `npm run deploy` fails because of outdated dependencies run:\n\n```shell\nnpm update\n```\n\n3. Bump the version\n```shell\nbumpver update  # Wait and see if the CI is green\n```\n4. Publish to PyPI\n```shell\npoetry build \u0026\u0026 poetry publish\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanze3db%2Fselenium-testing-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanze3db%2Fselenium-testing-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanze3db%2Fselenium-testing-library/lists"}