Skip to main content

Caching elements

Element caching is a performance optimization technique that reduces test execution time by eliminating unnecessary repeated searches for frequently accessed elements. When an element is cached, Kolibrium first finds the element then stores the result for all future usages, minimizing DOM (Document Object Model) searches and improving performance.

Caching mechanics​

Default behavior​

By default, Kolibrium caches single-element delegates. The first element lookup is stored and reused in subsequent accesses, reducing the overhead of repeated element searches. Multi-element delegates are not cached.

Disabling caching (single element)​

By setting cacheLookup = false, Kolibrium will perform a new DOM search each time the element is accessed. This is useful for dynamic pages with frequently changing content.

val dynamicContent by driver.className(
    value = "changing-content",
    cacheLookup = false // A new lookup will be performed each time the element is accessed.
)

Multi-element lookups​

Delegates that return multiple elements (e.g., classNames, cssSelectors, dataQas, dataTests, dataTestIds, names, linkTexts, partialLinkTexts, tagNames, xpaths) always perform a fresh lookup and are not cached. These delegates do not support cacheLookup.

val dynamicList by driver.classNames("dynamic-items") // always re-fetched, no cache
val dataItems by driver.dataQas("item") // always re-fetched, no cache
note

Use this feature with caution.

Disabled cacheLookup can significantly increase the number of issued findElement(s) commands because Kolibrium doesn't store the result when it locates an element. Instead, it always relocates the element first, which can lead to unnecessary overhead.

Stale elements and cache invalidation​

If a cached element becomes stale during lookup or readiness checks, Kolibrium clears its cache and re-locates the element automatically before retrying. To benefit from this behavior, avoid keeping long‑lived references to WebElement; access the delegated property when you need the element.