lupin.Open console
Browsers

Choose browser selectors that fail safely

Use unique visible controls, inspect fresh page state and avoid turning selector recovery into repeated form submissions.

Lupin editorialAI-assisted3 min read

A selector is a hypothesis about one control

For click, fill and select, Lupin accepts a CSS selector and checks that it matches exactly one available element. That contract is helpful: the system refuses an ambiguous selector instead of silently choosing the first matching button. Begin with a fresh page read and identify the control's purpose from its surrounding content. Prefer a stable identifier or a meaningful name that selects the intended element uniquely. A generated selector is an interaction hint, not proof of the control's business role. The user instruction must still authorize the effect of using it.

Know the fixed action requirements

The selector input is bounded to 500 characters. Fill accepts text for an input or textarea and excludes file inputs; select expects an actual select element and an option value. The chosen element must be visible and enabled. A label that looks like a dropdown may be a custom component rather than an HTML select, and a decorative button may not be the active control. Use the observed DOM-facing metadata and screenshots to distinguish these cases. Do not assume arbitrary automation code is available as a fallback through the fixed page-action endpoint.

Refresh after structural changes

Navigation, responsive layout, an opened modal and a human handoff can all invalidate an earlier selector. Read the page again after those transitions. If the element list is truncated or a selector is absent, acknowledge the limited observation rather than guessing a long nth-child chain. A screenshot can reveal that an overlay obscures the intended field, while a tab inventory can reveal that the form opened in another page. Repair the reason the selector no longer identifies the intended control before issuing another mutation. Merely making the string more complicated rarely resolves an account or page mismatch.

Illustrative request; source reviewed, not executed against a live provider.
{"action":"fill","tab_id":"TARGET_ID_FROM_TABS","selector":"input[name=search]","text":"documentation"}

Separate selector failure from uncertain execution

A page_action_failed response indicates that the selected action could not be completed as requested, while a lost response or browser_action_uncertain may leave the effect unknown. Read the current form and any confirmation state before repeating a click. A selector problem on a harmless field focus is different from uncertainty after pressing a purchase or send button. Preserve the original idempotency key for transport retries and give a genuinely new action its own identity. Never create new keys in a loop merely to force the same consequential click through an uncertainty guard.

Design for controlled failure

If you own the target application, use stable control identifiers, clear labels and disabled states that reflect readiness. For third-party pages, keep recovery bounded: refresh once, inspect the new evidence, then request an authorized human handoff when the control remains ambiguous. Record the observed URL, tab and sanitized selector failure without storing field secrets. After a successful action, verify its outcome from the returned page or application state. A selector matching one element only proves that the target was unambiguous at execution time; it does not prove the server accepted the intended change.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore browsers