Package io.karatelabs.driver

Interface Driver

All Superinterfaces:
CoreDriver, io.karatelabs.js.ObjectLike, io.karatelabs.js.SimpleObject
All Known Implementing Classes:
CdpDriver, W3cDriver
public interface Driver extends CoreDriver, io.karatelabs.js.SimpleObject
Browser automation driver interface. Provides a unified API for browser automation across different backends (CDP, Playwright, WebDriver).

This interface extends CoreDriver which defines the ~12 primitive operations. Most methods in this interface are convenience methods that delegate to those primitives, primarily to CoreDriver.eval(String).

Phase 8: Extracted from CdpDriver to enable multi-backend support.

Phase 9: Implements ObjectLike for Gherkin/DSL integration (JS property access).

Phase 10: Extends CoreDriver to clearly separate primitives from convenience methods.

See Also:

  • Method Details

    • jsGet

      default Object jsGet(String name)
      Get a property value or method by name for JavaScript access. Properties return values directly; methods return JavaCallables.
      Specified by:
      jsGet in interface io.karatelabs.js.SimpleObject

    • putMember

      default void putMember(String name, Object value)
      Set a property value by name for JavaScript assignment. Supports: driver.url = '...', driver.dimensions = {...}
      Specified by:
      putMember in interface io.karatelabs.js.ObjectLike
      Specified by:
      putMember in interface io.karatelabs.js.SimpleObject

    • eval

      default Object eval(String js)
      Execute JavaScript. Delegates to script(String).
      Specified by:
      eval in interface CoreDriver
      Parameters:
      js - JavaScript expression to execute
      Returns:
      the result of the JavaScript execution

    • eval

      default Object eval(Object expression)
      Execute JavaScript with support for JsFunction. Delegates to script(Object).
      Parameters:
      expression - JavaScript expression as String or JsFunction
      Returns:
      the result of the JavaScript execution

    • frame

      default void frame(Object target)
      Switch frames. Dispatches to switchFrame(int) or switchFrame(String).
      Specified by:
      frame in interface CoreDriver
      Parameters:
      target - frame identifier: - null to return to main frame - Integer for frame index - String for frame locator

    • window

      default void window(String operation)
      Window management. Dispatches to maximize(), minimize(), fullscreen().
      Specified by:
      window in interface CoreDriver
      Parameters:
      operation - one of: "maximize", "minimize", "fullscreen", "normal"

    • tab

      default void tab(Object target)
      Tab switching. Dispatches to switchPage(int) or switchPage(String).
      Specified by:
      tab in interface CoreDriver
      Parameters:
      target - tab identifier: - Integer for tab index - String for title or URL substring match

    • setUrl

      void setUrl(String url)
      Navigate to URL and wait for page load.

    • getUrl

      String getUrl()
      Get current URL.

    • getTitle

      String getTitle()
      Get page title.

    • waitForPageLoad

      void waitForPageLoad(PageLoadStrategy strategy)
      Wait for page to load based on strategy.

    • waitForPageLoad

      void waitForPageLoad(PageLoadStrategy strategy, Duration timeout)
      Wait for page to load with custom timeout.

    • refresh

      void refresh()
      Refresh the current page.

    • reload

      void reload()
      Reload the page ignoring cache.

    • back

      void back()
      Navigate back in history.

    • forward

      void forward()
      Navigate forward in history.

    • script

      Object script(String expression)
      Execute JavaScript and return result.

    • script

      default Object script(Object expression)
      Execute JavaScript with support for JsFunction. If the argument is a JsFunction (e.g., arrow function), it will be serialized to its source code and invoked as an IIFE.

      Examples:

       script("document.title")                    // string expression
 script(() => document.title)                // arrow function (from Karate JS)
 script(() => { return document.title })     // arrow function with block body
      Parameters:
      expression - JavaScript expression as String or JsFunction
      Returns:
      the result of the JavaScript execution

    • script

      default Object script(String locator, Object expression)
      Execute a script on an element. The element is available as '_' in the expression. Expression can be a String ("_.value") or JsFunction (_ => _.value).

    • scriptAll

      default List<Object> scriptAll(String locator, Object expression)
      Execute a script on all matching elements. Each element is available as '_' in the expression. Expression can be a String or JsFunction.

    • screenshot

      byte[] screenshot()
      Take screenshot and return PNG bytes.
      Specified by:
      screenshot in interface CoreDriver
      Returns:
      PNG image bytes

    • screenshot

      byte[] screenshot(boolean embed)
      Take screenshot, optionally embed in report.

    • onDialog

      void onDialog(DialogHandler handler)
      Register a handler for JavaScript dialogs (alert, confirm, prompt, beforeunload).

    • getDialogText

      String getDialogText()
      Get the current dialog message.

    • dialog

      void dialog(boolean accept)
      Accept or dismiss the current dialog.

    • dialog

      void dialog(boolean accept, String input)
      Accept or dismiss the current dialog with optional prompt input.
      Specified by:
      dialog in interface CoreDriver
      Parameters:
      accept - true to accept (OK), false to dismiss (Cancel)
      input - text for prompt dialogs (ignored if accept is false)

    • getDialog

      Dialog getDialog()
      Get the current dialog if one is open. This is useful for detecting dialogs that appear after actions.
      Returns:
      the current Dialog, or null if no dialog is open

    • switchFrame

      void switchFrame(int index)
      Switch to an iframe by index.

    • switchFrame

      void switchFrame(String locator)
      Switch to an iframe by locator, or null to return to main frame.

    • getCurrentFrame

      Map<String,Object> getCurrentFrame()
      Get the current frame info, or null if in main frame.

    • submit

      default Driver submit()
      Mark the next action as triggering a page navigation. After the next click/action, the driver will wait for the page to change (detected by URL or document element hash change).

      Works on all backends (CDP, WebDriver, Playwright).

      Usage: submit().click('#button')

    • waitIfSubmitRequested

      default void waitIfSubmitRequested()
      If submit() was called, wait for the document to change after running the action.

    • click

      default Element click(String locator)
      Click an element.

    • focus

      default Element focus(String locator)
      Focus an element.

    • clear

      default Element clear(String locator)
      Clear an input element.

    • input

      default Element input(String locator, String value)
      Input text into an element (focus, clear, type). For time/date inputs that don't respond to CDP keystrokes, uses JS value assignment.

    • value

      default Element value(String locator, String value)
      Set the value of an input element directly.

    • select

      default Element select(String locator, String text)
      Select an option from a dropdown by text or value.

    • select

      default Element select(String locator, int index)
      Select an option from a dropdown by index.

    • scroll

      default Element scroll(String locator)
      Scroll an element into view.

    • highlight

      default Element highlight(String locator)
      Highlight an element (for debugging).

    • text

      default String text(String locator)
      Get the text content of an element.

    • html

      default String html(String locator)
      Get the outer HTML of an element.

    • value

      default String value(String locator)
      Get the value of an input element.

    • attribute

      default String attribute(String locator, String name)
      Get an attribute of an element.

    • property

      default Object property(String locator, String name)
      Get a property of an element.

    • enabled

      default boolean enabled(String locator)
      Check if an element is enabled.

    • exists

      default boolean exists(String locator)
      Check if an element exists.

    • position

      default Map<String,Object> position(String locator)
      Get the position of an element (absolute).

    • position

      default Map<String,Object> position(String locator, boolean relative)
      Get the position of an element.
      Parameters:
      relative - if true, returns viewport-relative position

    • locate

      default Element locate(String locator)
      Find an element by locator. This is a convenience method that creates an Element wrapper.

    • locateAll

      List<Element> locateAll(String locator)
      Find all elements matching a locator. Implementation requires driver-specific indexed locator support.

    • optional

      default Element optional(String locator)
      Find an element that may not exist (optional). This is a convenience method that creates an optional Element wrapper.

    • waitFor

      Element waitFor(String locator)
      Wait for an element to exist.

    • waitFor

      Element waitFor(String locator, Duration timeout)
      Wait for an element to exist with custom timeout.

    • waitForAny

      Element waitForAny(String locator1, String locator2)
      Wait for any of the locators to match.

    • waitForAny

      Element waitForAny(String[] locators)
      Wait for any of the locators to match.

    • waitForAny

      Element waitForAny(String[] locators, Duration timeout)
      Wait for any of the locators to match with custom timeout.

    • waitForText

      Element waitForText(String locator, String expected)
      Wait for an element to contain specific text.

    • waitForText

      Element waitForText(String locator, String expected, Duration timeout)
      Wait for an element to contain specific text with custom timeout.

    • waitForEnabled

      Element waitForEnabled(String locator)
      Wait for an element to be enabled.

    • waitForEnabled

      Element waitForEnabled(String locator, Duration timeout)
      Wait for an element to be enabled with custom timeout.

    • waitForUrl

      String waitForUrl(String expected)
      Wait for URL to contain expected string.

    • waitForUrl

      String waitForUrl(String expected, Duration timeout)
      Wait for URL to contain expected string with custom timeout.

    • waitUntil

      Element waitUntil(String locator, String expression)
      Wait until a JavaScript expression on an element evaluates to truthy.

    • waitUntil

      Element waitUntil(String locator, String expression, Duration timeout)
      Wait until a JavaScript expression on an element evaluates to truthy.

    • waitUntil

      boolean waitUntil(String expression)
      Wait until a JavaScript expression evaluates to truthy.

    • waitUntil

      boolean waitUntil(String expression, Duration timeout)
      Wait until a JavaScript expression evaluates to truthy with custom timeout.

    • waitUntil

      Object waitUntil(Supplier<Object> condition)
      Wait until a supplier returns a truthy value.

    • waitUntil

      Object waitUntil(Supplier<Object> condition, Duration timeout)
      Wait until a supplier returns a truthy value with custom timeout.

    • waitForResultCount

      List<Element> waitForResultCount(String locator, int count)
      Wait for a specific number of elements to match.

    • waitForResultCount

      List<Element> waitForResultCount(String locator, int count, Duration timeout)
      Wait for a specific number of elements to match with custom timeout.

    • cookie

      Map<String,Object> cookie(String name)
      Get a cookie by name.
      Specified by:
      cookie in interface CoreDriver
      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.
      Specified by:
      cookie in interface CoreDriver
      Parameters:
      cookie - the cookie as a Map with keys: name, value, domain, path, etc.

    • deleteCookie

      void deleteCookie(String name)
      Delete a cookie by name.

    • clearCookies

      void clearCookies()
      Clear all cookies.

    • getCookies

      List<Map<String,Object>> getCookies()
      Get all cookies.

    • maximize

      void maximize()
      Maximize the browser window.

    • minimize

      void minimize()
      Minimize the browser window.

    • fullscreen

      void fullscreen()
      Make the browser window fullscreen.

    • getDimensions

      Map<String,Object> getDimensions()
      Get window dimensions and position.

    • setDimensions

      void setDimensions(Map<String,Object> dimensions)
      Set window dimensions and/or position.

    • activate

      void activate()
      Activate the browser window (bring to front).

    • pdf

      byte[] pdf(Map<String,Object> options)
      Generate a PDF of the current page.
      Specified by:
      pdf in interface CoreDriver
      Parameters:
      options - PDF options (scale, landscape, margins, etc.), or null for defaults
      Returns:
      PDF bytes

    • pdf

      byte[] pdf()
      Generate a PDF of the current page with default options.

    • mouse

      Mouse mouse()
      Get a Mouse object at position (0, 0).
      Specified by:
      mouse in interface CoreDriver
      Returns:
      a new Mouse object at position (0, 0)

    • mouse

      Mouse mouse(String locator)
      Get a Mouse object positioned at an element's center.

    • mouse

      Mouse mouse(Number x, Number y)
      Get a Mouse object at specified coordinates.

    • keys

      Keys keys()
      Get a Keys object for keyboard input.
      Specified by:
      keys in interface CoreDriver
      Returns:
      the Keys object for typing and key events

    • getPages

      List<String> getPages()
      Get list of all page targets (tabs).

    • switchPage

      void switchPage(String titleOrUrl)
      Switch to a page by title or URL substring.

    • switchPage

      void switchPage(int index)
      Switch to a page by index.

    • switchPageById

      default void switchPageById(String targetId)
      Switch to a page by its backend target ID.

      Useful in conjunction with drainOpenedTargets() — the drained entries carry a targetId which unambiguously identifies the new tab, while URL/title can be ambiguous (e.g. blank or duplicated across tabs).

      Default implementation delegates to switchPage(String) using the target ID as a substring match; most drivers should override.

    • drainOpenedTargets

      default List<Map<String,Object>> drainOpenedTargets()
      Drain and return the list of new page targets (tabs) opened since the last call.

      Event-driven — no CDP round-trip. Each entry is a map with targetId, url, and title. Returns an empty list if nothing new was opened.

      Use case: an automation that clicks a link with target="_blank" or a button that calls window.open() can call this after the click to learn whether (and where) a new tab appeared, and then call switchPage(String) or switchPage(int) to focus it.

      Mirrors the getDialog() pattern — the driver pushes events into an internal queue and the caller drains it, avoiding polling Target.getTargets after every action.

      Default implementation returns an empty list for drivers that don't track target events.

    • rightOf

      default Finder rightOf(String locator)
      Create a finder for elements to the right of the reference element. This is a convenience method that creates a Finder.

    • leftOf

      default Finder leftOf(String locator)
      Create a finder for elements to the left of the reference element. This is a convenience method that creates a Finder.

    • above

      default Finder above(String locator)
      Create a finder for elements above the reference element. This is a convenience method that creates a Finder.

    • below

      default Finder below(String locator)
      Create a finder for elements below the reference element. This is a convenience method that creates a Finder.

    • near

      default Finder near(String locator)
      Create a finder for elements near the reference element. This is a convenience method that creates a Finder.

    • intercept

      void intercept(List<String> patterns, InterceptHandler handler)
      Enable request interception with a handler.
      Specified by:
      intercept in interface CoreDriver
      Parameters:
      patterns - URL patterns to intercept (e.g., "*api/*")
      handler - the intercept handler (return InterceptResponse to mock, null to continue)

    • intercept

      void intercept(InterceptHandler handler)
      Enable request interception for all requests.

    • stopIntercept

      void stopIntercept()
      Stop request interception.

    • quit

      void quit()
      Close driver and browser.
      Specified by:
      quit in interface CoreDriver

    • close

      void close()
      Alias for quit().

    • isTerminated

      boolean isTerminated()
      Check if driver is terminated.
      Specified by:
      isTerminated in interface CoreDriver

    • isResponsive

      default boolean isResponsive()
      Quick health check — returns false if the driver's underlying protocol channel (CDP websocket, WebDriver session, etc.) is stuck or unresponsive. MUST use a short timeout so the caller doesn't block on a poisoned driver.

      Used by PooledDriverProvider to decide whether a driver can be returned to the pool safely. The default here returns true (backends that can't cheaply probe the channel are assumed healthy). CDP overrides with a bounded Runtime.evaluate.

    • getOptions

      DriverOptions getOptions()
      Get driver options.
      Specified by:
      getOptions in interface CoreDriver