Skip to main content

Getting Started

Get your first Selenium Boot test running in under 5 minutes.

Prerequisites​

  • Java 17+
  • Maven 3.8+ or Gradle 7+
  • Chrome or Firefox installed
info

No WebDriver binaries required — Selenium Manager handles browser driver downloads automatically.

Step 1 — Add the dependency​

pom.xml
<dependency>
    <groupId>io.github.seleniumboot</groupId>
    <artifactId>selenium-boot</artifactId>
    <version>3.3.0</version>
</dependency>
Using Gradle?

See the full Gradle Setup Guide for parallel config, JUnit 5, optional deps, and report locations.

Step 2 — Create the configuration file​

Create selenium-boot.yml in your project root (next to pom.xml or build.gradle). This example uses https://example.com — a stable real site reserved for documentation — so you can copy the files as-is and mvn test goes green. Swap in your own URL once it passes.

selenium-boot.yml
execution:
  mode: local
  baseUrl: https://example.com

browser:
  name: chrome
  headless: false

retry:
  enabled: true
  maxAttempts: 2

timeouts:
  explicit: 10
  pageLoad: 30

Step 3 — Write your first test​

Copy this as-is — it passes against the baseUrl from Step 2 with a real Chrome, no changes needed:

src/test/java/SmokeTest.java
import com.seleniumboot.locator.Role;
import com.seleniumboot.test.BaseTest;
import org.testng.annotations.Test;

public class SmokeTest extends BaseTest {

    @Test
    public void opensThePage() {
        open();  // navigates to baseUrl
        assertThat(getByRole(Role.HEADING, "Example Domain")).isVisible();
    }
}

getByRole finds elements the way a screen reader does, and assertThat(...).isVisible() retries until the timeout instead of failing on the first miss — so no WebDriverWait, no CSS selectors, no Thread.sleep().

Testing your own app?

Once this passes, point execution.baseUrl at your app and replace the assertion with a locator for your page — e.g. assertThat(getByRole(Role.BUTTON, "Sign in")).isVisible().

Step 4 — Create a TestNG suite​

testng.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="selenium-boot-suite" verbose="1">
    <test name="MyTests">
        <classes>
            <class name="SmokeTest"/>
        </classes>
    </test>
</suite>

Step 5 — Run​

mvn test

What happens​

  1. Framework loads selenium-boot.yml
  2. Chrome launches automatically
  3. Your test runs
  4. Screenshot captured on any failure
  5. Browser closes
  6. HTML report generated at target/selenium-boot-report.html (Maven) or build/selenium-boot-report/ (Gradle)
  7. Metrics JSON at target/selenium-boot-metrics.json

Project structure​

your-project/
├── pom.xml
├── selenium-boot.yml
├── testng.xml
└── src/test/java/
    └── SmokeTest.java

Working example project​

A complete working project is available at: https://github.com/seleniumboot/selenium-boot-test

Clone it, run mvn test (or ./gradlew test), and you'll have a full working suite with page objects, step logging, and retry configured.

Next steps​