Find hints

Force a single resolve strategy with by aria-label, by attribute, by role, and related hints

Optional find hints force one resolve strategy for the preceding target label. Place them immediately after the primary target (before with / in / in row / value / state tasks).

Without a find hint, StrikeTest auto-finds the element.

Available hints

Hint	Meaning	Example
`by aria-label`	Match `aria-label` only	`When I click on "Security" by aria-label`
`by data-testid`	Match `data-testid` only	`When I click on "save-account" by data-testid`
`by id`	Match element id only	`When I hover on "Profile" by id`
`by name`	Match `name` attribute only	`When I fill "email" by name with "a@b.com"`
`by text`	Match visible text only	`When I click on "Login" by text`
`by role "…"`	Role plus accessible name / text (role is quoted)	`When I click on "Security" by role "tab"`
`by attribute`	Unique visible element that has the attribute named by the label (presence only; any valid attr-name token; no value match)	`When I fill "data-submit-order" by attribute with "Ada"`

Requirements (resolve contracts)

Find hints replace the command’s auto-find chain for the primary target only. Container / row keys in one-shot in / in row always stay auto-find.

Hint	Element contract
`by id`	Unique visible `#id`
`by data-testid`	Unique visible `[data-testid='…']` (any tag)
`by aria-label`	Unique visible `[aria-label='…']` (any tag)
`by name`	Unique visible `[name='…']` (any tag)
`by text`	Only clickables: `button`, `a`, `input[type=button]`, `[role=button]`, `[role=link]`, `[role=tab]` — wider than default page `click` visible text, which omits `[role=button]`
`by role "R"`	Unique visible `[role='R']`; accessible name = `aria-label`, else direct text nodes (not full subtree InnerText)
`by attribute`	Label is the attribute name (presence only, no value match); unique visible; `*` in the name is rejected; Appium unsupported

When it fails

Wrong hint for the control — e.g. by text on a non-clickable div without role=button.
Ambiguous — two or more visible matches.
by role without a quoted role value → parse / resolve error.

Auto `data-*` presence fallback (web only)

When there is no by … and existing auto-find strategies miss, a label that is a valid data-* attribute name may still resolve if exactly one visible element has that attribute:

When I click on "data-submit-order"
When I fill "data-employee-name" with "Ada"

Non-data-* labels do not use this auto path (use forced by attribute instead).
Forced by attribute skips the auto chain and accepts any valid attribute name token (for example my-custom-hook).
Ambiguous (two or more visible matches) → fail. Do not write CSS or XPath in .stk.
Appium: by attribute and the auto data-* fallback are unsupported.

Rules

One find strategy per step.
Find by … is not the same as assert attribute "…" value "…" (which reads an HTML attribute after resolve).
For should have "…" values "…" sum equal "…", the find hint applies to the container only; the total label uses auto-find.
Prefer placing find hints on steps where the hint is parsed before the element action (for example fill "…" by attribute with "…"). See fill.

Examples

When I fill "Email" by aria-label with "a@b.com"
When I click on "Security" by role "tab"
When I fill "data-employee-name" by attribute with "Ada"
When I fill "my-custom-hook" by attribute with "Zoe"
Then I should have "username" by id value "chamodh" be enabled
And I wait for "dashboard" by data-testid