If your first Selenium test fails before the browser even opens, the problem usually is not Selenium itself. It is the setup. Knowing how to set up Selenium correctly saves hours of troubleshooting later, especially when you start building a suite that other engineers need to run, debug, and maintain.
This guide uses a practical path: choose a language, install the required tools, connect Selenium to a browser, and verify the setup with a small working test. Along the way, we will make choices that support maintainability rather than just getting one script to run.
How to set up Selenium without creating future problems
A basic Selenium environment has four moving parts: your programming language, a package manager or build tool, a browser, and the browser driver support that lets Selenium control that browser. Most setup issues happen when one of those parts is missing or version-misaligned.
Before installing anything, decide what stack fits your team. Java and Python are both common choices. Java is often a strong fit for larger automation frameworks with Maven or Gradle, while Python is faster to start with and works well for leaner test suites. Selenium supports both, so the best answer depends on your project, CI environment, and team skill set.
If you are learning individually, choose one language and stay with it long enough to understand the full workflow. Switching between examples from different languages is one of the fastest ways to make setup feel harder than it is.
Choose your Selenium stack first
For Java, install the current JDK and an IDE such as IntelliJ IDEA or Eclipse. You will also want Maven or Gradle if your IDE does not manage that automatically. For Python, install Python 3, then use pip and an editor like VS Code or PyCharm.
The browser matters too. Chrome is the most common starting point because many teams already use it for development and debugging. Firefox is also well supported and sometimes useful when you need a second browser in cross-browser coverage. Start with one browser, get the test passing, then expand.
A note on WebDriver and Selenium Manager
Older Selenium tutorials often tell you to manually download ChromeDriver or GeckoDriver and manage the path yourself. That still works, but it is no longer the best default for many teams. Recent Selenium versions include Selenium Manager, which can resolve driver management automatically in many environments.
That changes how to set up Selenium in practice. If you are using a current Selenium release, try the built-in driver management first. Manual driver setup is still relevant in locked-down enterprise environments, offline systems, or teams that pin exact browser and driver versions for repeatability.
Set up Selenium with Java
If your team uses Java-based test automation, create a new Maven project first. Once the project exists, add the Selenium Java dependency to your pom.xml. Your IDE should download the libraries automatically.
A minimal project structure should separate source code from tests. Even if you are only validating setup, start with a clean test folder and a naming convention you would keep in a real project. That small discipline pays off when your test count grows.
After adding Selenium, create a simple test class. If you are using JUnit or TestNG, include one test that opens a browser, navigates to a page, checks the title, and closes the browser. Keep the first test intentionally small. The goal here is not framework design. The goal is confirming that Java, Selenium, the browser, and your execution path all work together.
A simple Java example looks like this:
“`java import org.junit.jupiter.api.Test; import org.openqa.selenium.WebDriver; import org.openqa.selenium.chrome.ChromeDriver;
public class SmokeTest { @Test public void openBrowser() { WebDriver driver = new ChromeDriver(); driver.get(“https://example.com”); System.out.println(driver.getTitle()); driver.quit(); } } “`
If Selenium Manager resolves the driver correctly, this should open Chrome without extra configuration. If it does not, the error message usually points to either browser availability or driver resolution.
Set up Selenium with Python
For Python, create a project folder and a virtual environment first. This is not just cleanup. It prevents package conflicts across projects and makes your automation setup easier to reproduce on another machine.
Install Selenium with pip, then create a small script or test file. As with Java, start with one browser, one page load, and one assertion or printed output.
A minimal Python example:
“`python from selenium import webdriver
driver = webdriver.Chrome() driver.get(“https://example.com”) print(driver.title) driver.quit() “`
Run it from the same virtual environment where Selenium was installed. If your editor uses a different Python interpreter than your terminal, you can get confusing import errors even when the package is installed correctly. That is a common setup issue for newer engineers.
Browser setup and version alignment
When engineers say Selenium is flaky, they are often describing environment mismatch rather than test design. Browser version and driver compatibility still matter, even with Selenium Manager handling much of the work.
If Chrome updates automatically but your test runners are pinned to an older environment, your local setup may behave differently than CI. That is why setup should not stop at “it works on my laptop.” You want a repeatable configuration that your team can share.
For local learning, auto-managed browsers are fine. For team execution, especially in CI, consider documenting browser versions, package versions, and execution commands in the repository. Better yet, standardize them through containerization or CI images once your suite matures.
Common setup mistakes to avoid
The fastest way to get blocked is to combine too many decisions at once. New learners often install Java, Maven, JUnit, Selenium, ChromeDriver, an IDE plugin, and a reporting library in one sitting. Then they have no idea which layer caused the failure.
Set up Selenium in thin slices. First confirm the language install. Then confirm dependency installation. Then open the browser. Then add a test framework. Then add assertions and test structure. This sequence gives you a working baseline at each step.
Another mistake is treating setup as separate from framework design. The two are connected. If your first project has no dependency management, inconsistent package structure, and hardcoded waits, you are not just setting up Selenium – you are setting up future maintenance problems.
What a good Selenium setup includes
A good setup is not only a browser that launches. It also gives you a foundation for readable and stable tests. At minimum, that means using a real project structure, keeping dependencies explicit, and making test execution straightforward for someone else on the team.
This is where many fragmented tutorials stop too early. They show a browser opening, then leave the reader with a script that cannot scale. A stronger setup includes the next layer: where test code lives, how configuration is handled, and how the suite will run in local and CI environments.
If you are building beyond a one-off experiment, add these ideas early:
- Keep configuration outside test logic when possible
- Use a test framework like JUnit, TestNG, or pytest instead of raw scripts
- Create reusable browser setup code rather than duplicating it in every test
- Plan for explicit waits and maintainable locators from the beginning
That is the difference between learning Selenium and building automation you can trust.
Verify the setup with one meaningful test
After installation, resist the urge to automate a complicated workflow immediately. Start with a stable page and one assertion. Confirm that the browser opens, navigation works, the element can be located, and the session closes cleanly.
Then run the same test more than once. A setup that works once but fails intermittently is not finished. Repeat execution catches hidden issues like local profile conflicts, browser prompts, or environment path problems.
If you plan to use Selenium for real project work, run that same test from the command line and from your IDE. Local execution should be consistent in both places. If it is not, find that mismatch now instead of after you write twenty tests.
When manual driver setup still makes sense
Even though current Selenium versions reduce the need for manual driver management, there are cases where you may still want full control. Enterprise security policies, isolated build agents, proxy restrictions, and strict version pinning can all justify a manual approach.
In those environments, download the exact driver version that matches your browser strategy, store it in a predictable location, and configure the path explicitly. It adds setup overhead, but it can improve traceability. The trade-off is convenience versus control, and different teams will make different calls.
Build from setup into maintainability
The real goal is not simply to learn how to set up Selenium. It is to create an automation environment that can support reliable tests, team collaboration, and future growth. That means your first successful browser launch should immediately lead into better habits: organized test code, clear execution steps, and a framework structure you can extend without rewriting everything later.
For serious QA engineers, SDETs, and developers, setup is part of engineering discipline. Treat it that way, and the rest of your Selenium work becomes much easier to reason about. If you build the environment carefully now, every test you write after this starts on firmer ground.