How to Run Selenium Tests with Selenide, IntelliJ, and Maven

To run Selenium tests with Selenide, create a Java Maven project, add Selenide and a test framework to pom.xml, write a test under src/test/java, then run it from IntelliJ IDEA or with mvn test. Selenide uses Selenium WebDriver and provides fluent browser actions and condition assertions that wait for the expected page state.

This guide uses JUnit 5 and Selenide 7.18.2. Selenide’s current quick start lists that version; check the project page when creating a new project because releases change. Selenide is compatible with Selenium WebDriver 4.0 and later, according to the Selenide project.

1. Create a Java Maven project in IntelliJ IDEA

Install a JDK and make sure IntelliJ IDEA uses it for the project. In IntelliJ, check File → Project Structure → Project and select the project SDK.
Create a Maven project, or open an existing Maven project. IntelliJ’s new project flow can create a Java Maven project and lets you select a JDK and test framework. See the IntelliJ Selenium documentation.
Use Maven’s standard layout: production code in src/main/java, tests in src/test/java, and test resources in src/test/resources.
Use a JDK supported by your chosen Selenide and test-framework releases. Keep the JDK selected in IntelliJ consistent with the JDK used by Maven in your terminal or CI.

2. Add Selenide and JUnit to Maven

Add Selenide and a test engine to pom.xml. This example uses JUnit Jupiter. The Selenide dependency and version follow its quick start; the JUnit dependencies are declared explicitly so Maven can compile and discover the test.

<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>com.example</groupId>
  <artifactId>selenide-demo</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.13.4</junit.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.codeborne</groupId>
      <artifactId>selenide</artifactId>
      <version>7.18.2</version>
      <scope>test</scope>
    </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.3</version>
;        </plugin>
    </plugins>
  </build>
</project>

Correction before using: In the plugin block above, ensure the closing line reads </plugin> with no preceding punctuation. The complete valid plugin block is:

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

Use the current versions approved by your project for JUnit and Maven Surefire. The Selenide version above is from its published quick start. IntelliJ will prompt you to reload Maven after saving; click the reload action or use the Maven tool window’s reimport control.

If your project uses TestNG, Cucumber, ScalaTest, or JBehave instead, select that framework and include its matching Maven dependencies and runner configuration. Selenide lists these frameworks as options, but the dependency block here is specifically for JUnit Jupiter.

3. Write a first Selenide test

Create src/test/java/com/example/LoginTest.java. Replace the sample URL, field names, button selector, and expected text with values from your application. The example uses a public demo target solely to show the structure; real tests should target an environment you control.

package com.example;

import static com.codeborne.selenide.Condition.disappear;
import static com.codeborne.selenide.Condition.text;
import static com.codeborne.selenide.Selenide.$;
import static com.codeborne.selenide.Selenide.open;

import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;

class LoginTest {
  @Test
  void userCanLogIn() {
    open("https://your-app.example/login");
    $(By.name("user.name")).setValue("johny");
    $("#submit").click();
    $(".loading_progress").should(disappear);
    $("#username").shouldHave(text("Hello, Johny!"));
  }
}

The Selenide quick-start example uses the same core pattern: open a page, locate with $, perform actions such as setValue and click, then assert a condition. A condition assertion waits for the condition up to Selenide’s configured timeout; it is usually more reliable than inserting a fixed sleep. See the quick-start example.

Choose selectors that survive UI changes

Prefer stable IDs, accessible attributes, or app-owned test attributes such as data-testid where available.
Use CSS selectors with $("#submit") for a single element. Use $$(".row") when you need a collection.
Use Selenium’s By locators when useful, for example $(By.name("email")).
Avoid selectors tied to generated class names or deep DOM structure if the application can provide a stable test hook.

Wait for states, not arbitrary time

Use conditions such as shouldBe(visible), shouldHave(text("Saved")), or should(disappear) to express the state the test needs. A fixed pause can be too short on a slow run and waste time on a fast run. If the application has an asynchronous transition, assert its observable result.

4. Run the test from IntelliJ IDEA

Open the test class and wait for IntelliJ to import Maven dependencies.
Click the green gutter icon beside the test class or test method, then choose Run. For debugging, choose Debug.
Read the result in the Run tool window. Failed assertions include the condition that was not met; use the stack trace and browser state to locate the failing step.

IntelliJ can run tests using its test runner. You can also configure it to delegate test execution to Maven. Basic running and debugging work without the Test Automation plugin; additional Selenium-specific IDE features may rely on it. Refer to JetBrains’ Selenium support page and Maven testing documentation.

5. Run tests with Maven

From the directory containing pom.xml, run all tests with:

mvn test

Run one test class by name:

mvn -Dtest=LoginTest test

Run one test method with Surefire’s method selector:

mvn -Dtest=LoginTest#userCanLogIn test

In IntelliJ, open the Maven tool window and select Lifecycle → test. To run a single test using Maven, create or modify a Maven run configuration and enter -Dtest=LoginTest test. IntelliJ documents both the IDE runner and Maven delegation in its Maven testing guide.

IntelliJ runner or Maven?

Route	Best use	What runs it
IntelliJ gutter action	Quick feedback, breakpoints, and interactive debugging	IntelliJ’s test runner unless configured to delegate
Maven tool window	Run the project’s build lifecycle without leaving the IDE	Maven goals
Terminal `mvn test`	Repeatable local and CI command	Maven and its configured test plugins

For an issue that appears only in CI or Maven, reproduce it with the same Maven command and JDK before changing the test. IDE and command-line execution can differ if they use different JDKs, environment variables, profiles, or working directories.

6. Configure browser, timeout, and other settings

Selenide settings can be passed as JVM system properties, set in code, or stored in src/test/resources/selenide.properties. The Selenide FAQ documents these configuration methods and shows properties including browser, timeout, and remote endpoint.

Set properties on a Maven run

mvn test -Dselenide.browser=firefox -Dselenide.timeout=6000

Use the browser value supported in your environment. Selenide’s FAQ names Chrome, Firefox, Edge, Internet Explorer, Safari, and Opera among browser options, subject to WebDriver availability and local setup. A browser may need to be installed and compatible with its driver.

Use a properties file

Create src/test/resources/selenide.properties:

selenide.browser=chrome
selenide.timeout=6000
selenide.browserSize=1440x900

Keep machine-specific or secret values out of a committed file. Use CI-provided environment variables or protected run configuration settings for credentials and remote endpoints.

Set configuration in test setup

import com.codeborne.selenide.Configuration;
import org.junit.jupiter.api.BeforeAll;

class LoginTest {
  @BeforeAll
  static void configureBrowser() {
    Configuration.browser = "chrome";
    Configuration.timeout = 6000;
    Configuration.browserSize = "1440x900";
  }
}

Pick one clear configuration source for each setting. Avoid setting a value in multiple places unless you understand which source wins. Increase a timeout only when the application has a legitimate slower state; a large timeout can make a missing element take much longer to diagnose.

7. Run on Selenium Grid or another remote browser

For a local first run, let Selenide start a browser on the same machine as the test. To use Selenium Grid, configure its WebDriver endpoint using selenide.remote:

mvn test -Dselenide.remote=https://your-grid.example/wd/hub

The endpoint must be reachable from the test process and accept the capabilities your browser configuration requests. Selenide’s FAQ says most functionality works with Grid out of the box, while features such as file downloads may require the com.codeborne:selenide-grid dependency. Check the current Grid documentation for version alignment and feature-specific setup.

Remote execution is useful when browsers run on shared machines, multiple browser versions are needed, or execution must happen in a controlled environment. It adds network and service dependencies: a slow or unavailable Grid can look like a slow test. Keep the Grid URL and credentials outside source control, and distinguish browser startup failures from application assertion failures in logs.

8. Troubleshoot common failures

Symptom	Likely cause	Fix
IntelliJ does not show a Run icon, or test imports are red	Maven has not synced, the test source directory is not recognized, or the test dependency is missing.	Reload Maven; confirm the class is under `src/test/java`; check the chosen framework dependency and annotation imports.
`No tests were executed`	The test class or method does not match the runner’s discovery rules, or the wrong test framework is configured.	Use a conventional class name such as `LoginTest`, verify the JUnit annotation import, and run `mvn -Dtest=LoginTest test`. Check Surefire and framework configuration.
`Could not resolve dependencies`	Maven cannot reach the repository, the artifact version is unavailable, or a proxy/settings configuration is wrong.	Check the exact coordinates, network access, Maven settings, and repository configuration; then reload Maven.
Browser or driver fails to start	Browser is absent, incompatible, blocked by the environment, or not configured for headless execution.	Install a supported browser, check browser and driver compatibility, and inspect startup output. In containers or CI, configure the browser environment explicitly.
Element not found or condition times out	Wrong selector, wrong page, delayed rendering, or a state the test never reaches.	Confirm the URL and selector in the actual page; assert a meaningful condition; inspect the failure screenshot or page source if available; raise the timeout only when justified.
Test passes in IntelliJ but fails with Maven	Different JDK, environment, working directory, Maven profile, or runner settings.	Compare the IDE and terminal JDKs and environment. Reproduce with the exact Maven command and profile used in CI.
Grid session cannot be created	Incorrect endpoint, inaccessible Grid, unsupported browser capability, or missing authentication.	Verify the endpoint from the test host, check Grid logs and requested browser, and provide credentials through protected configuration.
Remote file download behaves differently	Some remote features need an integration module or have Grid-specific behavior.	Consult Selenide’s cloud documentation and add `com.codeborne:selenide-grid` when the feature requires it.

9. Performance, reliability, and cost

Prefer condition waits. They wait for the expected state and avoid paying the time cost of a fixed sleep on every run.
Keep browser scope purposeful. Browser startup and remote session creation add overhead. Run focused tests while iterating, then run the suite through Maven for build verification.
Control parallelism. Parallel browser tests can reduce elapsed time, but require enough browser capacity and isolated test data. Avoid parallelizing tests that mutate shared accounts or state.
Stabilize the environment. Pin compatible JDK, dependency, browser, and Grid configuration in the build environment. Diagnose environmental failures separately from application behavior.
Budget for infrastructure. Local browser testing uses local compute; Grid or hosted browser infrastructure may have its own resource or service costs. No universal runtime or cost figure applies because it depends on the app, browser, test suite, and environment.

10. Capture a page image without writing a browser test

Selenide is for browser UI tests: it exercises interactions and assertions. If the task is simply to save a page image for a report, review, or downstream workflow, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It returns a screenshot or PDF from a single GET request. See the ScreenshotNeo API documentation for parameters and response details.

Or skip the browser setup

Use the API call below to capture a page as WebP. Replace the URL and API key with your target and key. This is a capture service, not a replacement for assertions or interactive Selenium tests.

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

ScreenshotNeo can accept cookie and consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Every feature is available on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

11. FAQ

Is Selenide the same thing as Selenium?

No. Selenide is a Java UI testing framework built on Selenium WebDriver. It supplies a fluent API and condition-based waits while using WebDriver to control the browser.

Can I use TestNG instead of JUnit?

Yes. Selenide supports TestNG as well as several other test frameworks. Add the dependencies and runner configuration for the framework your project uses.

Do I need IntelliJ’s Test Automation plugin?

No for basic test running and debugging. JetBrains says those basics work without the plugin; additional IDE assistance is provided by its Test Automation plugin.

Can Selenide run in CI?

Yes. Run the Maven test command in the CI job and configure the JDK, browser environment, and any remote endpoint there. Selenide’s FAQ points to CI examples using Maven, Gradle, and Ant.

When should I use ScreenshotNeo instead?

Use it when you need a page capture or PDF through an API or MCP tool. Keep Selenide for tests that need browser interactions and assertions about application behavior.