Define site configuration

Kolibrium is flexible and lets you configure element readiness checks, wait strategies, and decorators. These cross‑cutting defaults live on a Site — a single place to express how your application under test should behave during tests.

A Site centralizes:

• The baseUrl of your app
• Declarative cookies to install for every new session
• Default waiting behavior (timeouts, polling, messages)
• Default decorators applied to WebDriver/WebElement interactions
• Readiness predicates for elements and element collections
• Optional local DriverService for managing browser drivers
• Optional hooks for additional per‑site tweaks

Define a Site

Create an object that extends Site and override the parts you want to change.

Note: to use isClickable in the examples below, import dev.kolibrium.webdriver.isClickable (or dev.kolibrium.webdriver.*).

object MySite : Site(baseUrl = "https://example.com") {
    override val elementReadyCondition: WebElement.() -> Boolean = { isClickable }

    override val elementsReadyCondition: WebElements.() -> Boolean = { isClickable }

    override val waitConfig: WaitConfig = WaitConfig.Default.copy(
        pollingInterval = 250.milliseconds,
        timeout = 5.seconds,
    )

    override val decorators: List<AbstractDecorator> = listOf(
        HighlighterDecorator(color = Color.Green, width = 5),
        SlowMotionDecorator(wait = 1.seconds),
        ElementStateCacheDecorator(cacheDisplayed = true, cacheEnabled = true),
    )

    // Optional: cookies that should always exist for this origin
    override val cookies: Set<Cookie> = setOf(
        Cookie("ab", "test"),
        Cookie("locale", "en-US"),
    )

    // Optional: local DriverService for managing browser drivers
    override val service: DriverService? = ChromeDriverService.createDefaultService()
}

With the above configuration:

• isClickable is used by default to decide when elements/collections are ready
• Waits poll every 250 milliseconds with a 5 second timeout
• All SearchContext instances (WebDriver and WebElement) are decorated with:
  • a green highlight outline for visual feedback
  • a 1 second delay after each interaction
  • caching for positive displayed/enabled checks

Notes:

• Kolibrium ignores org.openqa.selenium.NoSuchElementException during waits by default.
• Unless overridden, the default timeout message is "Condition not met within timeout" (see WaitConfig.Default).

Lifecycle and hooks

A Site can customize behavior declaratively (properties) and imperatively (hooks):

• onSessionReady(driver) — session‑aware hook called after cookies are applied

Order during a test run:

1. Navigate to baseUrl to establish origin
2. Apply Site.cookies (if any), then re‑navigate to baseUrl so they take effect immediately
3. Call Site.onSessionReady(driver)

Do not navigate inside onSessionReady; predictable navigation is owned by the DSL.

Example of a dynamic tweak in onSessionReady:

override fun onSessionReady(driver: WebDriver) {
    System.getenv("RUN_TOKEN")?.let { token ->
        driver.manage().addCookie(Cookie("auth", token))
    }
}

Using your Site in tests

Bind a Site using the DSL:

seleniumTest(site = MySite, driverFactory = { createDriver() }) {
    // your test steps; pages will use MySite's defaults
}

Site binding is handled automatically by the DSL; pages and components will use the configured Site defaults.

Decorators and precedence

Site-level and test-level decorators are merged (site first, then test). Duplicates are de-duplicated by class; on conflict, the test-level instance wins. You can layer additional test‑level decorators via DecoratorManager.

DecoratorManager.withDecorators(HighlighterDecorator()) {
    // run a test with extra highlighting in addition to Site decorators
}