reflex-dev/reflex · error · RuntimeError

Frontend functionality requires `selenium` to be installed,

Error message

Frontend functionality requires `selenium` to be installed, and it could not be imported.

What it means

RuntimeError from AppHarness.frontend when the selenium package cannot be imported. The Selenium-based driver helpers are optional in Reflex's testing layer, so calling frontend() without selenium installed fails fast with this message.

Source

Thrown at reflex/testing.py:641

            driver_clz: webdriver.Chrome (default), webdriver.Firefox, webdriver.Safari,
                webdriver.Edge, etc
            driver_kwargs: additional keyword arguments to pass to the webdriver constructor
            driver_options: selenium ArgOptions instance to pass to the webdriver constructor
            driver_option_args: additional arguments for the webdriver options
            driver_option_capabilities: additional capabilities for the webdriver options

        Returns:
            Instance of the given webdriver navigated to the frontend url of the app.

        Raises:
            RuntimeError: when selenium is not importable or frontend is not running
        """
        if not has_selenium:
            msg = (
                "Frontend functionality requires `selenium` to be installed, "
                "and it could not be imported."
            )
            raise RuntimeError(msg)
        if self.frontend_url is None:
            msg = "Frontend is not running."
            raise RuntimeError(msg)
        want_headless = False
        if environment.APP_HARNESS_HEADLESS.get():
            want_headless = True
        if driver_clz is None:
            requested_driver = environment.APP_HARNESS_DRIVER.get()
            driver_clz = getattr(webdriver, requested_driver)  # pyright: ignore [reportPossiblyUnboundVariable]
            if driver_options is None:
                driver_options = getattr(webdriver, f"{requested_driver}Options")()  # pyright: ignore [reportPossiblyUnboundVariable]
        if driver_clz is webdriver.Chrome:  # pyright: ignore [reportPossiblyUnboundVariable]
            if driver_options is None:
                from selenium.webdriver.chrome.options import Options

                driver_options = Options()  # pyright: ignore [reportPossiblyUnboundVariable]
            driver_options.add_argument("--class=AppHarness")
            if want_headless:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Install selenium: `uv add selenium` or `pip install selenium` (plus a webdriver such as chromedriver / selenium-manager bundled)
2. Prefer the Playwright-based tests in tests/integration/tests_playwright for new tests
3. Skip selenium-dependent tests when the package is absent (e.g. pytest.importorskip("selenium"))

Example fix

# before
harness.frontend()  # RuntimeError: selenium not installed

# after
pytest.importorskip("selenium")
harness.frontend()

try:
    import selenium  # noqa: F401
    has_selenium = True
except ImportError:
    has_selenium = False

if not has_selenium:
    pytest.skip("selenium not installed")

def selenium_available() -> bool:
    try:
        import selenium
        return True
    except ImportError:
        return False

try:
    driver = harness.frontend()
except RuntimeError as e:
    if "selenium" in str(e):
        pytest.skip(str(e))
    raise

When it happens

Trigger: Calling harness.frontend() (or the driver fixture) in an environment where `import selenium` failed at module import time (has_selenium is False). Triggered by tests like test_connection_banner, test_component_state_app, etc.

Common situations: Running the integration suite without the selenium extra installed; new venv/CI image missing selenium; using Playwright-based tests but accidentally calling the selenium API.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Named props cannot be used with custom thresholds
• {name}
• app_name must be provided when app_source is a string.
• Backend was not initialized.
• App was not initialized.

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/0134d50672a91166. Report an issue: GitHub.