Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 69.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 0.000s · 70MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
selenium (fixture)
✓ def test_example(selenium): ...
The 'selenium' fixture is automatically discovered and provided by the plugin; no explicit import statement from 'pytest_selenium' is typically needed in test files.
pytest.mark.nondestructive
✓ import pytest
@pytest.mark.nondestructive
def test_something_nondestructive(selenium): ...
Used to mark tests that do not make destructive changes, avoiding accidental skipping in sensitive environments.
This quickstart demonstrates a basic pytest test using the `selenium` fixture. The fixture automatically provides a WebDriver instance. To run, specify your desired browser (e.g., Firefox or Chrome) via the `--driver` command-line option. Ensure the corresponding WebDriver executable (e.g., `geckodriver`, `chromedriver`) is in your system's PATH.
import pytest
def test_example_opens_website(selenium):
"""A simple test that opens a website using the selenium fixture."""
selenium.get('http://www.example.com')
assert "Example Domain" in selenium.title
# To run: pytest --driver Firefox -v
Debug
Known issues
breakingCloud testing provider credentials were moved from generic configuration files (e.g., `pytest.ini`) to dedicated provider-specific files for improved security in versions 4.0.0/4.0.1.fixMigrate cloud provider credentials to new, separate configuration files (e.g., `.saucelabs`, `.browserstack`). Refer to the official documentation for specific file names and formats. Environment variables remain an unaffected method for credential management.
affects: >=4.0.0
gotchaBy default, `pytest-selenium` assumes all tests are 'destructive' and all environments are 'sensitive' (matching any URL), causing tests to be skipped.fixTo prevent skipping, explicitly mark nondestructive tests with `@pytest.mark.nondestructive` or configure the `sensitive_url` regular expression in `pytest.ini` to exclude your non-sensitive test environments.
affects: All versions
gotchaSelenium WebDriver requires browser driver executables (e.g., `chromedriver`, `geckodriver`) to be available in the system's PATH or explicitly configured, otherwise browser launch will fail.fixDownload the appropriate WebDriver executable for your browser and operating system, then add its directory to your system's PATH. Alternatively, you can use tools like `webdriver-manager` with direct Selenium WebDriver initialization or configure specific driver paths if `pytest-selenium` allows for it (often handled by `pytest-selenium`'s underlying Selenium setup).
affects: All versions
deprecatedWith Selenium 4, the `DesiredCapabilities` class is deprecated in favor of browser-specific `Options` classes (e.g., `ChromeOptions`, `FirefoxOptions`) for configuring browser capabilities. While `pytest-selenium` abstracts some of this, direct interaction with capabilities may be affected.fixWhen directly specifying browser capabilities, use browser-specific `Options` classes (e.g., `selenium.webdriver.ChromeOptions`, `selenium.webdriver.FirefoxOptions`) instead of `DesiredCapabilities`.
affects: Selenium 4 and later (indirectly affects pytest-selenium users)
Errors
Common errors & fixes
Fixture 'selenium' not found
The pytest-selenium plugin is not installed or not correctly recognized by pytest, preventing the 'selenium' fixture from being discovered.
fixInstall the plugin using `pip install pytest-selenium` and ensure pytest is run from an environment where it is installed.
AttributeError: 'WebDriver' object has no attribute 'find_element_by_id'
Selenium 4 has deprecated older `find_element_by_*` methods in favor of using the `By` class with `find_element` or `find_elements`.
fixUpdate your test code to use the new `By` class: `from selenium.webdriver.common.by import By` then `selenium.find_element(By.ID, 'element_id')`.
selenium.common.exceptions.WebDriverException: Message: 'geckodriver' executable needs to be in PATH.
The WebDriver executable (e.g., `geckodriver` for Firefox, `chromedriver` for Chrome) required by Selenium is not found in the system's PATH or specified location.
fixDownload the appropriate WebDriver executable for your browser and either place it in a directory listed in your system's PATH or specify its path using the `selenium_driver_executables` option in your `pytest.ini`.
ModuleNotFoundError: No module named 'selenium'
The core `selenium` library, which `pytest-selenium` depends on for browser automation, is not installed in your Python environment.
fixInstall the `selenium` library using `pip install selenium`.
Upgrade
Version history
4.1.0latest on PyPI · released Feb 1, 2024
Audit
Dependencies
pytestrequiredCore testing framework that pytest-selenium extends.
seleniumrequiredProvides WebDriver API for browser automation.