Principle:SeleniumHQ Selenium Test Execution Strategy
| Knowledge Sources | |
|---|---|
| Domains | Testing, Continuous_Integration, Quality_Assurance |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Strategy for running tests in the Selenium monorepo using Bazel with size filters, tag filters, and browser-specific configurations.
Description
Selenium tests are organized by size (small = unit, medium = integration, large = browser) and tagged by browser and feature. Bazel's --test_size_filters and --test_tag_filters flags enable precise test selection. The project prefers small unit tests over browser tests for speed and reliability, and avoids mocks to prevent API contract misrepresentation. Browser tests require actual browser binaries; --pin_browsers=false uses Selenium Manager to locate browsers/drivers. Tests should be written before implementing solutions (test-first approach). Bug fixes and features should have tests.
Usage
Run unit tests first (--test_size_filters=small) for fast feedback. Run browser tests for integration verification. Use --test_output=all for debugging and --cache_test_results=no (or -t-) to force re-execution. Use --flaky_test_attempts 3 to retry flaky tests. On Linux, use --run_under="xvfb-run -a" for virtual display or set --test_env=DISPLAY=:99.
Theoretical Basis
# Test Size Hierarchy
small -> Unit tests (no browser, fast, preferred)
medium -> Integration tests (may use network, more involved)
large -> Browser tests (require browser binary, slow)
# Key Bazel Test Flags
--test_size_filters=small -> only unit tests
--test_size_filters=large -> only browser tests
--test_tag_filters=chrome -> only Chrome-tagged tests
--test_tag_filters=this,-not -> include/exclude by tag
--test_output=all -> show all output
--test_output=streamed -> show output in real-time, one at a time
--cache_test_results=no / -t- -> force re-run (no caching)
--pin_browsers=false -> use Selenium Manager for browsers
--headless -> headless browser mode
--flaky_test_attempts=3 -> retry flaky tests up to 3 times
--local_test_jobs=1 -> control parallelism
--test_env=FOO=bar -> pass environment variable to test
--run_under="xvfb-run -a" -> run under virtual display (Linux)
# Per-Language Test Targets
Java: bazel test //java/... --test_size_filters=small
Python: bazel test //py:unit
Ruby: bazel test //rb/spec/unit/...
JavaScript: bazel test //javascript/selenium-webdriver:all
.NET: bazel test //dotnet/test/common:AllTests
Rust: bazel test //rust/...
# Note: If multiple --test_tag_filters are specified,
# only the last one is used (be careful with inherited configs)