Class ElementService

java.lang.Object
com.shaft.mcp.ElementService
@Service public class ElementService extends Object
MCP-safe element actions. Sensitive values are returned only to direct callers and are never logged.

  • Constructor Details

    • ElementService

      public ElementService()
      Creates the default element service, wiring default Playwright/mobile services for direct Java callers and tests that construct this class without Spring.

  • Method Details

    • hover

      @Tool(name="element_hover", description="hovers over an element; dispatches to the active engine and records the step when a Playwright recording is active") public ElementActionResult hover(locatorStrategy locatorStrategy, String locatorValue)
      Hovers over an element, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; only Playwright uses a distinct driver instance.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and, when a Playwright recording is active, the recorded step's code block

    • click

      @Tool(name="element_click", description="clicks an element; optional mode selects single (default) | double | long; dispatches to the active engine and records the step when a mobile or Playwright recording is active") public ElementActionResult click(locatorStrategy locatorStrategy, String locatorValue, @ToolParam(required=false) ClickMode mode)
      Clicks an element, dispatching to whichever engine is currently active (web/mobile WebDriver or Playwright) and routing through that engine's recording wrapper when a mobile or Playwright recording is active.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      mode - click gesture; blank/omitted defaults to ClickMode.SINGLE. ClickMode.DOUBLE and ClickMode.LONG absorb the former element_double_click/element_click_and_hold/ mobile_double_tap/mobile_long_tap tools; ClickMode.LONG is not supported on the Playwright engine.
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • click

      public ElementActionResult click(locatorStrategy locatorStrategy, String locatorValue)
      Java-caller convenience overload defaulting mode to ClickMode.SINGLE; not an MCP tool.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • clickSemantic

      public void clickSemantic(String elementName)
      Clicks an element using SHAFT semantic locator behavior for direct Java callers. Not exposed as an MCP tool because semantic names may contain sensitive application text.
      Parameters:
      elementName - semantic element name

    • clickUsingAI

      @Deprecated(forRemoval=false) public void clickUsingAI(String elementName)
      Deprecated.
      Compatibility alias for older clients; not exposed as an MCP tool.
      Parameters:
      elementName - semantic element name

    • type

      @Tool(name="element_type", description="types text into an element; optional append (default false) appends instead of clearing first, optional clear (default true; false behaves like append=true) controls whether the field is cleared before typing; dispatches to the active engine and records the step when a mobile or Playwright recording is active") public ElementActionResult type(locatorStrategy locatorStrategy, String locatorValue, String text, @ToolParam(required=false) Boolean append, @ToolParam(required=false) Boolean clear)
      Types text into an element, dispatching to whichever engine is currently active and routing through that engine's recording wrapper when a mobile or Playwright recording is active.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      text - text to type
      append - when true, appends instead of clearing first; blank/omitted defaults to false
      clear - when false, types without clearing first (equivalent to append=true); blank/omitted defaults to true
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • type

      public ElementActionResult type(locatorStrategy locatorStrategy, String locatorValue, String text)
      Java-caller convenience overload defaulting append/clear; not an MCP tool.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      text - text to type
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • typeSemantic

      public void typeSemantic(String elementName, CharSequence... textValue)
      Types text using SHAFT semantic locator behavior for direct Java callers. Not exposed as an MCP tool because semantic names and typed values may contain sensitive application text.
      Parameters:
      elementName - semantic element name
      textValue - text values

    • typeUsingAI

      @Deprecated(forRemoval=false) public void typeUsingAI(String elementName, CharSequence... textValue)
      Deprecated.
      Compatibility alias for older clients; not exposed as an MCP tool.
      Parameters:
      elementName - semantic element name
      textValue - text values

    • clear

      @Tool(name="element_clear", description="clears text from an element; dispatches to the active engine and records the step when a mobile or Playwright recording is active") public ElementActionResult clear(locatorStrategy locatorStrategy, String locatorValue)
      Clears an element, dispatching to whichever engine is currently active and routing through that engine's recording wrapper when a mobile or Playwright recording is active.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • dropFileToUpload

      @Tool(name="element_upload_file", description="drops file to an element to upload; dispatches to the active engine and records the step when a Playwright recording is active") public ElementActionResult dropFileToUpload(locatorStrategy locatorStrategy, String locatorValue, String filePath)
      Drops a file onto an upload element, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; only Playwright uses a distinct driver instance.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      filePath - local file path
      Returns:
      the active engine and, when a Playwright recording is active, the recorded step's code block

    • dragAndDrop

      @Tool(name="element_drag_and_drop", description="drags and drops an element from source to a target locator, or by offsetX/offsetY when no target locator is given; dispatches to the active engine and records the step when a Playwright recording is active") public ElementActionResult dragAndDrop(locatorStrategy sourceLocatorStrategy, String sourceLocatorValue, @ToolParam(required=false) locatorStrategy targetLocatorStrategy, @ToolParam(required=false) String targetLocatorValue, @ToolParam(required=false) Integer offsetX, @ToolParam(required=false) Integer offsetY)
      Drags one element to another, or drags a source element by an offset when no target locator is given, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/ MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; only Playwright uses a distinct driver instance.
      Parameters:
      sourceLocatorStrategy - source locator strategy
      sourceLocatorValue - source locator value
      targetLocatorStrategy - target locator strategy; omit together with targetLocatorValue to use offsetX/offsetY instead
      targetLocatorValue - target locator value; omit to use offsetX/offsetY instead
      offsetX - horizontal offset from the source element; used only when no target locator is given
      offsetY - vertical offset from the source element; used only when no target locator is given
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • dragAndDrop

      public ElementActionResult dragAndDrop(locatorStrategy sourceLocatorStrategy, String sourceLocatorValue, locatorStrategy targetLocatorStrategy, String targetLocatorValue)
      Java-caller convenience overload for the element-to-element drag shape; not an MCP tool.
      Parameters:
      sourceLocatorStrategy - source locator strategy
      sourceLocatorValue - source locator value
      targetLocatorStrategy - target locator strategy
      targetLocatorValue - target locator value
      Returns:
      the active engine and, when a recording is active, the recorded step's code block

    • getText

      public String getText(locatorStrategy locatorStrategy, String locatorValue)
      Gets text for direct Java callers. Not exposed as an MCP tool because text may be sensitive.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      element text

    • getDomAttribute

      public String getDomAttribute(locatorStrategy locatorStrategy, String locatorValue, String domAttributeName)
      Gets a DOM attribute for direct Java callers. Not exposed as an MCP tool.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      domAttributeName - attribute name
      Returns:
      attribute value

    • getDomProperty

      public String getDomProperty(locatorStrategy locatorStrategy, String locatorValue, String domPropertyName)
      Gets a DOM property for direct Java callers. Not exposed as an MCP tool.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      domPropertyName - property name
      Returns:
      property value

    • getCssValue

      public String getCssValue(locatorStrategy locatorStrategy, String locatorValue, String cssPropertyName)
      Gets a CSS value for direct Java callers. Not exposed as an MCP tool.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      cssPropertyName - CSS property name
      Returns:
      CSS value

    • isDisplayed

      @Tool(name="element_is_displayed", description="checks if an element is displayed; dispatches to the active engine") public ElementQueryResult isDisplayed(locatorStrategy locatorStrategy, String locatorValue)
      Checks whether an element is displayed, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; only Playwright uses a distinct driver instance.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and true when displayed

    • isEnabled

      @Tool(name="element_is_enabled", description="checks if an element is enabled; dispatches to the active engine") public ElementQueryResult isEnabled(locatorStrategy locatorStrategy, String locatorValue)
      Checks whether an element is enabled, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; only Playwright uses a distinct driver instance.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and true when enabled

    • isSelected

      @Tool(name="element_is_selected", description="checks if an element is selected; dispatches to the active engine") public ElementQueryResult isSelected(locatorStrategy locatorStrategy, String locatorValue)
      Checks whether an element (for example a checkbox or radio button) is selected, dispatching to whichever engine is currently active. Mobile engines (MOBILE_NATIVE/MOBILE_WEB) share the same WebDriver-backed session as WEB and use the same code path; Playwright uses a small dedicated implementation via the raw Locator.isChecked() (design doc amendment A8), since no SHAFT Playwright ElementActions equivalent existed before this commit.
      Parameters:
      locatorStrategy - locator strategy
      locatorValue - locator value
      Returns:
      the active engine and true when selected