Natural Language Actions

Natural-language actions let a test express a browser, element, or touch intent through SHAFT.GUI.WebDriver.act(...). The engine plans the request, validates the plan against the configured trust threshold, and executes it only when the plan is trusted enough.

The feature is disabled by default. Enable it only in tests where readable workflow intent is more valuable than direct locator calls:

EnableNaturalActions.java

SHAFT.Properties.naturalActions.set()
    .enabled(true)
    .minimumTrustPercentage(85)
    .planner("deterministic")
    .aiFallbackEnabled(false)
    .allowedActions("browser,element,touch");

Basic usage

NaturalLogin.java

String username = "standard_user";
String password = System.getenv("APP_PASSWORD");

driver.act("Login with valid credentials", username, password);

act(...) returns the same SHAFT.GUI.WebDriver instance so it can be used in fluent flows. Arguments are passed separately from the natural-language intent. SHAFT logs argument counts and intent metadata, not raw argument values.

Deterministic planner

The default planner is local and deterministic. It recognizes a small set of high-signal patterns and maps them to existing SHAFT actions:

Intent pattern	Action
refresh, refresh page, reload page	driver.browser().refreshCurrentPage()
go back, navigate back	driver.browser().navigateBack()
go forward, navigate forward	driver.browser().navigateForward()
open ... or navigate to ... with a URL argument	driver.browser().navigateToURL(url)
Login with valid credentials with username and password arguments	types username, types password securely, then clicks login/sign in/submit
click Save	clicks a semantic clickable element
type into Email with one argument	types into a semantic input field
clear Search	clears a semantic input field
tap Continue	taps a semantic clickable element

Element and touch plans use SHAFT smart locators under the hood. If no deterministic pattern matches, the action fails without changing the page.

Trust gate

Every plan has a trust score. SHAFT executes the action only when the score is greater than or equal to naturalActions.minimumTrustPercentage.

src/main/resources/properties/custom.properties

naturalActions.enabled=true
naturalActions.minimumTrustPercentage=90
naturalActions.planner=deterministic
naturalActions.aiFallback.enabled=false
naturalActions.allowedActions=browser,element,touch

Use allowedActions to narrow what natural actions may do in a test class. For example, allowedActions=browser allows navigation-style actions but rejects element and touch actions before execution.

Optional planner fallback

Set naturalActions.planner=auto and naturalActions.aiFallback.enabled=true only when an optional planner should be allowed after the deterministic planner cannot produce a plan. SHAFT discovers additional planners through Java ServiceLoader; shaft-pilot-core provides a Pilot-backed natural-action planner that is also disabled unless pilot.enabled=true.

Provider-assisted planning is still plan-only. The returned steps must pass the same local validation, allowed-action filter, and trust threshold before SHAFT touches the browser.

MCP usage

shaft-mcp exposes the same behavior through the natural_act tool. The tool uses the active SHAFT driver, temporarily enables natural actions for the call, and restores the previous natural-action settings afterward. MCP clients can also pass per-call trust threshold, planner, AI fallback, and allowed-action overrides.

See Connect shaft-mcp for transport setup and MCP client approval guidance.