Package io.karatelabs.driver.cdp

Class CdpDriver

java.lang.Object
io.karatelabs.driver.cdp.CdpDriver
All Implemented Interfaces:
CoreDriver, Driver, io.karatelabs.js.ObjectLike, io.karatelabs.js.SimpleObject
public class CdpDriver extends Object implements Driver
CDP-based browser driver implementation. Implements the Driver interface using Chrome DevTools Protocol.

  • Method Details

    • addCdpEventListener

      public void addCdpEventListener(CdpEventListener listener)
      Add an external event listener that receives all CDP events. Used for traffic recording, debugging, etc.
      Parameters:
      listener - The listener to add

    • removeCdpEventListener

      public void removeCdpEventListener(CdpEventListener listener)
      Remove an external event listener.
      Parameters:
      listener - The listener to remove

    • start

      public static CdpDriver start(CdpDriverOptions options)
      Launch a new browser and create driver.

    • start

      public static CdpDriver start()
      Launch a new browser with default options.

    • startHeadless

      public static CdpDriver startHeadless()
      Launch a headless browser.

    • connect

      public static CdpDriver connect(String webSocketUrl)
      Connect to an existing browser via WebSocket URL.

    • connect

      public static CdpDriver connect(String webSocketUrl, CdpDriverOptions options)
      Connect to an existing browser with options.

    • closeAll

      public static void closeAll()
      Close all active drivers.

    • setUrl

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

    • waitForPageLoad

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

    • waitForPageLoad

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

    • getUrl

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

    • getTitle

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

    • script

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

    • screenshot

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

    • screenshot

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

    • onDialog

      public void onDialog(DialogHandler handler)
      Register a handler for JavaScript dialogs (alert, confirm, prompt, beforeunload). When a dialog opens, the handler is called with a Dialog object. The handler should call dialog.accept() or dialog.dismiss() to resolve the dialog.
      Specified by:
      onDialog in interface Driver
      Parameters:
      handler - the dialog handler, or null to remove the handler

    • getDialogText

      public String getDialogText()
      Get the current dialog message.
      Specified by:
      getDialogText in interface Driver
      Returns:
      the dialog message, or null if no dialog is open

    • getDialog

      public Dialog getDialog()
      Get the current dialog if one is open. This is useful for detecting dialogs that appear after actions (e.g., click). The dialog remains available until handled via dialog() or the Dialog methods.
      Specified by:
      getDialog in interface Driver
      Returns:
      the current Dialog, or null if no dialog is open or already handled

    • dialog

      public void dialog(boolean accept)
      Accept or dismiss the current dialog. This is used when no DialogHandler is registered.
      Specified by:
      dialog in interface Driver
      Parameters:
      accept - true to accept (OK), false to dismiss (Cancel)

    • dialog

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

    • switchFrame

      public void switchFrame(int index)
      Switch to an iframe by index in the frame tree.
      Specified by:
      switchFrame in interface Driver
      Parameters:
      index - the zero-based index of the frame

    • switchFrame

      public void switchFrame(String locator)
      Switch to an iframe by locator (CSS, XPath, or wildcard). Pass null to switch back to the main frame.
      Specified by:
      switchFrame in interface Driver
      Parameters:
      locator - the locator for the iframe element, or null to return to main frame

    • getCurrentFrame

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

    • quit

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

    • close

      public void close()
      Close the current tab/page. After closing, automatically switches to another open tab if available. If this is the last tab, creates a blank page first to keep the browser alive. DESIGN NOTE: We must switch to another tab BEFORE closing the current one. When connected via page-specific WebSocket URL (e.g., /devtools/page/xxx), closing that page also closes the WebSocket connection. By switching first, we establish a new session on a different target, then safely close the old one.
      Specified by:
      close 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

    • isResponsive

      public boolean isResponsive()
      Bounded liveness probe for
      invalid reference 
      PooledDriverProvider
      reset.

      Sends a trivial Runtime.evaluate("1") with a 3-second CDP timeout (vs the default 30s). Returns false on any error, timeout, or closed socket — the caller treats false as "discard this driver, create a fresh one for the next scenario."

      Why this exists (context for future maintainers): observed in CI as deterministic "CDP timeout for: Page.navigate" failures in cookie.feature and keys.feature (same scenarios every run, alternating cookie pattern — classic "poisoned pool driver" signature). Every failing run was preceded by tab-switch.feature, which makes 5 activateTarget / Target.attachToTarget calls back-to-back. Each attach creates a new session on the driver's websocket and old sessions are never detached — the accumulated session state appears to leave Chrome unable to respond to Page.navigate on that specific driver, while the other pool driver stays healthy. Without this probe the broken driver kept getting handed back out and every other cookie scenario timed out at 30s.

      We probe Runtime.evaluate rather than Page.navigate because it's cheap and local (no network). If even that is stuck, the driver is definitively done.

      Specified by:
      isResponsive in interface Driver

    • getCdpClient

      public CdpClient getCdpClient()

    • getOptions

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

    • getCdpOptions

      public CdpDriverOptions getCdpOptions()
      Get the CDP-specific options.

    • click

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

    • focus

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

    • clear

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

    • input

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

    • value

      public Element value(String locator, String value)
      Set the value of an input element.
      Specified by:
      value in interface Driver

    • select

      public Element select(String locator, String text)
      Select an option from a dropdown by text or value.
      Specified by:
      select in interface Driver

    • select

      public Element select(String locator, int index)
      Select an option from a dropdown by index.
      Specified by:
      select in interface Driver

    • scroll

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

    • highlight

      public Element highlight(String locator)
      Highlight an element.
      Specified by:
      highlight in interface Driver

    • text

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

    • html

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

    • value

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

    • attribute

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

    • property

      public Object property(String locator, String name)
      Get a property of an element.
      Specified by:
      property in interface Driver

    • enabled

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

    • exists

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

    • position

      public Map<String,Object> position(String locator)
      Get the position of an element (absolute).
      Specified by:
      position in interface Driver

    • position

      public Map<String,Object> position(String locator, boolean relative)
      Get the position of an element.
      Specified by:
      position in interface Driver
      Parameters:
      relative - if true, returns viewport-relative position

    • locate

      public Element locate(String locator)
      Find an element by locator.
      Specified by:
      locate in interface Driver

    • locateAll

      public List<Element> locateAll(String locator)
      Find all elements matching a locator.
      Specified by:
      locateAll in interface Driver

    • optional

      public Element optional(String locator)
      Find an element that may not exist (optional).
      Specified by:
      optional in interface Driver

    • script

      public 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).
      Specified by:
      script in interface Driver

    • scriptAll

      public 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.
      Specified by:
      scriptAll in interface Driver

    • waitFor

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

    • waitFor

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

    • waitForAny

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

    • waitForAny

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

    • waitForAny

      public Element waitForAny(String[] locators, Duration timeout)
      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)
      Wait for an element to contain specific text.
      Specified by:
      waitForText in interface Driver

    • waitForText

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

    • waitForEnabled

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

    • waitForEnabled

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

    • waitForUrl

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

    • waitForUrl

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

    • waitUntil

      public Element waitUntil(String locator, String expression)
      Wait until a JavaScript expression on an element evaluates to truthy. The element is available as '_' in the expression.
      Specified by:
      waitUntil in interface Driver

    • waitUntil

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

    • waitUntil

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

    • waitUntil

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

    • waitUntil

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

    • waitUntil

      public Object waitUntil(Supplier<Object> condition, Duration timeout)
      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)
      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)
      Wait for a specific number of elements to match with custom timeout.
      Specified by:
      waitForResultCount in interface Driver

    • cookie

      public Map<String,Object> cookie(String name)
      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)
      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, secure, httpOnly, sameSite, expires

    • deleteCookie

      public void deleteCookie(String name)
      Delete a cookie by name.
      Specified by:
      deleteCookie in interface Driver
      Parameters:
      name - the cookie name

    • clearCookies

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

    • getCookies

      public List<Map<String,Object>> getCookies()
      Get all cookies.
      Specified by:
      getCookies in interface Driver
      Returns:
      list of cookies as Maps

    • maximize

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

    • minimize

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

    • fullscreen

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

    • getDimensions

      public Map<String,Object> getDimensions()
      Get window dimensions and position.
      Specified by:
      getDimensions in interface Driver
      Returns:
      Map with keys: x, y, width, height, windowState

    • setDimensions

      public void setDimensions(Map<String,Object> dimensions)
      Set window dimensions and/or position.
      Specified by:
      setDimensions in interface Driver
      Parameters:
      dimensions - Map with optional keys: x, y, width, height, windowState

    • pdf

      public byte[] pdf(Map<String,Object> options)
      Generate a PDF of the current page.
      Specified by:
      pdf in interface CoreDriver
      Specified by:
      pdf in interface Driver
      Parameters:
      options - Map with optional keys: scale, displayHeaderFooter, headerTemplate, footerTemplate, printBackground, landscape, pageRanges, paperWidth, paperHeight, marginTop, marginBottom, marginLeft, marginRight
      Returns:
      PDF bytes

    • pdf

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

    • refresh

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

    • reload

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

    • back

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

    • forward

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

    • activate

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

    • mouse

      public Mouse mouse()
      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

    • mouse

      public Mouse mouse(String locator)
      Get a Mouse object positioned at an element's center.
      Specified by:
      mouse in interface Driver
      Parameters:
      locator - the element locator
      Returns:
      a new Mouse object positioned at the element's center

    • mouse

      public Mouse mouse(Number x, Number y)
      Get a Mouse object at specified coordinates.
      Specified by:
      mouse in interface Driver
      Parameters:
      x - the x coordinate
      y - the y coordinate
      Returns:
      a new Mouse object at the specified position

    • keys

      public Keys keys()
      Get a Keys object for keyboard input. Returns the same instance to maintain modifier state (e.g., holding Shift across multiple calls).
      Specified by:
      keys in interface CoreDriver
      Specified by:
      keys in interface Driver
      Returns:
      the Keys object for this driver

    • getPages

      public List<String> getPages()
      Get list of all page targets (tabs). Uses browserMethod() because Target.getTargets is a browser-level command.
      Specified by:
      getPages in interface Driver
      Returns:
      list of target IDs

    • switchPage

      public void switchPage(String titleOrUrl)
      Switch to a page by title or URL substring. Includes verification that the switch was successful.
      Specified by:
      switchPage in interface Driver
      Parameters:
      titleOrUrl - the title or URL substring to match

    • switchPageById

      public void switchPageById(String targetId)
      Switch to a page by its backend target ID (unambiguous — avoids URL/title collisions that switchPage(String) is vulnerable to).
      Specified by:
      switchPageById in interface Driver

    • drainOpenedTargets

      public List<Map<String,Object>> drainOpenedTargets()
      Drain the queue of page targets (tabs) opened since the last call. Event-driven — no CDP round-trip. See Driver.drainOpenedTargets().
      Specified by:
      drainOpenedTargets in interface Driver

    • switchPage

      public void switchPage(int index)
      Switch to a page by index.
      Specified by:
      switchPage in interface Driver
      Parameters:
      index - the zero-based index

    • rightOf

      public Finder rightOf(String locator)
      Create a finder for elements to the right of the reference element.
      Specified by:
      rightOf in interface Driver
      Parameters:
      locator - the reference element locator
      Returns:
      a Finder for elements to the right

    • leftOf

      public Finder leftOf(String locator)
      Create a finder for elements to the left of the reference element.
      Specified by:
      leftOf in interface Driver
      Parameters:
      locator - the reference element locator
      Returns:
      a Finder for elements to the left

    • above

      public Finder above(String locator)
      Create a finder for elements above the reference element.
      Specified by:
      above in interface Driver
      Parameters:
      locator - the reference element locator
      Returns:
      a Finder for elements above

    • below

      public Finder below(String locator)
      Create a finder for elements below the reference element.
      Specified by:
      below in interface Driver
      Parameters:
      locator - the reference element locator
      Returns:
      a Finder for elements below

    • near

      public Finder near(String locator)
      Create a finder for elements near the reference element.
      Specified by:
      near in interface Driver
      Parameters:
      locator - the reference element locator
      Returns:
      a Finder for nearby elements

    • intercept

      public void intercept(List<String> patterns, InterceptHandler handler)
      Enable request interception with a handler. The handler is called for each matching request. Return an InterceptResponse to mock, or null to continue to the network.
      Specified by:
      intercept in interface CoreDriver
      Specified by:
      intercept in interface Driver
      Parameters:
      patterns - URL patterns to intercept (e.g., "*api/*", "https://example.com/*")
      handler - the intercept handler

    • intercept

      public void intercept(InterceptHandler handler)
      Enable request interception for all requests.
      Specified by:
      intercept in interface Driver
      Parameters:
      handler - the intercept handler

    • stopIntercept

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