UI Testing — Quickstart
This guide walks through setting up a UI test using Playwright. A Selenium variant is shown at the end.
1. Add Dependencies
Pick the artifacts that match your JUnit version — -junit6 for JUnit 6, -junit5 for JUnit 5. The clearwave example places UI testing in its own source set; the dependencies declaration below shows both drivers wired up for that source set:
loading...
The version-catalog entries those libs.* references resolve to:
loading...
Find the latest version on GitHub releases.
Before running Playwright tests for the first time, install the browsers once. Add a Gradle task that runs the Playwright CLI:
loading...
Then run ./gradlew installPlaywrightBrowsers once. Selenium 4.x auto-manages ChromeDriver — no extra setup needed.
2. Define a User Stub
A user stub is a page object that extends UserStub<D>, where D is your BrowserDriver type. It exposes a typed driver property — driver.page for Playwright, driver.webDriver for Selenium. Call screenshot("label") at any point to capture the current page state.
The clearwave example pairs each driver with its own user stub class in the same file:
loading...
3. Write a UI Test
Extend KensaPlaywrightUiTest<U> — driver creation is handled for you (headless Chromium by default). Provide createUser(driver) and mix in WithKotest so the then(collector, matcher) DSL is available. The theUser property gives you the typed user stub inside each test method.
Configure Kensa in a @BeforeAll companion method — set sourceLocations to point at your UI test sources so sentence parsing works correctly.
loading...
What's happening here
| Element | Purpose |
|---|---|
KensaPlaywrightUiTest<U> | Base class — creates a Playwright driver per test |
WithKotest | Mixin enabling the then(collector, matcher) DSL |
createUser(driver) | Wraps the driver in your user stub |
theUser | Typed user stub instance; available in given/and/whenever blocks |
uiTesting.autoScreenshotOnFailure | If true, captures a screenshot automatically on test failure |
sourceLocations | Tells Kensa where to find your UI test sources for sentence parsing |
Named givens (theFeasibilityServiceCanOfferFibre, theUserOpensTheFeasibilityPage, …) | Wrap the implementation away from the rendered test body so the report reads as fluent prose |
then(collector, matcher) with named matchers (shouldShowAtLeastOneProfile) | Keeps assertions semantic in the report — never raw matcher calls in the test body |
Customising the driver
To launch headed, slow Playwright down for debugging, or pass extra args, override configureLaunchOptions:
override fun configureLaunchOptions(options: BrowserType.LaunchOptions) {
options.setHeadless(false).setSlowMo(100.0)
}
If you need full control over driver creation (different browser type, custom BrowserContext, etc.), extend KensaUiTest<U> directly and implement createDriver() / createUser() yourself.
4. Run the Tests
If you've placed UI tests in a custom source set (e.g., uiTest):
./gradlew uiTest
Or run them alongside regular tests:
./gradlew test
After the run, open build/kensa-output-ui/index.html in a browser, or serve it with the Kensa CLI:
kensa --dir build/kensa-output-ui
Each test invocation includes a Screenshots tab in the HTML report showing all captured screenshots in order.
5. Selenium Variant
For Selenium, extend KensaSeleniumUiTest<U>. Defaults to headless Chrome with CI-friendly flags. Override configureChromeOptions to customise.
loading...
The Selenium user stub accesses driver.webDriver instead of driver.page. The given/and/whenever/then DSL and screenshot() calls are identical:
loading...