description	Complete selenium-boot.yml configuration reference: browser, parallel threads, timeouts, retry, and CI quality gates, every option in one place.
id	configuration
title	Configuration Reference
sidebar_position	3

Configuration Reference

All framework behaviour is controlled by selenium-boot.yml.

File resolution order

The framework looks for the config file in this priority order:

System property — -Dselenium.boot.config=/path/to/custom.yml
Working directory — ./selenium-boot.yml (next to pom.xml)
Classpath — src/test/resources/selenium-boot.yml
Built-in defaults — used only when none of the above exist and no profile or explicit path was requested. The framework prints one line saying so.

A requested profile (-Dselenium.boot.profile=staging) or explicit path that cannot be found is always an error, so a typo never silently runs against defaults.

Defaults for omitted fields

A file only has to say what it wants to change. Anything it leaves out (or an empty file) falls back to:

Field	Default
`browser.name`	`chrome` (not applied when `browser.matrix` is set)
`execution.mode`	`local`
`timeouts.explicit`	`10`
`timeouts.pageLoad`	`30`

Values that are present but invalid — an unknown execution.mode, a negative timeout — still fail at startup.

Full reference

# ── Browser ────────────────────────────────────────────────────────────────
browser:
  name: chrome              # chrome | firefox | edge | safari
  headless: false           # true in CI (auto-forced when CI detected)
  lifecycle: per-test       # per-test (default) | per-suite
  # version: "120.0.6099.109"  # optional: pin local Chrome/Firefox to an exact build

  # Optional: extra browser arguments
  arguments:
    - --start-maximized
    - --disable-notifications

  # Optional: raw capability overrides
  capabilities:
    acceptInsecureCerts: true

# ── Execution ───────────────────────────────────────────────────────────────
execution:
  mode: local               # local | remote | browserstack | saucelabs | lambdatest
  baseUrl: https://your-app.com
  gridUrl: http://localhost:4444   # only for remote mode

  parallel: none            # none | methods | classes | tests | instances
  threadCount: 1            # ignored when parallel: none
  maxActiveSessions: 5      # max concurrent browser instances (semaphore)

  # ── BrowserStack (mode: browserstack) ──────────────────────────────────────
  browserstack:
    username:      ${BS_USER}
    accessKey:     ${BS_KEY}
    os:            Windows          # Windows | OS X
    osVersion:     "11"
    browser:       chrome           # chrome | firefox | edge | safari
    browserVersion: latest
    device:                         # optional — mobile device name
    realMobile:    true
    capabilities:                   # raw bstack:options overrides
      debug: false

  # ── Sauce Labs (mode: saucelabs) ───────────────────────────────────────────
  saucelabs:
    username:      ${SAUCE_USER}
    accessKey:     ${SAUCE_KEY}
    region:        us-west-1        # us-west-1 | eu-central | apac-southeast
    platformName:  "Windows 11"
    browser:       chrome
    browserVersion: latest
    capabilities:                   # raw sauce:options overrides
      recordVideo: true

# ── Locators ─────────────────────────────────────────────────────────────────
locators:
  selfHealing: false        # auto-retry failed locators with derived fallbacks
  testIdAttribute: data-testid  # attribute used by getByTestId()

# ── Retry ───────────────────────────────────────────────────────────────────
retry:
  enabled: true             # applies to all tests globally
  maxAttempts: 2            # total attempts (1 = no retry)

# ── Timeouts ────────────────────────────────────────────────────────────────
timeouts:
  explicit: 10              # seconds — WaitEngine default timeout
  pageLoad: 30              # seconds — browser page load timeout

# ── CI / Build Quality Gates ────────────────────────────────────────────────
ci:
  failOnPassRateBelow: 80   # 0 = disabled. Fail build if pass rate < 80%
  maxFlakyTests: 3          # -1 = disabled. Fail if more than 3 tests retried

# ── Database Assertions ─────────────────────────────────────────────────────
database:
  url:      jdbc:postgresql://localhost/mydb
  username: ${DB_USER}
  password: ${DB_PASS}
  driver:   org.postgresql.Driver  # optional; auto-detected from URL by most drivers

  # Named datasources (access via db("reporting"))
  datasources:
    reporting:
      url:      jdbc:postgresql://localhost/reporting
      username: ${REPORTING_DB_USER}
      password: ${REPORTING_DB_PASS}

# ── Multi-Session Testing ───────────────────────────────────────────────────
sessions:
  maxPerTest: 2   # max named sessions per test (guard against resource leaks)

# ── Email Verification ──────────────────────────────────────────────────────
email:
  provider: mailhog          # mailhog | mailtrap | outlook | imap
  timeoutSeconds: 30         # default wait for waitForEmail()
  pollIntervalMs: 1000       # polling interval
  autoClear: false           # clear inbox before each test automatically

  mailhog:
    host: localhost
    port: 8025

  mailtrap:
    apiToken:  ${MAILTRAP_TOKEN}
    accountId: ${MAILTRAP_ACCOUNT_ID}
    inboxId:   ${MAILTRAP_INBOX_ID}

  outlook:
    tenantId:     ${AZURE_TENANT_ID}
    clientId:     ${AZURE_CLIENT_ID}
    clientSecret: ${AZURE_CLIENT_SECRET}
    mailbox:      test-inbox@yourcompany.com

  imap:
    host:     imap.gmail.com
    port:     993
    ssl:      true
    username: ${EMAIL_USER}
    password: ${EMAIL_PASS}
    folder:   INBOX

# ── Clock Mocking ────────────────────────────────────────────────────────────
clock:
  injectHeader: false      # send X-Mock-Date header to server
  headerName: X-Mock-Date

Browser

`name`

The browser to use. Selenium Manager downloads the matching driver automatically.

Value	Browser
`chrome`	Google Chrome (default)
`firefox`	Mozilla Firefox
`edge`	Microsoft Edge
`safari`	Safari (macOS only)

`headless`

Runs the browser without a visible window. Automatically forced to true when a CI environment is detected (GitHub Actions, Jenkins, etc.).

`version`

Pins a local Chrome or Firefox run to an exact browser version, for when "passes on my laptop, fails in CI" is a browser-version mismatch. Passed to Selenium Manager, which resolves and downloads the matching build. Optional — omit it to use whatever browser is installed. Ignored by remote, browserstack and saucelabs modes (those use their own browserVersion).

`lifecycle`

Controls when the WebDriver session is closed.

Value	Behaviour
`per-test`	Browser opens and closes for every test method (default — full isolation)
`per-suite`	Browser stays open for the entire suite; one instance per thread, closed at suite end

:::tip When to use per-suite Use per-suite when your suite has many sequential tests and browser startup time is a bottleneck. The browser retains cookies and state between tests — plan your test flow accordingly. :::

Execution

`parallel`

Maps directly to TestNG parallel execution mode. Thread count is set via threadCount. Selenium Boot validates this value at suite bootstrap against TestNG's own set of modes; an unrecognised value fails immediately with a message naming both the rejected value and the accepted ones.

Value	Behaviour
`none`	Sequential execution (default)
`methods`	Each `@Test` method runs in its own thread
`classes`	Each test class runs in its own thread
`tests`	Each `<test>` in the suite XML runs in its own thread
`instances`	Each test class instance runs in its own thread

`maxActiveSessions`

Maximum concurrent browser instances. Tests wait (up to 30s) for a slot rather than failing immediately. Prevents resource exhaustion in parallel runs.

Retry

`enabled`

When true, all test methods are retried on failure up to maxAttempts times. Set to false to disable retry globally.

Use @Retryable on a method to override the global setting for that specific test.

@Test
@Retryable(maxAttempts = 3)
public void flakyTest() { ... }

Locators

`selfHealing`

When true, a locator that fails inside waitForVisible / waitForClickable is automatically retried with fallback strategies derived from the original By descriptor (extract id, name, text, class, data-testid, or placeholder). Healed tests get a ⚠ healed badge in the HTML report, and every heal is written to target/healed-locators.json. Off by default. See Self-Healing Locators.

`testIdAttribute`

The HTML attribute resolved by getByTestId(). Defaults to data-testid; set it to data-qa, data-test, etc. to match your app. See Semantic Locators.

Debug

Live-triage aids for watching a test run on your own machine. Dev-only — keep them off in CI: they slow the run down and modify the page. Both are off by default and cost nothing when off.

debug:
  slowMoMs: 300     # pause after each Locator action (ms); 0 = off
  highlight: true   # red outline on the element just before each Locator action

`slowMoMs`

Sleeps for the given number of milliseconds after every terminal Locator action (click, type, getText, hover, …), so you can follow the browser by eye.

`highlight`

Applies outline: 2px solid red to the resolved element immediately before the action. The outline is left in place afterwards, so you can see what was touched.

These complement trace and recording: TraceRecorder / RecordingManager give you a post-mortem after the test finishes; debug lets you watch it live.

Environment profiles

Override the default config for a specific environment using a profile suffix:

selenium-boot.yml            ← base config
selenium-boot-staging.yml    ← staging overrides
selenium-boot-prod.yml       ← prod overrides

Activate with:

mvn test -Dselenium.boot.profile=staging

Only the fields present in the profile file are overridden — everything else falls back to the base config.

Switching browser from the command line

Pick the browser for a single run without editing any file:

mvn test -Dbrowser=firefox

-Dselenium.boot.browser=firefox does the same and wins if both are set. The value replaces browser.name from selenium-boot.yml, any profile, and SeleniumBootDefaults. It also replaces browser.matrix: asking for one browser runs only that browser. Values are case-insensitive; a blank value is ignored.

Gradle runs tests in a separate JVM, so forward the property in build.gradle. See Gradle setup.

Navigation Menu

Repository navigation

configuration.md

configuration.md

Configuration Reference

File resolution order

Defaults for omitted fields

Full reference

Browser

`name`

`headless`

`version`

`lifecycle`

Execution

`parallel`

`maxActiveSessions`

Retry

`enabled`

Locators

`selfHealing`

`testIdAttribute`

Debug

`slowMoMs`

`highlight`

Environment profiles

Switching browser from the command line

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration Reference

File resolution order

Defaults for omitted fields

Full reference

Browser

name

headless

version

lifecycle

Execution

parallel

maxActiveSessions

Retry

enabled

Locators

selfHealing

testIdAttribute

Debug

slowMoMs

highlight

Environment profiles

Switching browser from the command line

`name`

`headless`

`version`

`lifecycle`

`parallel`

`maxActiveSessions`

`enabled`

`selfHealing`

`testIdAttribute`

`slowMoMs`

`highlight`