To build a Selenium project, add the Selenium language binding as a project dependency, install a target browser, write a test that opens a WebDriver session and closes it, then run it with your language’s test runner. For a small project, run locally first; Selenium Manager can handle many driver setup cases, while Selenium Grid is an optional step for distributed tests.
What belongs in a Selenium project?
Selenium WebDriver is a language-neutral interface. Your project uses a language binding—such as Python’s Selenium package or Java’s Selenium library—to send commands through a browser-specific driver to a browser. The Selenium Project’s Getting started guide describes these as distinct components: install the binding, the browser you want to use, and its driver.
- Language binding: the Selenium dependency your code imports.
- Browser: the browser your test will control, such as Chrome, Firefox, or Edge.
- WebDriver implementation: the browser-specific driver, which Selenium Manager can often locate or obtain when needed.
- Test runner: the tool that discovers and runs tests, such as pytest, Maven, or Gradle.
Record dependencies in a manifest or build file so another developer or a CI job can reproduce the setup. Start with a local browser and one focused test; add remote execution only if you need it.
How do I install Selenium?
Python
Create and activate a virtual environment, then install Selenium in it. Python’s official API documentation recommends virtual environments for project isolation: Python API documentation.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
- Create a project directory and enter it.
- Create a virtual environment with
python -m venv .venv. - Activate it: on macOS or Linux, run
source .venv/bin/activate; in Windows PowerShell, run.venvScriptsActivate.ps1. - Install Selenium with
python -m pip install selenium. - Save the installed dependency with
python -m pip freeze > requirements.txtso the environment can be recreated.
For a team project, review and pin dependency versions deliberately rather than assuming a version copied from an old tutorial is current.
Java with Maven
Add org.seleniumhq.selenium:selenium-java to the project’s Maven dependencies, then use Maven’s test lifecycle to run tests. The Selenium documentation provides language-specific setup instructions and examples: Install a Selenium library.
Java with Gradle
Declare org.seleniumhq.selenium:selenium-java as a test dependency (the official Gradle example uses testImplementation) and configure the test task for JUnit Platform if that is the framework your tests use. Run the project’s tests with Gradle after the dependency and test framework are configured.
Rank #2
Other languages
Selenium also documents setup routes for JavaScript, .NET, and Ruby. Follow the current language-specific installation page for the package name, supported runtime, and test-runner setup, since those details can change.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteHow do I write and run a first Selenium test?
Python example
Save this as test_example.py. It starts a browser session, loads a page, checks the page title, and closes the session even if an assertion fails.
from selenium import webdriver
def test_example_page_title():
driver = webdriver.Chrome()
try:
driver.get("https://example.com")
assert driver.title == "Example Domain"
finally:
driver.quit()Run just this test with pytest -q test_example.py, or run the project suite with pytest. Pytest must be installed in the same environment if the project does not already declare it. Selenium’s execution guidance shows pytest as a common way to run Python tests: First Selenium script.
driver.quit() ends the WebDriver session and closes its browser windows. Prefer it for cleanup at the end of a test; an unclosed session can leave browser processes running and interfere with later runs.
Java test execution
Put Java test code in the test source set used by your build and use your chosen test framework’s assertions. Run the suite with mvn clean test for Maven or gradle clean test for Gradle, as shown in Selenium’s documentation. A standalone Java example can also be launched with the documented Maven exec command, but a test runner is usually the more repeatable path for a project: First Selenium script.
Do I need to install ChromeDriver or another driver manually?
Usually, not for a standard local setup using a recent Selenium binding. Selenium Manager is the Selenium Project’s driver manager and has shipped with Selenium since Selenium 4.6.0. When a driver is not supplied, Selenium bindings can invoke it to handle many driver setup cases. You can still configure a driver path or manage drivers yourself where the environment requires it.
Managed browser discovery, download, and caching were added in Selenium 4.11.0. In this mode, Selenium Manager documents management for Chrome, Firefox, and Edge. Its documented unsupported environments include Linux arm64/aarch64, 32-bit architecture, and Raspberry Pi. Check the current Selenium Manager documentation for platform details.
When manual driver management makes sense
- Your platform or architecture is not supported by Selenium Manager.
- A restricted network prevents the required discovery or download.
- You need a deliberately controlled browser/driver combination for a particular environment.
- You use an older Selenium release or have other specialized driver-management requirements.
In those cases, consult Selenium’s driver location guidance and verify browser/driver compatibility. Avoid embedding a developer’s fixed local driver path in shared code unless the deployment environment specifically requires it; a hard-coded path makes the project less portable.
When should I use Selenium Grid?
Run tests locally while developing a small suite. Grid becomes useful when you need remote WebDriver sessions or distributed execution across multiple machines, browsers, or operating systems. It adds server setup and an endpoint to configure in tests, so it is not a prerequisite for a first Selenium project.
Start a standalone Grid
The Selenium Grid quick start lists Java 11 or higher, browser(s), driver(s) or Selenium Manager configuration, and the Selenium Server JAR as prerequisites. With the JAR available, start standalone mode:
java -jar selenium-server-<version>.jar standaloneReplace <version> with the version of the JAR you downloaded. Configure your test to use the remote endpoint http://localhost:4444 rather than launching a local browser directly. Follow the current Grid quick start for server options and client configuration.
Common setup problems and fixes
- Python reports that Selenium cannot be imported: activate the intended virtual environment and install Selenium there with
python -m pip install selenium. Check that the Python running pytest is the same interpreter where the dependency was installed. - Browser or driver cannot be found: confirm the browser is installed, check whether your Selenium version and platform support Selenium Manager’s needed behavior, and review network access if downloads are required. For unsupported or controlled environments, use the official driver location guidance and verify compatibility.
- A fixed driver path works only on one machine: remove the machine-specific path from shared code where possible and let Selenium Manager resolve the driver, or define an explicit environment-specific configuration for deployments that require manual management.
- A test passes locally but fails on another machine: check that dependencies are recorded in the project manifest or build file, the required browser is available, and the target platform is supported. Recreate the environment from the project’s dependency declarations.
- The browser remains open after a failed test: ensure cleanup runs in a
finallyblock or test-fixture teardown and callquit()to end the WebDriver session. - A Grid test cannot connect: confirm the standalone server is running, the test points to
http://localhost:4444(or the correct remote host), and the server has access to a supported browser and driver configuration.
Run browser automation responsibly
Selenium is commonly used for web application testing and other browser automation. If you intend to use it for scraping, check the site’s terms and access rules first; sites may prohibit scraping or block automated access. Selenium’s execution documentation notes both issues: Selenium WebDriver documentation.
Or skip the browser setup
If your goal is to capture a page rather than interactively test it, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. For example, with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
