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 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.core.selenium.isClickable (or dev.kolibrium.core.selenium.*).

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"),
    )
}

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 border 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):

• configureSite() — no‑arg hook for quick per‑site tweaks that don't need a session
• 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.configureSite()
4. 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

You can bind a Site explicitly using the DSL, or without the DSL using SiteContext.

• With the DSL webTest harness:

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

• Without the DSL (core only):

SiteContext.withSite(MySite) {
    // create and use your WebDriver and page objects here
}

Decorators and precedence

Decorators defined on the Site are applied first. You can layer additional test‑level decorators via DecoratorManager; duplicates are de‑duplicated by class with test‑level winning.

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