Package io.karatelabs.driver

Class Locators

java.lang.Object
io.karatelabs.driver.Locators
public class Locators extends Object
Utility class for transforming locators into JavaScript expressions. Supports CSS selectors, XPath, and wildcard locators.

Locator types:

  • CSS selector: "#id", ".class", "tag", "tag.class"
  • XPath: "//div", "./span", "../parent", "(//div)[2]"
  • Wildcard: "{div}text", "{^div}partial", "{tag:2}text", "{:2}text"
  • Pure JS: "(expression)" - passed through unchanged

  • Field Details

    • SCROLL_JS_FUNCTION

      public static final String SCROLL_JS_FUNCTION
      See Also:

    • ELEMENT_NOT_FOUND

      public static final String ELEMENT_NOT_FOUND
      Marker in the page-side Error thrown by an action whose locator resolved to null. CdpDriver matches on this to tell a transient re-resolve miss (the document swapped under us — retryable) apart from a genuine JS error in the page under test.
      See Also:

  • Constructor Details

    • Locators

      public Locators()

  • Method Details

    • selector

      public static String selector(String locator)
      Transform a locator into a JavaScript expression that returns a single element.
      Parameters:
      locator - CSS selector, XPath, wildcard, or JS expression
      Returns:
      JavaScript expression

    • selector

      public static String selector(String locator, String contextNode)
      Transform a locator into a JavaScript expression with a context node.
      Parameters:
      locator - CSS selector, XPath, wildcard, or JS expression
      contextNode - JavaScript expression for the context node
      Returns:
      JavaScript expression

    • isXpath

      public static boolean isXpath(String locator)
      Check if a locator is an XPath expression.

    • expandWildcard

      public static String expandWildcard(String locator)
      Expand wildcard locator to JavaScript resolver call. Uses browser-side JS that matches the same logic as locator generation.
      • {tag}text → window.__kjs.resolve('tag', 'text', 1, false)
      • {^tag}text → window.__kjs.resolve('tag', 'text', 1, true)
      • {tag:2}text → window.__kjs.resolve('tag', 'text', 2, false)
      • {:2}text → window.__kjs.resolve('*', 'text', 2, false)

    • selectorAll

      public static String selectorAll(String locator)
      Transform a locator into a JavaScript expression that returns all matching elements.

    • selectorAll

      public static String selectorAll(String locator, String contextNode)
      Transform a locator into a JavaScript expression that returns all matching elements.

    • wrapInFunctionInvoke

      public static String wrapInFunctionInvoke(String js)
      Wrap JavaScript in an IIFE (Immediately Invoked Function Expression).

    • toFunction

      public static String toFunction(Object expression)
      Convert shorthand expression to a function.
      • JsFunction: arrow functions like _ => _.value are serialized to source
      • "_" expressions: "_.value" → _ => _.value
      • "!" expressions: "!_.disabled" → _ => !_.disabled

    • scriptSelector

      public static String scriptSelector(String locator, Object expression)
      Execute a function on a single element found by locator. Expression can be a String or JsFunction (arrow function).

    • scriptSelector

      public static String scriptSelector(String locator, Object expression, String contextNode)
      Execute a function on a single element found by locator with context. Expression can be a String or JsFunction (arrow function).

    • scriptAllSelector

      public static String scriptAllSelector(String locator, Object expression)
      Execute a function on all elements matching locator. Expression can be a String or JsFunction (arrow function).

    • scriptAllSelector

      public static String scriptAllSelector(String locator, Object expression, String contextNode)
      Execute a function on all elements matching locator with context. Expression can be a String or JsFunction (arrow function).

    • highlight

      public static String highlight(String locator, int millis)
      Generate JS to highlight an element.

    • highlightAll

      public static String highlightAll(String locator, int millis)
      Generate JS to highlight all elements matching a locator.

    • commitFieldEventsJs

      public static String commitFieldEventsJs(String e)
      The full event sequence a real <select> change produces, fired on the element expression e. input+change update the value; blur+focusout trigger a framework's field-level commit/validation — so a form that only commits (or clears a "required" error) on blur (Guidewire, SAP and many enterprise UIs) commits at select time, instead of lazily on the next interaction. Without the blur pair, a programmatic select sets the value but leaves the framework's field state stale, which reads as "the select didn't stick". (Native semantics: blur does not bubble; focusout does — fire both so direct and delegated listeners run.)

    • optionSelector

      public static String optionSelector(String locator, String text)
      Generate JS to select a dropdown option. Dispatches the full real-selection event sequence (input, change, blur, focusout) so a framework that commits or validates a field on blur commits at select time (see commitFieldEventsJs(java.lang.String)).
      • "{}" prefix: select by exact text only
      • "{^}" prefix: select by text contains
      • otherwise: try value first, then fall back to text match

    • getPositionJs

      public static String getPositionJs(String locator)
      Generate JS to get element position.

    • focusJs

      public static String focusJs(String locator)
      Generate JS to focus an element with cursor at end.

    • clickJs

      public static String clickJs(String locator)
      Generate JS to click an element.

    • scrollJs

      public static String scrollJs(String locator)
      Generate JS to scroll an element into view.

    • inputJs

      public static String inputJs(String locator, String value)
      Generate JS to set the value of an input element with events.

    • clearJs

      public static String clearJs(String locator)
      Generate JS to clear an input element.

    • textJs

      public static String textJs(String locator)
      Generate JS to get text content of an element.

    • valueJs

      public static String valueJs(String locator)
      Generate JS to get the value of an input element.

    • attributeJs

      public static String attributeJs(String locator, String name)
      Generate JS to get an attribute of an element.

    • propertyJs

      public static String propertyJs(String locator, String name)
      Generate JS to get a property of an element.

    • closestJs

      public static String closestJs(String locator, String cssSelector)
      Generate a pure-JS locator that resolves to the closest ancestor (or self) matching the given CSS selector, or null if no ancestor matches.

      Mirrors the native Element.closest() DOM API. Result starts with ( so it passes through selector(String) unchanged and can be used anywhere a locator string is accepted (element ops, waits, script).

    • matchesJs

      public static String matchesJs(String locator, String cssSelector)
      Generate a JS expression that evaluates to true when the element resolved by the given locator matches the CSS selector, or false otherwise (including when the element does not exist).

      Mirrors the native Element.matches() DOM API. Unlike closestJs(java.lang.String, java.lang.String), this returns a boolean, so it is a full JS expression meant for driver.script() rather than a locator string.

    • scopedSelectorJs

      public static String scopedSelectorJs(String baseJsLocator, String cssChildSelector)
      Generate a pure-JS locator that evaluates to the first descendant of the given pure-JS base locator matching the child CSS selector, or null if no match.

      Used by BaseElement.locate(String) when the base element's locator is itself a JS expression (e.g. produced by closestJs(java.lang.String, java.lang.String)) — naive string-concat would produce invalid JS.

    • scopedCountJs

      public static String scopedCountJs(String baseJsLocator, String cssChildSelector)
      Generate a JS expression that counts descendants of the given pure-JS base locator matching the child CSS selector. Returns 0 when the base is missing.

    • scopedIndexedSelectorJs

      public static String scopedIndexedSelectorJs(String baseJsLocator, String cssChildSelector, int index)
      Generate a pure-JS locator that evaluates to the nth descendant of the given pure-JS base locator matching the child CSS selector. Index is zero-based.

      Re-resolves the base on every access, so the resulting locator tolerates DOM mutations between the count and later element ops — matching how CDP driver createIndexedLocator behaves for CSS/XPath locators.

    • enabledJs

      public static String enabledJs(String locator)
      Generate JS to check if element is enabled.

    • existsJs

      public static String existsJs(String locator)
      Generate JS to check if element exists.

    • outerHtmlJs

      public static String outerHtmlJs(String locator)
      Generate JS to get outer HTML of an element.

    • innerHtmlJs

      public static String innerHtmlJs(String locator)
      Generate JS to get inner HTML of an element.

    • findAllJs

      public static String findAllJs(String locator)
      Generate JS to find all matching elements and return their unique selectors. Returns an array of CSS selectors that can be used to re-locate each element.

    • countJs

      public static String countJs(String locator)
      Generate JS to count matching elements.

    • escapeForJs

      public static String escapeForJs(String text)
      Escape a string for embedding in a JavaScript double-quoted string.

    • escapeXpathString

      public static String escapeXpathString(String text)
      Escape a string for use in XPath. Handles strings containing single quotes, double quotes, or both.