Package io.karatelabs.driver.w3c

Class W3cDriver

java.lang.Object
io.karatelabs.driver.w3c.W3cDriver
All Implemented Interfaces:
CoreDriver, Driver, io.karatelabs.js.ObjectLike, io.karatelabs.js.SimpleObject
public class W3cDriver extends Object implements Driver
W3C WebDriver protocol driver implementation. Single class supporting all W3C-compatible browser drivers (chromedriver, geckodriver, safaridriver, msedgedriver) via the W3cBrowserType enum.

Uses java.net.http.HttpClient for W3C protocol communication, cleanly separated from scenario HTTP state.

CDP-only operations (intercept, PDF, ariaTree, Mouse) throw UnsupportedOperationException.

  • Method Details

    • start

      public static W3cDriver start(Map<String,Object> config)
      Start a WebDriver from a config map. If webDriverUrl is set, connects to remote. Otherwise, launches the driver process.

    • connect

      public static W3cDriver connect(String webDriverUrl, W3cDriverOptions opts)
      Connect to an existing WebDriver server (remote hub, SauceLabs, etc.).

    • getSession

      public W3cSession getSession()
      Get the underlying W3C session for direct protocol access.

    • eval

      public Object eval(String js)
      Execute JavaScript via W3C executeScript.

      Battle-tested pattern from v1 WebDriver: if JS execution fails, sleep once and retry before throwing. This handles transient failures that occur when the page is still loading or transitioning. The v1 codebase proved this single-retry approach effective across thousands of real-world test suites.

      W3C element references in the result are auto-wrapped as W3cElement instances.

      Specified by:
      eval in interface CoreDriver
      Specified by:
      eval in interface Driver
      Parameters:
      js - JavaScript expression to execute
      Returns:
      the result of the JavaScript execution

    • keys

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

    • screenshot

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

    • frame

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

    • dialog

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

    • mouse

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

    • pdf

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

    • cookie

      public Map<String,Object> cookie(String name)
      Description copied from interface: Driver
      Get a cookie by name.
      Specified by:
      cookie in interface CoreDriver
      Specified by:
      cookie in interface Driver
      Parameters:
      name - the cookie name
      Returns:
      the cookie as a Map, or null if not found

    • cookie

      public void cookie(Map<String,Object> cookie)
      Description copied from interface: Driver
      Set a cookie.
      Specified by:
      cookie in interface CoreDriver
      Specified by:
      cookie in interface Driver
      Parameters:
      cookie - the cookie as a Map with keys: name, value, domain, path, etc.

    • intercept

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

    • window

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

    • tab

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

    • click

      public Element click(String locator)
      Description copied from interface: Driver
      Click an element.
      Specified by:
      click in interface Driver

    • input

      public Element input(String locator, String value)
      Description copied from interface: Driver
      Input text into an element (focus, clear, type). For time/date inputs that don't respond to CDP keystrokes, uses JS value assignment.
      Specified by:
      input in interface Driver

    • clear

      public Element clear(String locator)
      Description copied from interface: Driver
      Clear an input element.
      Specified by:
      clear in interface Driver

    • focus

      public Element focus(String locator)
      Description copied from interface: Driver
      Focus an element.
      Specified by:
      focus in interface Driver

    • scroll

      public Element scroll(String locator)
      Description copied from interface: Driver
      Scroll an element into view.
      Specified by:
      scroll in interface Driver

    • highlight

      public Element highlight(String locator)
      Description copied from interface: Driver
      Highlight an element (for debugging).
      Specified by:
      highlight in interface Driver

    • text

      public String text(String locator)
      Description copied from interface: Driver
      Get the text content of an element.
      Specified by:
      text in interface Driver

    • html

      public String html(String locator)
      Description copied from interface: Driver
      Get the outer HTML of an element.
      Specified by:
      html in interface Driver

    • value

      public String value(String locator)
      Description copied from interface: Driver
      Get the value of an input element.
      Specified by:
      value in interface Driver

    • attribute

      public String attribute(String locator, String name)
      Description copied from interface: Driver
      Get an attribute of an element.
      Specified by:
      attribute in interface Driver

    • enabled

      public boolean enabled(String locator)
      Description copied from interface: Driver
      Check if an element is enabled.
      Specified by:
      enabled in interface Driver

    • exists

      public boolean exists(String locator)
      Description copied from interface: Driver
      Check if an element exists.
      Specified by:
      exists in interface Driver

    • locateAll

      public List<Element> locateAll(String locator)
      Description copied from interface: Driver
      Find all elements matching a locator. Implementation requires driver-specific indexed locator support.
      Specified by:
      locateAll in interface Driver

    • waitFor

      public Element waitFor(String locator)
      Description copied from interface: Driver
      Wait for an element to exist.
      Specified by:
      waitFor in interface Driver

    • waitFor

      public Element waitFor(String locator, Duration timeout)
      Description copied from interface: Driver
      Wait for an element to exist with custom timeout.
      Specified by:
      waitFor in interface Driver

    • waitForAny

      public Element waitForAny(String locator1, String locator2)
      Description copied from interface: Driver
      Wait for any of the locators to match.
      Specified by:
      waitForAny in interface Driver

    • waitForAny

      public Element waitForAny(String[] locators)
      Description copied from interface: Driver
      Wait for any of the locators to match.
      Specified by:
      waitForAny in interface Driver

    • waitForAny

      public Element waitForAny(String[] locators, Duration timeout)
      Description copied from interface: Driver
      Wait for any of the locators to match with custom timeout.
      Specified by:
      waitForAny in interface Driver

    • waitForText

      public Element waitForText(String locator, String expected)
      Description copied from interface: Driver
      Wait for an element to contain specific text.
      Specified by:
      waitForText in interface Driver

    • waitForText

      public Element waitForText(String locator, String expected, Duration timeout)
      Description copied from interface: Driver
      Wait for an element to contain specific text with custom timeout.
      Specified by:
      waitForText in interface Driver

    • waitForEnabled

      public Element waitForEnabled(String locator)
      Description copied from interface: Driver
      Wait for an element to be enabled.
      Specified by:
      waitForEnabled in interface Driver

    • waitForEnabled

      public Element waitForEnabled(String locator, Duration timeout)
      Description copied from interface: Driver
      Wait for an element to be enabled with custom timeout.
      Specified by:
      waitForEnabled in interface Driver

    • waitForUrl

      public String waitForUrl(String expected)
      Description copied from interface: Driver
      Wait for URL to contain expected string.
      Specified by:
      waitForUrl in interface Driver

    • waitForUrl

      public String waitForUrl(String expected, Duration timeout)
      Description copied from interface: Driver
      Wait for URL to contain expected string with custom timeout.
      Specified by:
      waitForUrl in interface Driver

    • waitUntil

      public Element waitUntil(String locator, String expression)
      Description copied from interface: Driver
      Wait until a JavaScript expression on an element evaluates to truthy.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

      public Element waitUntil(String locator, String expression, Duration timeout)
      Description copied from interface: Driver
      Wait until a JavaScript expression on an element evaluates to truthy.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

      public boolean waitUntil(String expression)
      Description copied from interface: Driver
      Wait until a JavaScript expression evaluates to truthy.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

      public boolean waitUntil(String expression, Duration timeout)
      Description copied from interface: Driver
      Wait until a JavaScript expression evaluates to truthy with custom timeout.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

      public Object waitUntil(Supplier<Object> condition)
      Description copied from interface: Driver
      Wait until a supplier returns a truthy value.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

      public Object waitUntil(Supplier<Object> condition, Duration timeout)
      Description copied from interface: Driver
      Wait until a supplier returns a truthy value with custom timeout.
      Specified by:
      waitUntil in interface Driver

    • waitForResultCount

      public List<Element> waitForResultCount(String locator, int count)
      Description copied from interface: Driver
      Wait for a specific number of elements to match.
      Specified by:
      waitForResultCount in interface Driver

    • waitForResultCount

      public List<Element> waitForResultCount(String locator, int count, Duration timeout)
      Description copied from interface: Driver
      Wait for a specific number of elements to match with custom timeout.
      Specified by:
      waitForResultCount in interface Driver

    • getUrl

      public String getUrl()
      Description copied from interface: Driver
      Get current URL.
      Specified by:
      getUrl in interface Driver

    • getTitle

      public String getTitle()
      Description copied from interface: Driver
      Get page title.
      Specified by:
      getTitle in interface Driver

    • deleteCookie

      public void deleteCookie(String name)
      Description copied from interface: Driver
      Delete a cookie by name.
      Specified by:
      deleteCookie in interface Driver

    • clearCookies

      public void clearCookies()
      Description copied from interface: Driver
      Clear all cookies.
      Specified by:
      clearCookies in interface Driver

    • getCookies

      public List<Map<String,Object>> getCookies()
      Description copied from interface: Driver
      Get all cookies.
      Specified by:
      getCookies in interface Driver

    • getDimensions

      public Map<String,Object> getDimensions()
      Description copied from interface: Driver
      Get window dimensions and position.
      Specified by:
      getDimensions in interface Driver

    • setDimensions

      public void setDimensions(Map<String,Object> dimensions)
      Description copied from interface: Driver
      Set window dimensions and/or position.
      Specified by:
      setDimensions in interface Driver

    • getPages

      public List<String> getPages()
      Description copied from interface: Driver
      Get list of all page targets (tabs).
      Specified by:
      getPages in interface Driver

    • getDialog

      public Dialog getDialog()
      Description copied from interface: Driver
      Get the current dialog if one is open. This is useful for detecting dialogs that appear after actions.
      Specified by:
      getDialog in interface Driver
      Returns:
      the current Dialog, or null if no dialog is open

    • onDialog

      public void onDialog(DialogHandler handler)
      Description copied from interface: Driver
      Register a handler for JavaScript dialogs (alert, confirm, prompt, beforeunload).
      Specified by:
      onDialog in interface Driver

    • setUrl

      public void setUrl(String url)
      Description copied from interface: Driver
      Navigate to URL and wait for page load.
      Specified by:
      setUrl in interface Driver

    • waitForPageLoad

      public void waitForPageLoad(PageLoadStrategy strategy)
      Description copied from interface: Driver
      Wait for page to load based on strategy.
      Specified by:
      waitForPageLoad in interface Driver

    • waitForPageLoad

      public void waitForPageLoad(PageLoadStrategy strategy, Duration timeout)
      Description copied from interface: Driver
      Wait for page to load with custom timeout.
      Specified by:
      waitForPageLoad in interface Driver

    • refresh

      public void refresh()
      Description copied from interface: Driver
      Refresh the current page.
      Specified by:
      refresh in interface Driver

    • reload

      public void reload()
      Description copied from interface: Driver
      Reload the page ignoring cache.
      Specified by:
      reload in interface Driver

    • back

      public void back()
      Description copied from interface: Driver
      Navigate back in history.
      Specified by:
      back in interface Driver

    • forward

      public void forward()
      Description copied from interface: Driver
      Navigate forward in history.
      Specified by:
      forward in interface Driver

    • script

      public Object script(String expression)
      Description copied from interface: Driver
      Execute JavaScript and return result.
      Specified by:
      script in interface Driver

    • screenshot

      public byte[] screenshot(boolean embed)
      Description copied from interface: Driver
      Take screenshot, optionally embed in report.
      Specified by:
      screenshot in interface Driver

    • screenshot

      public byte[] screenshot(String locator, boolean embed)
      Element-clipped screenshot via the W3C GET /session/{id}/element/{eid}/screenshot endpoint.
      Specified by:
      screenshot in interface Driver

    • getDialogText

      public String getDialogText()
      Description copied from interface: Driver
      Get the current dialog message.
      Specified by:
      getDialogText in interface Driver

    • dialog

      public void dialog(boolean accept)
      Description copied from interface: Driver
      Accept or dismiss the current dialog.
      Specified by:
      dialog in interface Driver

    • switchFrame

      public void switchFrame(int index)
      Description copied from interface: Driver
      Switch to an iframe by index.
      Specified by:
      switchFrame in interface Driver

    • switchFrame

      public void switchFrame(String locator)
      Description copied from interface: Driver
      Switch to an iframe by locator, or null to return to main frame.
      Specified by:
      switchFrame in interface Driver

    • getCurrentFrame

      public Map<String,Object> getCurrentFrame()
      Description copied from interface: Driver
      Get the current frame info, or null if in main frame.
      Specified by:
      getCurrentFrame in interface Driver

    • maximize

      public void maximize()
      Description copied from interface: Driver
      Maximize the browser window.
      Specified by:
      maximize in interface Driver

    • minimize

      public void minimize()
      Description copied from interface: Driver
      Minimize the browser window.
      Specified by:
      minimize in interface Driver

    • fullscreen

      public void fullscreen()
      Description copied from interface: Driver
      Make the browser window fullscreen.
      Specified by:
      fullscreen in interface Driver

    • activate

      public void activate()
      Description copied from interface: Driver
      Activate the browser window (bring to front).
      Specified by:
      activate in interface Driver

    • pdf

      public byte[] pdf()
      Description copied from interface: Driver
      Generate a PDF of the current page with default options.
      Specified by:
      pdf in interface Driver

    • mouse

      public Mouse mouse(String locator)
      Description copied from interface: Driver
      Get a Mouse object positioned at an element's center.
      Specified by:
      mouse in interface Driver

    • mouse

      public Mouse mouse(Number x, Number y)
      Description copied from interface: Driver
      Get a Mouse object at specified coordinates.
      Specified by:
      mouse in interface Driver

    • switchPage

      public void switchPage(String titleOrUrl)
      Description copied from interface: Driver
      Switch to a page by title or URL substring.
      Specified by:
      switchPage in interface Driver

    • switchPage

      public void switchPage(int index)
      Description copied from interface: Driver
      Switch to a page by index.
      Specified by:
      switchPage in interface Driver

    • intercept

      public void intercept(InterceptHandler handler)
      Description copied from interface: Driver
      Enable request interception for all requests.
      Specified by:
      intercept in interface Driver

    • stopIntercept

      public void stopIntercept()
      Description copied from interface: Driver
      Stop request interception.
      Specified by:
      stopIntercept in interface Driver

    • close

      public void close()
      Description copied from interface: Driver
      Alias for quit().
      Specified by:
      close in interface Driver

    • quit

      public void quit()
      Description copied from interface: Driver
      Close driver and browser.
      Specified by:
      quit in interface CoreDriver
      Specified by:
      quit in interface Driver

    • isTerminated

      public boolean isTerminated()
      Description copied from interface: Driver
      Check if driver is terminated.
      Specified by:
      isTerminated in interface CoreDriver
      Specified by:
      isTerminated in interface Driver

    • getOptions

      public DriverOptions getOptions()
      Description copied from interface: Driver
      Get driver options.
      Specified by:
      getOptions in interface CoreDriver
      Specified by:
      getOptions in interface Driver