Package io.karatelabs.driver

Interface CoreDriver

All Known Subinterfaces:

Driver

All Known Implementing Classes:

CdpDriver, W3cDriver

public interface CoreDriver

Core driver interface defining the primitive operations.

All driver operations reduce to a small set of primitives, with eval(js) being THE foundational primitive. This interface documents the minimal set of methods that require backend-specific implementation (CDP, WebDriver, etc.).

Tier 1: Essential Primitives

• eval(String) - Execute JavaScript (Runtime.evaluate) - THE core primitive
• navigate(String) - Navigate to URL (Page.navigate)
• keys() - Keyboard input (Input.dispatchKeyEvent)
• screenshot() - Capture screenshot (Page.captureScreenshot)
• frame(Object) - Switch frames (Page.getFrameTree + createIsolatedWorld)
• dialog(boolean, String) - Handle JS dialogs (Page.handleJavaScriptDialog)

Tier 2: Extended Primitives

• mouse() - Mouse input (Input.dispatchMouseEvent)
• pdf(Map) - Generate PDF (Page.printToPDF)
• cookie(String), cookie(Map) - Cookie operations (Network.*)
• intercept(List, InterceptHandler) - Request interception (Fetch.*)
• window(String) - Window management (Browser.*)
• tab(Object) - Tab/page switching (Target.*)

All other Driver methods (click, text, waitFor, etc.) are convenience methods that delegate to these primitives, primarily to eval().

See Also:

• Driver

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	cookie(String name)	Get a cookie by name.
void	cookie(Map<String,Object> cookie)	Set a cookie.
void	dialog(boolean accept, String input)	Handle JavaScript dialog (alert, confirm, prompt, beforeunload).
Object	eval(String js)	Execute JavaScript and return result.
void	frame(Object target)	Switch to a frame.
DriverOptions	getOptions()	Get driver options.
void	intercept(List<String> patterns, InterceptHandler handler)	Enable request interception with a handler.
boolean	isTerminated()	Check if driver is terminated.
Keys	keys()	Get a Keys object for keyboard input.
Mouse	mouse()	Get a Mouse object for mouse input.
void	navigate(String url)	Navigate to URL and wait for page load.
byte[]	pdf(Map<String,Object> options)	Generate a PDF of the current page.
void	quit()	Close driver and browser.
byte[]	screenshot()	Take screenshot and return PNG bytes.
void	tab(Object target)	Switch to a different tab/page.
void	window(String operation)	Perform window management operation.

Method Details

eval

Object eval(String js)

Execute JavaScript and return result. This is THE foundational primitive - virtually all element operations generate JavaScript that is executed via this method.

Examples:

 eval("document.title")                           // get page title
 eval("document.querySelector('#btn').click()")   // click element
 eval("document.querySelector('input').value")    // get input value
 

Parameters:

js - JavaScript expression to execute

Returns:

the result of the JavaScript execution

navigate

void navigate(String url)

Navigate to URL and wait for page load. Maps to CDP Page.navigate.

Parameters:

url - the URL to navigate to

keys

Keys keys()

Get a Keys object for keyboard input. Maps to CDP Input.dispatchKeyEvent.

Returns:

the Keys object for typing and key events

screenshot

byte[] screenshot()

Take screenshot and return PNG bytes. Maps to CDP Page.captureScreenshot.

Returns:

PNG image bytes

frame

void frame(Object target)

Switch to a frame. Maps to CDP Page.getFrameTree + Page.createIsolatedWorld.

Parameters:

target - frame identifier: - null to return to main frame - Integer for frame index - String for frame locator

dialog

void dialog(boolean accept,
 String input)

Handle JavaScript dialog (alert, confirm, prompt, beforeunload). Maps to CDP Page.handleJavaScriptDialog.

Parameters:

accept - true to accept (OK), false to dismiss (Cancel)

input - text for prompt dialogs (ignored if accept is false)

mouse

Mouse mouse()

Get a Mouse object for mouse input. Maps to CDP Input.dispatchMouseEvent.

Returns:

a new Mouse object at position (0, 0)

pdf

byte[] pdf(Map<String,Object> options)

Generate a PDF of the current page. Maps to CDP Page.printToPDF.

Parameters:

options - PDF options (scale, landscape, margins, etc.), or null for defaults

Returns:

PDF bytes

cookie

Map<String,Object> cookie(String name)

Get a cookie by name. Maps to CDP Network.getCookies.

Parameters:

name - the cookie name

Returns:

the cookie as a Map, or null if not found

cookie

void cookie(Map<String,Object> cookie)

Set a cookie. Maps to CDP Network.setCookie.

Parameters:

cookie - the cookie as a Map with keys: name, value, domain, path, etc.

intercept

void intercept(List<String> patterns,
 InterceptHandler handler)

Enable request interception with a handler. Maps to CDP Fetch.enable + Fetch.requestPaused handling.

Parameters:

patterns - URL patterns to intercept (e.g., "*api/*")

handler - the intercept handler (return InterceptResponse to mock, null to continue)

window

void window(String operation)

Perform window management operation. Maps to CDP Browser.setWindowBounds.

Parameters:

operation - one of: "maximize", "minimize", "fullscreen", "normal"

tab

void tab(Object target)

Switch to a different tab/page. Maps to CDP Target.activateTarget + Target.attachToTarget.

Parameters:

target - tab identifier: - Integer for tab index - String for title or URL substring match

quit

void quit()

Close driver and browser.

isTerminated

boolean isTerminated()

Check if driver is terminated.

getOptions

DriverOptions getOptions()

Get driver options.