How to Use Selenium with IntelliJ IDEA

To use Selenium with IntelliJ IDEA: create or open a Java project, add Selenium’s Java library through Maven or Gradle, choose a test framework such as JUnit or TestNG, and run a test from IntelliJ’s gutter controls. Selenium provides the browser automation API; the browser and its WebDriver implementation are separate runtime pieces. IntelliJ provides project, test-running, and debugging tools.

1. Check the prerequisites

• JDK: Install a JDK and select it for the project in IntelliJ. Match the project’s configured Java level to the version supported by its dependencies and build environment.
• Browser: Install the browser your test will automate, such as Chrome.
• Build tool: Use the existing project’s Maven or Gradle setup when adding Selenium to a repository. For a new project, either is suitable.
• Test framework: Select JUnit or TestNG, or use the one already established by the project.

WebDriver is the browser-control interface. Selenium’s language binding, the browser, and the browser-specific driver implementation all participate in a local browser session. Selenium can resolve drivers for supported browsers, but a first startup can take extra time while a driver is downloaded and verified. Consult the Selenium WebDriver getting-started guide for the current setup details.

2. Create a Selenium project in IntelliJ IDEA

1. Open File | New | Project.
2. Select Selenium, choose Java, then select Maven or Gradle.
3. Choose JUnit or TestNG, select or download a JDK, and complete the wizard’s Selenium version and dependency choices.
4. Let IntelliJ import or sync the build project. Confirm the chosen JDK and test framework are configured for the module that contains your test.

JetBrains documents that “Selenium support in IntelliJ IDEA is provided by the Test Automation plugin, and most of the features described in this section rely on it.” Basic test execution and debugging can work without that plugin. If the Selenium project option or Selenium-specific IDE support is missing, check the plugin settings. See JetBrains’ IntelliJ Selenium documentation.

3. Add Selenium to a Maven project

For an existing Maven project, add Selenium’s Java binding and a test framework dependency to the correct module’s pom.xml. This complete example uses the Selenium Java artifact and JUnit 5. The version values are examples; check the current Selenium release and your project’s Java compatibility before adopting them.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>selenium-intellij-demo</artifactId>
  <version>1.0-SNAPSHOT</version>
  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.11.4</junit.version>
    <selenium.version>4.49.0</selenium.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-java</artifactId>
      <version>${selenium.version}</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.2</version>
;      </plugin>
    </plugins>
  </build>
</project>

Note: Replace the stray semicolon before </plugin> if copying from a rendered source? No: the XML above must be valid. Here is the correct plugin block to use in place of the block above:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.5.2</version>
</plugin>

After editing pom.xml, use IntelliJ’s Maven tool window to reload the project or accept the import prompt. The Java compiler level in the Maven configuration can override IntelliJ’s Maven importer JDK setting, so make both choices deliberately. See IntelliJ Maven support and Selenium’s Java library installation guide.

4. Write and run a JUnit browser test

Save this as src/test/java/example/FirstSeleniumTest.java. The test opens Selenium’s sample form page, checks its title, and closes the browser even if an assertion fails.

package example;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

import static org.junit.jupiter.api.Assertions.assertTrue;

class FirstSeleniumTest {
    private WebDriver driver;

    @Test
    void opensTheSamplePage() {
        driver = new ChromeDriver();
        driver.get("https://www.selenium.dev/selenium/web/web-form.html");
        assertTrue(driver.getTitle().contains("Web form"));
    }

    @AfterEach
    void closeBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }
}

In IntelliJ, click the Run icon in the gutter beside the test class or method, or place the caret in the test and use the IDE’s run action. Test results appear in the Run/Test Runner window. To inspect a failure, set a breakpoint and choose Debug. For a command-line run from the project directory, use:

mvn test

Use the same teardown discipline for every test: quit() closes the whole WebDriver session and releases its browser process. Avoid sharing one mutable browser session across unrelated tests unless the suite is intentionally designed around shared state.

5. Choose Maven or Gradle, JUnit or TestNG

Choice	Use this guidance
Maven or Gradle	Follow the repository’s existing build tool. IntelliJ’s Selenium wizard supports both; use its dependency management and command-line build for consistent IDE and CI behavior.
JUnit or TestNG	Prefer the framework already used by the team. Selenium describes JUnit as widely used for Java tests and notes TestNG’s parallel execution and parameterized-test features.
IDE run or build-tool run	Use IntelliJ for authoring, focused runs, and interactive debugging. Also run through Maven or Gradle to check the project’s normal build path.

For Gradle, add the same Selenium binding and your selected test framework to the module’s build file, then sync Gradle. Exact dependency syntax depends on whether the project uses Groovy or Kotlin DSL; use the project’s existing conventions and current framework versions.

6. Make browser tests reliable

• Wait for a condition: Prefer an explicit wait for the element or state the test needs over a fixed sleep. Fixed delays waste time on fast runs and still fail when a page is slower than expected.
• Keep tests isolated: Start and close browser sessions predictably. Avoid hidden dependence on a prior test’s cookies, page, or browser state.
• Use stable selectors: Prefer selectors tied to stable IDs or deliberate test attributes where available; avoid brittle selectors based on incidental page structure.
• Account for the first run: Driver resolution may add time when Selenium downloads and verifies a required driver. Distinguish that startup delay from a page-load hang.
• Debug at the failure point: Use IntelliJ breakpoints and inspect the Run/Test Runner output, including the exception and WebDriver startup logs.

7. Common IntelliJ and Selenium errors

Symptom	Likely cause	What to check
org.openqa.selenium imports are unresolved	Selenium was added to another module, or Maven/Gradle has not synced.	Confirm selenium-java is in the test’s module build file, reload the build project, and inspect dependency resolution errors.
Test class or Run gutter icon is missing	The test framework dependency, source folder, or project SDK is not configured for the module.	Check the selected JDK, test dependency, and test source layout; try running from the class gutter and inspect the IDE’s test output.
Chrome fails to start or driver cannot be resolved	The browser is absent, the environment cannot obtain a compatible driver, or browser/driver versions are mismatched.	Confirm the browser is installed and available to the process. Review current Selenium and browser-vendor setup guidance for that environment and version.
Build works in the IDE but fails from Maven	The IDE run configuration and Maven build may use different JDK or test settings.	Compare the project SDK, Maven importer JDK, and compiler source/target values in pom.xml; run mvn test and use its error output.
Test hangs or passes inconsistently	The test may depend on a fixed delay, a changing page state, or an unclosed/shared browser session.	Wait for a specific condition, isolate session state, close the driver in teardown, and inspect the exact failing step.

8. ScreenshotNeo: capture a page without maintaining a browser setup

For browser automation and assertions, Selenium in IntelliJ is the direct workflow. If the task is to save a page image or PDF, an API can handle the capture request without a local browser-driver setup. ScreenshotNeo is a website screenshot API and MCP server for developers. Its API accepts a URL and returns a PNG, JPEG, WebP, or PDF. The API options and setup are documented at ScreenshotNeo’s API docs.

Or skip the browser setup

One GET request captures a URL. This cURL example saves a WebP file:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Equivalent Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Equivalent Node.js using built-in fetch:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

9. Cost, speed, and maintenance considerations

A Selenium test uses your own browser runtime and the resources of the machine or CI worker running it. Browser startup, page loading, and test waits contribute to run time; driver setup can add delay on an initial run. Keep tests focused, avoid unnecessary fixed waits, and close sessions to release resources.

For a Selenium workflow, the main maintenance work is keeping the Java build, test framework, browser, and driver setup compatible with the project environment. Version compatibility changes over time, so check current official documentation when updating those pieces. For screenshot-only jobs, ScreenshotNeo offers a usage-based plan structure: 1,000 monthly shots free, then paid tiers from $5 for 3,000; yearly billing gives two months free, and every feature is available on every plan.

10. Frequently asked questions

Can I use Selenium in IntelliJ without the Selenium project wizard?

Yes. Add the Selenium Java dependency and test framework to an ordinary Maven or Gradle project, then import the project and write browser tests. The wizard is a setup convenience.

Does IntelliJ include a browser or Selenium WebDriver?

No. IntelliJ is the development and test-running environment. Your test uses Selenium’s Java binding to control an installed browser through its driver implementation.

Can ScreenshotNeo replace Selenium?

It can handle website screenshot and PDF capture requests. Use Selenium when you need browser interaction and assertions as part of an automated test.

Where should I look if a version stops working?

Check the current Selenium setup guidance, browser-vendor driver notes, and IntelliJ documentation for your IDE version. The versions shown in this example are sample configuration values, not universal compatibility requirements.