Class LocatorPolicy

java.lang.Object

com.shaft.capture.generate.LocatorPolicy

public final class LocatorPolicy
extends Object

Issue #4271: the single deterministic locator-selection policy for every SHAFT surface that identifies an element from captured evidence.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	LocatorPolicy.LocatorPlan	How one candidate is emitted.
static enum	LocatorPolicy.Tier	Emission tiers, most preferred first.

Method Summary

Modifier and Type	Method	Description
static boolean	looksAutoGenerated(String id)	Tier 1 promotes an id above a live-verified ARIA role, so its premise -- that the id was written by a human and will survive a redeploy -- has to be enforced here rather than assumed.
static Optional<LocatorPolicy.LocatorPlan>	plan(ElementSnapshot target, LocatorCandidate candidate)	Plans how candidate would be emitted for target.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

plan

public static Optional<LocatorPolicy.LocatorPlan> plan(ElementSnapshot target,
 LocatorCandidate candidate)

Plans how candidate would be emitted for target.

Parameters:

target - the captured element

candidate - one piece of captured locator evidence

Returns:

the plan, or empty when the evidence is not trustworthy enough to emit

looksAutoGenerated

public static boolean looksAutoGenerated(String id)

Tier 1 promotes an id above a live-verified ARIA role, so its premise -- that the id was written by a human and will survive a redeploy -- has to be enforced here rather than assumed. The recorder's own stable flag is not sufficient evidence: dynamic() (shaft-capture-recorder.js:17-19) tests only for an 8+ digit run or a UUID, so every shape below is reported stable, and candidates built directly in Java (the shaft-mcp adapters) never run that check at all.

This is unavoidably a heuristic over an open set of frameworks and it will never be complete. It is deliberately biased toward refusing: a false positive costs one tier (the element still generates from its verified role or XPath), while a false negative ships a locator that silently breaks on the next deploy. An ordinary authored id that happens to end in -<number> is the known, accepted false positive.

Public so every producer of id-strategy locator evidence can share this one heuristic instead of maintaining a second copy -- e.g. shaft-mcp's PlaywrightService calls this directly to compute a real stable signal from the live Playwright driver, at the one point a live page is actually available (issue #4273).

Parameters:

id - the candidate id

Returns:

whether the id looks framework-generated rather than authored