Package: selenium-testing-library
Selenium Testing LibrarySelenium Testing Library (STL) is a Python library implementingTesting-Libraryin Selenium.DependenciesPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13-devselenium>= 3.0.0Installationpip install selenium-testing-libraryQuick Startfromseleniumimportwebdriverfromselenium_testing_libraryimportScreendriver=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 elementsSTL implements theQueries APIfrom the Testing Library. The Testing Library queriesget_by,query_by,find_by, and the multiple element equivalentsget_all_by,query_all_by,find_all_byare used in places where you would normally use Selenium'sfind_elementandfind_elementsfunctions.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), returnNone(query_by) or block, wait and retry until the element is found (find_by).get_byreturns 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.query_byreturns the element matched orNoneif no element match. It throws an exception if more than one element matches. Mostly used for asserting that an element isnotpresent:assert not screen.query_by_text("not on page").find_bybehaves likeget_by, but uses aWebDriverWaitto wait until the element is present in the DOM.get_all_byreturns a list of elements matched. It raises an exception if no elements match.query_all_byreturns a list of elements matched. It returns an empty list when no elements match.find_all_bybehaves likeget_all_by, but uses aWebDriverWaitto wait until the elements are present in the DOM.When an element is found the queries return a SeleniumWebElementor a list containing SeleniumWebElements when usingget_all_by,query_all_by,find_all_by.The queries accept a tuple containing theBy class identifierand the search query, so they can be used with XPath, Css or any other native Selenium selector:fromseleniumimportwebdriverfromselenium.webdriver.common.byimportByfromselenium_testing_libraryimportScreenscreen=Screen(webdriver.Chrome())screen.get_by((By.CSS,".my_class"))# Will throw an exception if the element is not foundscreen.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 workLocator ClassesFor convenience Locator classes can be used instead of the tuples:fromseleniumimportwebdriverfromselenium_testing_libraryimportScreen,locatorsscreen=Screen(webdriver.Chrome())screen.get_by(locators.Css(".my_class"))# Will throw an exception if the element is not foundscreen.query_by(locators.Id("my_id"))# you can use regular tuples as if you were using Selenium's find_element()screen.find_by(locators.XPath("//div"),timeout=5,poll_frequency=0.5)# locators for searching through text also workTesting Library SelectorsBesides all the Selenium native By selectors, the queries also support Testing Library's selectors:RoleLabelTextPlaceholderTextTextDisplayValueAltTextTitleTestIdfromseleniumimportwebdriverfromselenium_testing_libraryimportScreen,locatorsscreen=Screen(webdriver.Chrome())screen.get_by(locators.Text("My Text"))screen.query_by(locators.Role("button",pressed=True))screen.find_by(locators.TestId("my-test"),timeout=5,poll_frequency=0.5)# locators for searching through text also workHelper functionsFor convenience helper functions on the screen class are available to avoid instantiating locator classes all over the place:screen.get_by_role(role_name)Queries for elements with the given role.screen.get_by_label_text(text)Queries for label elements that match the text string and return the corresponding input element.screen.get_by_placeholder_text(text)Queries elements with the matching placeholder attribute.screen.get_by_text(text)Queries elements where the content matches the provided text.screen.get_by_display_value(value)Queries inputs, textareas, or selects with matching display value.screen.get_by_alt_text(text)Queries elements with the matching alt attribute.screen.get_by_title(text)Queries elements with the matching title attribute.screen.get_by_test_id(value)Queries elements matching thedata-testidvalue.screen.get_by_css(css)Queries elements matching the specified css selector.screen.get_by_xpath(xpath)Queries elements matching the specified xpath selector.There are alsoquery_by_*,find_by_*,get_all_by_*,query_all_by_*,find_all_by_*equivalents.Note:The selenium project has removed thefind_element_by_*andfind_elements_by_*helper functions in theSelenium 4.3.0release, so I just want to state that thescreenhelper functions will never be deprecated or removed.Examples:fromseleniumimportwebdriverfromselenium_testing_libraryimportScreenscreen=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")Wait functionswait_for(condition_function)Waits until the condition function returns a truthy value.wait_for_stale(element)Waits until the element is removed from the DOM.Examples:fromseleniumimportwebdriverfromselenium_testing_libraryimportScreen,locatorsscreen=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 elementsWithin(element)Used to limit the query to the children of the provided elementExample:fromseleniumimportwebdriverfromselenium_testing_libraryimportScreen,Withinscreen=Screen(webdriver.Chrome())parent_element=screen.get_by_css(".container")Within(parent_element).get_by_title("My title inside the container")Testing Playground URLsFor debugging usingtesting-playground,screenexposeslog_testing_playground_url()which prints end returns a URL that can be opened in the browser.# log entire document to testing-playgroundurl=screen.log_testing_playground_url()# log a single elementurl=screen.log_testing_playground_url(screen.get_by_text("test"))ContributingSetting up a local development environmentgitclonehttps://github.com/anze3db/selenium-testing-library.git&&cdselenium-testing-library
poetryinstall&&poetryshell# 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-reporthtml# 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:toxReleasing a new versionUpdate ChangelogUpdate npm dependenciesnpmrundeployIfnpm run deployfails because of outdated dependencies run:npmupdateBump the versionbumpverupdate# Wait and see if the CI is greenPublish to PyPIpoetrybuild&&poetrypublish