E2E tests (Selenium)

End-to-end browser automation tests using Selenium.

Usage

splent feature:test --e2e
splent feature:test auth --e2e

E2E tests live in tests/e2e/ inside each feature and are not included in the default test run. Use the --e2e flag explicitly.

Description

E2E tests drive a real browser via Selenium against the running application. They verify critical user flows that cannot be covered by functional tests (e.g. JavaScript interactions, multi-page workflows).

Each test file uses a browser fixture that initializes and tears down the Selenium driver, and resolves the base URL through the framework helper.

import pytest
from splent_framework.environment.host import get_host_for_selenium_testing
from splent_framework.selenium.common import initialize_driver, close_driver

@pytest.fixture()
def browser():
    driver = initialize_driver()
    yield driver
    close_driver(driver)

def test_login_flow(browser):
    host = get_host_for_selenium_testing()
    browser.get(f"{host}/login")
    # ... interact with the page

Driver modes

initialize_driver() picks one of two modes based on the environment.

Local (default). Launches a browser on the machine running the tests, resolving the driver binary through webdriver_manager. Requires the browser itself to be installed locally.
Grid. When SELENIUM_GRID_URL is set, the driver is a webdriver.Remote attached to that Selenium Grid hub, so the browser runs in a grid node container rather than alongside the tests. This is the mode that works under Docker Compose, where the application container has no browser installed.

Both modes support Chrome (the default) and Firefox. Select the browser with the browser argument (initialize_driver("firefox")) or the SELENIUM_BROWSER environment variable; any other value raises ValueError. Every driver is configured with a 30-second page-load timeout and a 10-second implicit wait.

Targeting the right host

The URL a test opens is resolved by the browser, not by the test process. With a grid, the browser runs inside a grid node container, where localhost is the node itself, not the application. Grid users must therefore point tests at a host the browser container can reach, such as the web or proxy container name.

get_host_for_selenium_testing() handles this. When SELENIUM_TARGET_URL is set, it returns that value; otherwise it falls back to a default based on WORKING_DIR.

Environment variables

Variable	Default	Purpose
`SELENIUM_GRID_URL`	unset	When set, attach to this Selenium Grid hub via `webdriver.Remote` instead of launching a local browser.
`SELENIUM_BROWSER`	`chrome`	Browser to drive, `chrome` or `firefox`. Applies in both modes.
`SELENIUM_TARGET_URL`	unset	Base URL returned by `get_host_for_selenium_testing()`. Required with a grid, where the default `localhost` would point the browser at its own container.

Requirements

The application must be running (splent product:run).
Without a grid, a local Chrome or Firefox installation is required; webdriver_manager downloads the matching driver binary automatically.
With a grid, set SELENIUM_GRID_URL and SELENIUM_TARGET_URL. No local browser is needed.

Products scaffolded by CLI 1.13.0 and later ship the grid out of the box. The compose file starts a Selenium hub with Chrome and Firefox nodes, and both variables come wired on the web service, pointing the driver at the hub and the browser at the web container. Scaffolded e2e tests run under Docker with no further setup.