Keb

Web Testing, Browser Automation, Page Object Pattern and more

Content

1. Page object pattern
2. Modules
3. Navigation
4. Waiting
5. Installation
6. Usage

Page object pattern

Keb is a https://gebish.org inspired Selenium wrapper written in Kotlin that allows you to modularize pages of your web application into logic units represented by Kotlin classes.

classKotlinHomePage : Page() {
overridefunurl() ="https://kotlinlang.org"
}

Page elements

To select web element on your page use the following methods.

css(".my-selector") // returns single DOM element by CSS selector
cssList(".my-select") // returns list of all elements found by CSS selector// following selectors are also available
html("h1")
htmlList("h1")
xpath("/html/body/h1")
xpathList("/html/body/h1")
by(MyCustomBy()) // can be used with custom implementation of org.openqa.selenium.By
byList(MyCustomBy())

In order to lazily access page content use the content delegate.

classKotlinHomePage : Page() {
overridefunurl() ="https://kotlinlang.org"val header by content { css(".global-header-logo") }
val headerText by content { header.text }
}

There are multiple options how to handle the selected content:

• cache
  • content can be cached - i.e. only initialized on first access, otherwise invoked on every access
  • usage: val title by content(cache=true) { html("h1") }
  • default value: false
• required:
  • you can specify whether the content is required to be present on the page
  • if required and the content is not present, then the org.openqa.selenium.NoSuchElementException exception is thrown, instance of org.kebish.core.EmptyContent is returned otherwise
  • usage: val title by content(required=true) { html("h1") }
  • default value: true
• wait:
  • wheter the keb should wait for the given content
  • usage:

  val title by content(wait =true) { html("h1") } // uses the default wait presetval title by content(wait =60) { html("h1") } // uses custom timeout value with retryInterval from the default wait presetval title by content(wait ="quick") { html("h1") } // uses the given wait presetval title by content(waitTimeout =10, waitRetryInterval =2) { html("h1") } // specify both timeout and retry interval

  • if content is still not present after the specified interval, the org.kebish.core.WaitTimeoutException exception is thrown
  • default value: false
  • for more info on waiting, refer to the Waiting section below

Page verifier

In order to verify, that you successfully landed on your page, you can use at method.

classKotlinHomePage : Page() {
overridefunurl() ="https://kotlinlang.org"overridefunat() = header
val header by content { css(".global-header-logo") }
}

Whether every page has to define at verifier can be controlled by configuration property atVerifierRequired. If no verifier is defined and neither is required, no page verification is performed.

Modules

If you want to reuse page content present on multiple pages, you can use modules. Module has an optional constructor parameter scope, which can be used as a search root for all the module's content. To initialize module with use the module method.

classNavMenuModule(scope:WebElement) : Module(scope) {
val menuItems by content { htmlList("a") }
}
classKotlinHomePage : Page() {
overridefunurl() ="https://kotlinlang.org"// either initialize the module by passing the module object into the 'module' methodval menu by content { module(NavMenuModule(css(".nav-links"))) }
// or initialize the module by calling the 'module' method on a WebElement and pass reference to your moduleval menu2 by content { css(".nav-links").module(::NavMenuModule) }
}

Navigation

at(::MyPage) create instance of page and wait until validator at() is satisfied

to(::MyPage) write url of page into browser and call method at()

at(::MyPage) { methodOnMyPage() } methods can have closure. Inside closure this is created page

at(::MyPage) { clickMainLink() } return result of closure

All the methods defined above can be used with constructor reference to(::MyPage) or with instance of a page to(MyPage()). Please note that constructor reference variant can only be used if the required page has no primary constructor parameters.

Both to and at methods can wait for the transition/verification of page to happen. Wait definition is same as for the content method.

val myPage = to(::MyPage, wait =true)
val myPage = to(::MyPage, wait =30)
val myPage = to(::MyPage, wait ="quick")
val myPage = to(::MyPage, waitTimeout =10, waitRetryInterval =1)
// same for the 'at' methods

Navigating pages using fluent API

val joeContact = to(::MyPage)
.via { clickOnContacts() }
.via { findContact("joe") } 

// Same as method above, but explicitly validate, that method is called on correct pageval joeContact = to(::MyPage)
.via(MyPage::class) { clickOnContacts() }
.via(ContactsPage::class) { findContact("joe") } 

Waiting

Waiting for some page element to be present, you can use waitFor method.

css(".form-input").click()
val result = waitFor {
css(".result")
}

Timeout duration and retry interval can be defined either by custom wait preset or directly through waitFor method.

waitFor(preset ="quick") { css(".result") }
waitFor(timeout =2, retryInterval =0.1) { css(".result") }

Custom wait presets can be defined using Kotlin DSL in the Configuration. Default values when no custom configuration is defined are 15 seconds for timeout and 1 second for retry interval.

kebConfig {
waiting {
timeout =15
retryInterval =1"quick" {
timeout =2
retryInterval =0.1
}
"slow" {
timeout =60 }
}
}

Installation

Relesed jar files are available in jcenter().

Gradle setup:

repositories {
jcenter()
}
val kebVersion ="<insert_actual_version>"
dependencies{
implementation("org.kebish:keb-core:$kebVersion")
implementation("org.kebish:keb-junit5:$kebVersion")
implementation("org.kebish:keb-bobril:$kebVersion")
}

If you use Keb in tests you will probably use configuration testImplementation instead of implementation

Full usage - keb + JUnit

packageorg.kebish.usageimportio.github.bonigarcia.wdm.WebDriverManagerimportorg.junit.jupiter.api.Assertionsimportorg.junit.jupiter.api.Testimportorg.kebish.core.*importorg.kebish.junit5.KebTestimportorg.openqa.selenium.WebElementimportorg.openqa.selenium.firefox.FirefoxDriverclassKotlinSiteKebTest : KebTest(Browser(kebConfig {
WebDriverManager.firefoxdriver().setup()
driver = { FirefoxDriver() }
baseUrl = "https://kotlinlang.org"
})) {
@Test
fun`testing kotlin lang page`() {
// givenval homePage = to(::KotlinHomePage)
// whenval title = homePage.header
// thenAssertions.assertEquals("Kotlin", title.text)
Assertions.assertTrue(homePage.licensedUnderApacheLicense())
// whenval docsPage = homePage.openDocumentation()
// thenAssertions.assertEquals("Learn Kotlin", docsPage.title.text)
}
}
classKotlinHomePage : Page() {
overridefunurl() ="/"overridefunat() = header
val header by content { css(".global-header-logo") }
val menu by content { module(NavMenuModule(css(".nav-links"))) }
val footer by content { module(FooterModule(html("footer"))) }
funopenDocumentation(): KotlinDocumentationPage {
menu.menuItems.first { it.text.contains("learn", ignoreCase =true) }.click()
return at(::KotlinDocumentationPage)
}
funlicensedUnderApacheLicense() = footer.licenseNotice.text.contains("apache", ignoreCase =true)
}
classKotlinDocumentationPage : Page() {
overridefunurl() ="/docs/reference"overridefunat() = title
val title by content { html("h1") }
}
classNavMenuModule(scope:WebElement) : Module(scope) {
val menuItems by content { htmlList("a") }
}
classFooterModule(scope:WebElement) : Module(scope) {
val licenseNotice by content { css(".terms-copyright") }
val sponsor by content { css(".terms-sponsor") }
}

For full usage example please refer to /keb-core/src/test/kotlin/org/kebish/usage.