scout_attach
Attach a browser to a running web app for exploratory UI testing. Controlled by write policies: observe, read-only, safe-write, or destructive.
Instructions
Launch a browser and attach to a running web app. First attach in this conversation and you have read neither the SceneScout skill nor scout_playbook? Call scout_playbook before this. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted, and POSTs the user named in readPosts) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass role to sign in with a login the user saved by scenescout login <url> --role <name>, or a Playwright storage-state JSON as storageStatePath. Pass session to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's session param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Base URL of the running app, e.g. http://localhost:3000 | |
| mode | No | Write policy (see tool description). Never choose 'destructive' yourself — user opt-in only. | read-only |
| open | No | Open the live view (on this attach) and/or report.html (when scout_report writes it) in the user's default browser: 'live', 'report', 'both' or 'none'. Default: the SCENESCOUT_OPEN environment variable, else 'both' on a local desktop session (headed or headless) and 'none' in CI, over SSH, or with no display. Pass it only when the user asked for something other than the default. | |
| role | No | Sign in as a role whose login was saved with `scenescout login <url> --role <name>` (kept in the project's .scenescout/auth/). Every session given the same role gets its own browser built from that one login. Not with storageStatePath. No saved login for the role: the attach is refused and names the command to run — ask the user to run it, since it opens a window for them to sign in. | |
| task | No | What this session is doing right now, shown under its objective from the moment it appears, e.g. Signing in and taking stock. Passed alone it is read as the 2.0 spelling of `objective`. Defaults to a placeholder so a fresh card never reads as idle. | |
| dedup | No | How this run tells a filed finding from one already recorded. Default: the SCENESCOUT_DEDUP environment variable, else 'rule', the store's rule alone. 'judge': the rule first, then, for a filing the rule keeps apart from everything recorded, a model is asked whether it is one of the open findings on its page, and merges it when it says so. It needs ANTHROPIC_API_KEY or OPENAI_API_KEY in the server's environment, and sends each pair's titles, categories and evidence, and the page's path, to that provider — ONLY when the user asked for it. Applies to every session of the project until the run ends. | |
| headed | No | Show the browser window | |
| paceMs | No | A floor between actions, in milliseconds, for when a person is watching and needs to keep up — following a flow, taking notes, demonstrating. Default 0: as fast as the page allows, which is what a run wants otherwise. Changeable mid-run with scout_session {paceMs}. | |
| record | No | Keep a frame of the page after every action, under .scenescout/recordings/, and show it beside that step in report.html. Default: the SCENESCOUT_RECORD environment variable (on or off), else off: a recording is pictures of the app under test sitting in the project folder. Turn it on for QA work, where the run is evidence and not only a report. | |
| browser | No | Browser to drive. Default: the SCENESCOUT_BROWSER environment variable, else chromium. A build that is not on disk is downloaded on this attach, once, except in CI or with SCENESCOUT_BROWSER_DOWNLOAD=off, where the attach names the command to run. Use firefox or webkit for a cross-browser pass; stay on chromium otherwise. | |
| session | No | Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'. | |
| evidence | No | What happens to the picture each scout_finding takes of what it is about. 'inline': kept under .scenescout/recordings/, shown in report.html, and returned in the scout_finding result so the conversation shows it. 'file': kept and shown in the report only. 'off': none taken. Default: the SCENESCOUT_EVIDENCE environment variable, else 'inline', or 'file' in a CI job. Pictures are bounded in size and in how many one session returns (see the configuration reference). | |
| objective | No | This session's objective: the whole remit you were given, in one sentence ("Admin lane: §2 registers, §7 plan gating", "Approve and reject orders as a manager"). It sits above the task, which is what the session is doing at any moment. Shown to whoever is watching the run; worth setting whenever more than one session is live. | |
| readPosts | No | POST endpoints that only read, e.g. ["POST /api/search", "POST https://api.example.com/reports/query"], which observe mode then lets out — ONLY when the user named them. Never add one yourself, even when the gap ledger lists a refused POST: ask the user. Exact paths; * stands for one path segment. Still refused when the path or body looks destructive or the body is a GraphQL mutation. Observe mode only. Default: the SCENESCOUT_READ_POSTS environment variable, else none. | |
| projectPath | No | Absolute path to the project (memory + report live in .scenescout/ here). Pass it whenever you have a project or working folder. Omitted: the client's workspace folder, else a folder per tested site under the user's documents folder (Documents/SceneScout/<host>/, or SCENESCOUT_PROJECTS_DIR), which the result names — tell the user where it is. | |
| navTimeoutMs | No | How long a page may take to load, in ms. Default: the SCENESCOUT_NAV_TIMEOUT_MS environment variable, else 20000 (crawled pages 15000; a value set here applies to them too). Raise it only when timeouts come from a loaded machine rather than the app. | |
| trustedEmbeds | No | Origins of embedded frames (e.g. "https://pay.example.com") whose writes out of the app may go out — ONLY when the user named them, typically a provider in test mode, and only in safe-write mode. Never add one yourself. Hostile input, repeated-click probes and uploads stay refused in them. | |
| viewportWidth | No | Viewport width (default 1280); use e.g. 390 for a mobile pass | |
| viewportHeight | No | Viewport height (default 900) | |
| actionTimeoutMs | No | How long one click, keystroke, hover or pick may take, in ms. Default: the SCENESCOUT_ACTION_TIMEOUT_MS environment variable, else 5000. Raise it only when timeouts come from a loaded machine rather than the app. | |
| storageStatePath | No | Optional Playwright storage-state JSON path for authenticated exploration. Not with `role`. |