Home / Modules / yoja-selenium

yoja-selenium

Browser-driven tests with a fluent TestBuilder: pick a browser, start an embedded server, run named JS exports as test steps, capture browser logs, integrate as JUnit 6 dynamic tests.

Installation

testImplementation 'com.easygoingapi:yoja-selenium:VERSION'

Requires a matching Selenium WebDriver on the test classpath (chromedriver, geckodriver, msedgedriver), either on PATH or via Selenium Manager.

Quick start

import com.easygoingapi.yoja.selenium.*;
import org.junit.jupiter.api.*;
import java.util.stream.Stream;

class TaskBoardTest {

    @TestFactory
    Stream<DynamicNode> scenarios() {
        return TestBuilder.builder()
            .browser(Browser.builder(Browser.CHROME)
                            .mode(Browser.Mode.HEADLESS)
                            .build())
            .startYojaWeb()
            .loadYwAssert()
            .testJsUnit("/jsUnitSyncTest.js",
                        List.of("titleIsTaskManager", "loginFormIsPresent"))
            .testAsyncModule("/jsUnitAsyncTest.js")
            .stream();
    }
}

Browser

`Browser` enum

Supported browsers. Each value maps to a Selenium WebDriver implementation.

Values

Value	Description
`CHROME` · `FIREFOX` · `EDGE`	Supported browsers; require the matching WebDriver on `PATH` or via Selenium Manager

API

Signature	Returns	Description
`getWebDriverClass()`	`Class<WebDriver>`	Selenium driver class for this browser
`static builder(Browser)`	`Browser.Builder`	Start a `Config` builder

Browser.Mode

Value	Description
`HEADLESS`	No visible window
`HEADFUL`	Visible window
`DEBUGGER`	Pins all timeouts to 1 hour and opens devtools

Browser.Config (Builder)

Signature	Returns	Description
`Builder.mode(Mode)`	`Builder`
`Builder.timeout(Duration)`	`Builder`	Default wait timeout for element lookups
`Builder.build()`	`Browser.Config`
`getBrowser()`	`Browser`
`getMode()`	`Mode`
`getTimeout()`	`Duration`

SeleniumService

`SeleniumService` class (AutoCloseable)

High-level wrapper around a WebDriver, tailored to driving Yoja-Web pages.

Factory

Signature	Returns	Description
`static newInstance(Browser.Config)`	`SeleniumService`	Launch the browser with the right options
`webDriver()`	`WebDriver`	Underlying Selenium driver
`javascriptExecutor()`	`JavascriptExecutor`

Navigation

Signature	Returns	Description
`getHttpPage(HttpUrl \| String)`	`void`	Navigate the browser to the given URL
`getHttpPage(Duration, HttpUrl \| String)`	`void`	Navigate with an explicit wait timeout
`reload()`	`void`	Reload the current page
`reload(ScriptOption)`	`void`	Reload and re-inject helpers
`await(Duration)`	`void`	Pause execution for the given duration
`resizeWindow(int w, int h)`	`void`	Set the browser window dimensions

Script execution

Signature	Returns	Description
`executeScript(String \| Path [, args])`	`Object`	Execute synchronous JS
`executeScript(Duration, String \| Path, args)`	`Object`	With an explicit timeout
`executeAsyncScript(String \| Path [, args])`	`Object`	Execute async JS (must call the injected `done` callback)
`repeatScript(Duration until, String, args)`	`Object`	Re-execute until a truthy value is returned or the timeout elapses
`repeatAsyncScript(Duration, String, args)`	`Object`	Async variant of `repeatScript`

DOM queries

Signature	Returns	Description
`firstTag(css)`	`WebElement`	First matching element (waits for presence)
`firstTag(Duration, css)`	`WebElement`	With an explicit wait timeout
`firstTagFrom(WebElement, css)`	`WebElement`	Scoped to a given element
`findTags(css)`	`List<WebElement>`	All matching elements
`findTagsFrom(WebElement, css)`	`List<WebElement>`	Scoped to a given element

Storage accessors

Signature	Returns	Description
`localStorage(key)`	`String`	Raw value from `window.localStorage`
`localStorage(key, Storage)`	`String`	`Storage.date` / `type` / `value` — extract a specific field from the stored JSON
`sessionStorage(key [, Storage])`	`String`	Same for `window.sessionStorage`

Logs & helpers

Signature	Returns	Description
`logs()`	`List<Log>`	All browser-side log entries collected so far
`clearLogs()`	`void`	Discard captured log entries
`saveLogs()`	`void`	Persist logs to disk
`printLogs()`	`void`	Print logs to stdout
`loadJavascript(String)`	`void`	Inject a JS snippet into the current page
`loadYwAssert()`	`void`	Inject the `ywAssert.js` assertion helper
`debugger()`	`void`	IDE breakpoint hook
`close()`	`void`	Quit the WebDriver

TestBuilder

`TestBuilder` class

Fluent orchestrator. Builds a list of test steps, then runs them via execute() or exposes them as JUnit dynamic nodes via stream().

Factory

Signature	Returns	Description
`static builder()`	`TestBuilder`

Configuration

Signature	Returns	Description
`browser(Browser.Config)`	`TestBuilder`	Select browser and mode
`host(String)`	`TestBuilder`	Override embedded server host
`contentType(String ext, String mime)`	`TestBuilder`	Extension → MIME mapping for static serving
`webResource(String packageName [, contextPath [, url]])`	`TestBuilder`	Serve resources from a classpath package
`webResource(WebApp, String url)`	`TestBuilder`	Serve resources from a `WebApp`
`webResource(WebResource)`	`TestBuilder`	Serve a pre-built `WebResource`
`webService(WebService)`	`TestBuilder`	Add a service endpoint to the embedded server
`webSocket(WebSocket)`	`TestBuilder`	Add a WebSocket endpoint to the embedded server

Bootstrap steps

Signature	Returns	Description
`startJavascript([ScriptOption])`	`TestBuilder`	Step: serve a minimal HTML fixture and navigate to it
`startYojaWeb([ScriptOption])`	`TestBuilder`	Step: serve a full Yoja-Web fixture page and navigate to it
`getPage(String path)`	`TestBuilder`	Step: navigate to the given path on the embedded server

Test steps

Signature	Returns	Description
`test(String name, Consumer<TestContext>)`	`TestBuilder`	Add a custom named step
`testJsUnit(String path, List<String> functions, args...)`	`TestBuilder`	Run named JS exports as individual test steps
`testModule(String path, args...)`	`TestBuilder`	Run a synchronous JS module as a test step
`testAsyncModule([Duration,] String path, args...)`	`TestBuilder`	Run an async JS module; optional timeout
`loadModule(String path)`	`TestBuilder`	Step: load a JS module without asserting on its result
`repeatTestModuleUntil(Duration, String path, args...)`	`TestBuilder`	Step: retry the module until it returns truthy or the timeout elapses

Utility steps

Signature	Returns	Description
`reload([ScriptOption])`	`TestBuilder`	Step: reload the current page
`resizeWindow(int w, int h)`	`TestBuilder`	Step: resize the browser window
`await(Duration)`	`TestBuilder`	Step: pause execution
`loadYwAssert()`	`TestBuilder`	Step: inject `ywAssert.js`
`saveLogs()`	`TestBuilder`	Step: persist browser logs to disk
`printLogs()`	`TestBuilder`	Step: print browser logs to stdout
`debugger()`	`TestBuilder`	Step: IDE breakpoint hook

Run

Signature	Returns	Description
`execute([boolean keepRunning])`	`void`	Run all steps sequentially; optionally keep the browser open after completion
`stream()`	`Stream<DynamicNode>`	Expose steps as JUnit 6 `@TestFactory` dynamic nodes

`ScriptOption` class

Controls which helpers are injected after page navigation.

Signature	Returns	Description
`static apply()`	`ScriptOption`	Fresh option with all flags off
`saveLogs()`	`ScriptOption`	Install the `ywLogger.js` log capture helper
`loadYwAssert()`	`ScriptOption`	Install the `ywAssert.js` assertion helper

Test context

`TestContext` class (AutoCloseable)

Per-test handle injected into every Consumer<TestContext> step. Closing it shuts down both the embedded server and the WebDriver.

Signature	Returns	Description
`browser()`	`Browser`	Active browser enum value
`seleniumService()`	`SeleniumService`	The wrapped WebDriver instance
`httpServerContext()`	`HttpServerContext`	Embedded HTTP server details
`httpUrlBuilder()`	`HttpUrlBuilder`	URL builder pre-configured for the embedded server
`logs()`	`List<Log>`	Browser-side log entries
`getHttpPage(HttpUrl \| String [, Duration])`	`void`	Navigate the browser; optional explicit timeout
`close()`	`void`	Stop the embedded server and quit the WebDriver

`HttpServerContext` · `HttpUrlBuilder` classes

Embedded Yoja HTTP server serving test fixtures. Port auto-assigned from a monotonically-increasing sequence starting at 8888.

HttpServerContext

Signature	Returns	Description
`host()`	`String`	Embedded server hostname
`port()`	`int`	Auto-assigned port
`httpServerState()`	`State`	Server lifecycle state
`httpUrlBuilder()`	`HttpUrlBuilder`	URL builder pre-wired for this server
`close()`	`void`	Stop the embedded server

HttpUrlBuilder

Signature	Returns	Description
`path(String \| Path)`	`HttpUrlBuilder`
`query(String \| HttpParameter)`	`HttpUrlBuilder`	Query string
`fragment(String)`	`HttpUrlBuilder`	URL hash fragment
`build()`	`HttpUrl`	Build the full URL pointing at the embedded server

Logs

`Log` · `Log.Level` classes

Browser-side log entry collected by ywLogger.js and surfaced via SeleniumService.logs().

Log accessors

Signature	Returns	Description
`date()`	`Instant`	Time the log entry was captured
`level()`	`Level`
`message()`	`String`

Log.Level values

Value	Description
`LOG · TRACE · DEBUG · INFO · WRAN · ERROR`	Mirror the browser-side console levels; `WRAN` is intentional (matches the JS side)

`DateUtil` · `Debugger` · `SeleniumException` helpers

Class	Key API	Description
`DateUtil`	`formatTimestamp(Long \| Instant)`	Format a timestamp as `yyyy-MM-dd HH:mm:ss` in the JVM timezone
`Debugger`	`debugger()`	IDE breakpoint hook — throws and immediately catches a `Debugger` exception
`SeleniumException`		Runtime exception for WebDriver, script and embedded-server failures

Module README: yoja-selenium/README.md.

yoja-selenium

Installation

Quick start

Browser

Browser enum

SeleniumService

SeleniumService class (AutoCloseable)

TestBuilder

TestBuilder class

ScriptOption class