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

  • 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.

    • optionSelector

      public static String optionSelector(String locator, String text)
      Generate JS to select a dropdown option. Dispatches both 'input' and 'change' events with bubbles:true for framework compatibility.
      • "{}" 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.

    • 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.