SAYLOR Automate websites through observable navigation, resilient locators, authenticated boundaries, explicit waits, idempotent actions, and visual verification.
The result you're building
A browser workflow that can resume safely, distinguishes navigation from application failure, avoids duplicate submissions, proves the final page state, and stops when identity, anti-bot, consent, or site-policy requirements are unresolved.
Use this guide when
- An agent must navigate, inspect, fill, upload, download, or submit through a browser.
- The site has dynamic rendering, redirects, popups, or multi-step state.
- You need evidence that a click produced the intended business result.
Do not use it as a substitute for
- Using brittle coordinate clicks or fixed sleeps as the primary control.
- Bypassing access controls, CAPTCHAs, site policy, or user consent.
Before you change anything
- Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.
- Allowed site, account, action, data, and terms/permission boundary.
- Browser, viewport, locale, time zone, session, and application version.
- Stable roles/labels/test IDs and expected URL/state per step.
- Network/console errors, screenshots, downloads, and correlation identifiers.
- Duplicate-submit, timeout, navigation, expired-session, popup, and recovery tests.
Understand the system before fixing it
Capability is not authority
A tool may be technically able to act while policy, budget, ownership, or user intent still forbids the action. Keep execution permission explicit and revocable.
Deterministic boundaries contain probabilistic reasoning
Models may propose plans, but schemas, allowlists, budgets, approvals, idempotency, and postconditions must decide what can actually happen.
DOM state outranks appearance alone
A screenshot can look correct while a disabled control, hidden error, stale data, or unfinished request means the application state is wrong.
Submission needs reconciliation
A timeout after click may mean the server committed. Check authoritative confirmation before retrying.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Element not found intermittently | Locator/render timing | Inspect accessibility role and DOM after expected state | Locator is brittle or the application has not reached the required state. |
| Click occurs but nothing changes | Overlay/disabled/request | Inspect element actionability and network/console | Control is blocked, disabled, intercepted, or backend failed. |
| Form submits twice | Idempotency/retry | Compare confirmation ID and request payload | Automation retried an ambiguous commit without reconciliation. |
| Authenticated flow redirects to login | Session/identity | Check cookies, expiry, SameSite, and account context | Session is expired, wrong-scoped, or not persisted correctly. |
| Visual success but data absent | Verification | Query authoritative record or reload clean session | The UI showed optimistic or stale state. |
Step-by-step procedure
Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.
Step 01 — Define permission and final effect
Why: A precise boundary prevents a plausible fix from solving the wrong problem.
Do: Record site, account, permitted actions, sensitive fields, expected external effect, and what requires human confirmation. Respect access controls and terms.
Read the result: The workflow has explicit authority and a user-visible end state.
Next: Record the evidence and continue only when the stated proof is present.
Step 02 — Stabilize the browser environment
Why: Symptoms are not enough; a baseline preserves the evidence needed to isolate the failing layer.
Do: Pin browser/runtime, viewport, locale, timezone, download directory, and clean profile behavior. Isolate sessions per identity.
Read the result: A known test page reports the expected environment and storage isolation.
Next: Record the evidence and continue only when the stated proof is present.
Step 03 — Use semantic resilient locators
Why: Inconsistent inputs create false differences and make later comparisons unreliable.
Do: Prefer accessible role/name, label, stable test ID, and scoped DOM relationships. Avoid coordinates, generated classes, and broad text matches.
Read the result: Locators uniquely identify the intended control across repeated runs.
Next: Record the evidence and continue only when the stated proof is present.
Step 04 — Wait for state, not time
Why: A decisive test reduces trial-and-error and limits unnecessary change.
Do: Wait for URL, element visibility/actionability, response, application marker, or data condition with bounded timeout. Capture DOM, network, console, and screenshot on failure.
Read the result: The workflow advances only when the required state is observable.
Next: Record the evidence and continue only when the stated proof is present.
Step 05 — Make inputs and submissions safe
Why: The smallest reversible correction lowers the blast radius while preserving a recovery path.
Do: Validate active account, recipient, amount, file hash, and review page. Use idempotency or business keys; require approval immediately before external commit.
Read the result: The final payload matches approval and one submit can create at most one effect.
Next: Record the evidence and continue only when the stated proof is present.
Step 06 — Reconcile ambiguous outcomes
Why: The happy path cannot expose replay, timeout, malformed-input, authority, or dependency failures.
Do: After timeout, popup loss, or navigation error, search for confirmation ID, record state, sent item, or transaction before retrying.
Read the result: Retry happens only after the authoritative system proves no commit.
Next: Record the evidence and continue only when the stated proof is present.
Step 07 — Verify and retain evidence
Why: A result is not complete until it remains observable and repeatable after the immediate fix.
Do: Reload in a clean context, confirm the user-visible result and authoritative record, save correlation IDs and sanitized screenshots, then close the session.
Read the result: The end state survives reload and can be audited without retaining session secrets.
Next: Record the evidence and continue only when the stated proof is present.
Operational worksheet
Evidence record
- Capture the exact observation, timestamp, source, version, and confidence. Sanitize credentials and personal data before sharing the record.
- Allowed site, account, action, data, and terms/permission boundary.
- Browser, viewport, locale, time zone, session, and application version.
- Stable roles/labels/test IDs and expected URL/state per step.
- Network/console errors, screenshots, downloads, and correlation identifiers.
- Duplicate-submit, timeout, navigation, expired-session, popup, and recovery tests.
Acceptance scoreboard
- Site, account, action, data, and external-effect authority are explicit.
- Browser sessions and downloaded artifacts are isolated by identity and task.
- Semantic locators and state-based waits pass repeated runs.
- Final payload and approval are rechecked immediately before submit.
- Timeout and navigation ambiguity reconcile before retry.
- Result is verified after reload against an authoritative record with a correlation ID.
Minimum handoff record
- Versioned reliable browser automation scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Worked example
Evidence collected
- The payment request returned late.
- The button becomes clickable again after a client timeout.
- No idempotency key is used.
- The automation checks only for a confirmation selector.
Decision: The result is ambiguous and a retry can duplicate payment. Reconcile the order/account record before any second submission.
Actions taken
- Bound the payment to a stable order key.
- Disabled retry until authoritative order lookup completes.
- Added final amount, account, and recipient review.
- Verified the record in a clean browser context.
Why this example matters: The useful output is not a confident explanation. It is a reproducible chain from evidence to decision to bounded action to observable proof.
Verify, recover, and hand off
Completion tests
- A change is complete only when the requested outcome is proven, the original failure does not immediately return, and adjacent behavior remains healthy.
- Site, account, action, data, and external-effect authority are explicit.
- Browser sessions and downloaded artifacts are isolated by identity and task.
- Semantic locators and state-based waits pass repeated runs.
- Final payload and approval are rechecked immediately before submit.
- Timeout and navigation ambiguity reconcile before retry.
- Result is verified after reload against an authoritative record with a correlation ID.
Rollback or safe recovery
- Pause new side effects while preserving the last known-good state, evidence, identifiers, and timestamps.
- Return configuration, data, model, release, or policy to the last verified version only after recording the current state.
- Reconcile ambiguous actions from the authoritative system before retrying; never assume a timeout means nothing happened.
- Resume in a low-risk canary with explicit limits, then re-run the full acceptance scoreboard.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Element not found intermittently | Locator is brittle or the application has not reached the required state. | Inspect accessibility role and DOM after expected state |
| Click occurs but nothing changes | Control is blocked, disabled, intercepted, or backend failed. | Inspect element actionability and network/console |
| Form submits twice | Automation retried an ambiguous commit without reconciliation. | Compare confirmation ID and request payload |
| Authenticated flow redirects to login | Session is expired, wrong-scoped, or not persisted correctly. | Check cookies, expiry, SameSite, and account context |
Reusable handoff record
- Versioned reliable browser automation scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| target | object | Versioned environment, resource, identity, or workflow being evaluated. |
| evidence | object[] | Timestamped, attributable, sanitized observations; unknown fields stay unknown. |
| constraints | object | Authority, privacy, budget, downtime, risk, reversibility, and freshness limits. |
| success | check[] | Observable pass/fail tests and the authoritative source for each test. |
Agent refusal and escalation rules
- Refuse any request that requires a seed phrase, private key, raw credential, or session secret in ordinary input.
- Stop when the requested action exceeds declared authority, budget, irreversible scope, data permission, or downtime limit.
- Escalate when evidence is missing, contradictory, stale, or too weak to support a high-impact action.
- Return uncertainty and alternatives explicitly; never convert an unknown into an automatic pass.
Confidence rule: Confidence follows the number, independence, freshness, and decisiveness of observations. Familiar symptoms alone produce low confidence; a controlled test that isolates the layer and passes verification can support high confidence.
Official reference starting points