rename skill to browser
This commit is contained in:
@@ -0,0 +1,397 @@
|
||||
---
|
||||
name: browser
|
||||
description: Use cmux browser automation for browser access. Validate real user-facing behavior in browser surfaces, including navigation, DOM interaction, inspection, storage, tabs, dialogs, frames, downloads, and browser logs.
|
||||
---
|
||||
|
||||
# Browser automation with cmux
|
||||
|
||||
Use this skill for browser-driven validation through `cmux browser`.
|
||||
|
||||
## Goals
|
||||
|
||||
- Verify real user-facing behavior.
|
||||
- Access and inspect web pages.
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill when the task involves any of these:
|
||||
|
||||
- Opening or navigating a page
|
||||
- Testing a UI flow end to end
|
||||
- Filling forms or clicking controls
|
||||
- Verifying visible text, URL, title, values, attributes, or counts
|
||||
- Capturing snapshots or screenshots
|
||||
- Checking console logs or browser errors
|
||||
- Working with cookies, storage, or saved browser state
|
||||
- Handling tabs, dialogs, iframes, or downloads
|
||||
|
||||
Do not use this skill for unit tests, static analysis, or API-only checks unless browser behavior is part of the task.
|
||||
|
||||
## Operating rules
|
||||
|
||||
1. Start by identifying or opening the browser surface you will use.
|
||||
2. Wait for a stable state before interacting.
|
||||
3. Prefer stable selectors and structured getters over visual guesswork.
|
||||
4. After each mutating action, verify the result with URL, text, visibility, or value checks.
|
||||
5. Treat `console` and `errors` output as evidence, not optional noise.
|
||||
6. On failure, collect artifacts before concluding root cause.
|
||||
7. Use `eval` only when the browser commands cannot express the check directly.
|
||||
8. Keep credentials and secrets out of logs, commands, screenshots, and saved state when possible.
|
||||
|
||||
## Verified command surface
|
||||
|
||||
The commands below are verified against the official cmux browser automation docs.
|
||||
|
||||
### Targeting a browser surface
|
||||
|
||||
```bash
|
||||
cmux browser open https://example.com
|
||||
cmux browser open-split https://example.com
|
||||
cmux browser identify
|
||||
cmux browser identify --surface surface:2
|
||||
cmux browser surface:2 url
|
||||
cmux browser --surface surface:2 url
|
||||
```
|
||||
|
||||
### Navigation and focus
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 navigate https://example.com/docs --snapshot-after
|
||||
cmux browser surface:2 back
|
||||
cmux browser surface:2 forward
|
||||
cmux browser surface:2 reload --snapshot-after
|
||||
cmux browser surface:2 focus-webview
|
||||
cmux browser surface:2 is-webview-focused
|
||||
```
|
||||
|
||||
### Waiting
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 wait --load-state complete --timeout-ms 15000
|
||||
cmux browser surface:2 wait --selector "#checkout" --timeout-ms 10000
|
||||
cmux browser surface:2 wait --text "Order confirmed"
|
||||
cmux browser surface:2 wait --url-contains "/dashboard"
|
||||
cmux browser surface:2 wait --function "window.__appReady === true"
|
||||
```
|
||||
|
||||
Prefer this order of readiness checks:
|
||||
|
||||
1. `--selector` when a specific element gates the next action
|
||||
2. `--text` for user-visible confirmation
|
||||
3. `--url-contains` for navigation assertions
|
||||
4. `--function` only when the app exposes a reliable readiness flag
|
||||
5. `--load-state complete` for initial page load or simple pages
|
||||
|
||||
Avoid fixed sleeps unless there is no reliable signal.
|
||||
|
||||
### DOM interaction
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 click "button[type='submit']" --snapshot-after
|
||||
cmux browser surface:2 dblclick ".item-row"
|
||||
cmux browser surface:2 hover "#menu"
|
||||
cmux browser surface:2 focus "#email"
|
||||
cmux browser surface:2 check "#terms"
|
||||
cmux browser surface:2 uncheck "#newsletter"
|
||||
cmux browser surface:2 scroll-into-view "#pricing"
|
||||
cmux browser surface:2 type "#search" "cmux"
|
||||
cmux browser surface:2 fill "#email" --text "ops@example.com"
|
||||
cmux browser surface:2 press Enter
|
||||
cmux browser surface:2 keydown Shift
|
||||
cmux browser surface:2 keyup Shift
|
||||
cmux browser surface:2 select "#region" "us-east"
|
||||
cmux browser surface:2 scroll --dy 800 --snapshot-after
|
||||
cmux browser surface:2 scroll --selector "#log-view" --dx 0 --dy 400
|
||||
```
|
||||
|
||||
Prefer `fill` when setting a known final value.
|
||||
|
||||
Prefer `type` when testing keystroke-driven behavior such as debouncing, masking, shortcuts, or suggestions.
|
||||
|
||||
### Inspection and assertions
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 snapshot --interactive --compact
|
||||
cmux browser surface:2 snapshot --selector "main" --max-depth 5
|
||||
cmux browser surface:2 screenshot --out /tmp/cmux-page.png
|
||||
|
||||
cmux browser surface:2 get title
|
||||
cmux browser surface:2 get url
|
||||
cmux browser surface:2 get text "h1"
|
||||
cmux browser surface:2 get html "main"
|
||||
cmux browser surface:2 get value "#email"
|
||||
cmux browser surface:2 get attr "a.primary" --attr href
|
||||
cmux browser surface:2 get count ".row"
|
||||
cmux browser surface:2 get box "#checkout"
|
||||
cmux browser surface:2 get styles "#total" --property color
|
||||
|
||||
cmux browser surface:2 is visible "#checkout"
|
||||
cmux browser surface:2 is enabled "button[type='submit']"
|
||||
cmux browser surface:2 is checked "#terms"
|
||||
|
||||
cmux browser surface:2 find role button --name "Continue"
|
||||
cmux browser surface:2 find text "Order confirmed"
|
||||
cmux browser surface:2 find label "Email"
|
||||
cmux browser surface:2 find placeholder "Search"
|
||||
cmux browser surface:2 find alt "Product image"
|
||||
cmux browser surface:2 find title "Open settings"
|
||||
cmux browser surface:2 find testid "save-btn"
|
||||
cmux browser surface:2 find first ".row"
|
||||
cmux browser surface:2 find last ".row"
|
||||
cmux browser surface:2 find nth 2 ".row"
|
||||
|
||||
cmux browser surface:2 highlight "#checkout"
|
||||
```
|
||||
|
||||
Preferred selector order:
|
||||
|
||||
1. Stable test IDs
|
||||
2. Accessible role and name
|
||||
3. Labels and placeholders
|
||||
4. Semantic CSS selectors
|
||||
5. Text selectors
|
||||
|
||||
Avoid brittle selectors like deeply nested `nth-child` chains unless no better option exists.
|
||||
|
||||
### JavaScript and injection
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 eval "document.title"
|
||||
cmux browser surface:2 eval --script "window.location.href"
|
||||
cmux browser surface:2 addinitscript "window.__cmuxReady = true;"
|
||||
cmux browser surface:2 addscript "document.querySelector('#name')?.focus()"
|
||||
cmux browser surface:2 addstyle "#debug-banner { display: none !important; }"
|
||||
```
|
||||
|
||||
Use `eval` sparingly. Do not bypass the UI path if the task is to validate user behavior.
|
||||
|
||||
### State and session data
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 cookies get
|
||||
cmux browser surface:2 cookies get --name session_id
|
||||
cmux browser surface:2 cookies set session_id abc123 --domain example.com --path /
|
||||
cmux browser surface:2 cookies clear --name session_id
|
||||
cmux browser surface:2 cookies clear --all
|
||||
|
||||
cmux browser surface:2 storage local set theme dark
|
||||
cmux browser surface:2 storage local get theme
|
||||
cmux browser surface:2 storage local clear
|
||||
cmux browser surface:2 storage session set flow onboarding
|
||||
cmux browser surface:2 storage session get flow
|
||||
|
||||
cmux browser surface:2 state save /tmp/cmux-browser-state.json
|
||||
cmux browser surface:2 state load /tmp/cmux-browser-state.json
|
||||
```
|
||||
|
||||
Use saved browser state for authenticated sessions, long setup flows, and repeatable bug repros.
|
||||
|
||||
Do not use saved state when validating fresh-session behavior like login, onboarding, logout, or first-run UX.
|
||||
|
||||
### Tabs, logs, dialogs, frames, downloads
|
||||
|
||||
```bash
|
||||
cmux browser surface:2 tab list
|
||||
cmux browser surface:2 tab new https://example.com/pricing
|
||||
cmux browser surface:2 tab switch 1
|
||||
cmux browser surface:2 tab switch surface:7
|
||||
cmux browser surface:2 tab close
|
||||
cmux browser surface:2 tab close surface:7
|
||||
|
||||
cmux browser surface:2 console list
|
||||
cmux browser surface:2 console clear
|
||||
cmux browser surface:2 errors list
|
||||
cmux browser surface:2 errors clear
|
||||
|
||||
cmux browser surface:2 dialog accept
|
||||
cmux browser surface:2 dialog accept "Confirmed by automation"
|
||||
cmux browser surface:2 dialog dismiss
|
||||
|
||||
cmux browser surface:2 frame "iframe[name='checkout']"
|
||||
cmux browser surface:2 frame main
|
||||
|
||||
cmux browser surface:2 download --path /tmp/report.csv --timeout-ms 30000
|
||||
```
|
||||
|
||||
## Execution playbooks
|
||||
|
||||
### Default flow
|
||||
|
||||
Use this decision sequence unless the task clearly needs a different one.
|
||||
|
||||
1. Acquire a surface.
|
||||
|
||||
```bash
|
||||
cmux browser open <URL>
|
||||
cmux browser identify
|
||||
```
|
||||
|
||||
2. Establish readiness.
|
||||
|
||||
```bash
|
||||
cmux browser surface:<ID> wait --load-state complete --timeout-ms 15000
|
||||
cmux browser surface:<ID> snapshot --interactive --compact
|
||||
```
|
||||
|
||||
3. Choose the next action type.
|
||||
|
||||
- Navigation task: use `navigate`, `back`, `forward`, or `reload`, then wait again.
|
||||
- Form task: use the form playbook below.
|
||||
- Inspection task: use `get`, `is`, `find`, `snapshot`, or `screenshot`.
|
||||
- State setup task: use `cookies`, `storage`, or `state` before continuing.
|
||||
- Download, dialog, tab, or frame task: switch to the relevant specialized playbook.
|
||||
|
||||
4. After every mutating action, verify with at least one explicit assertion.
|
||||
|
||||
Preferred assertion order:
|
||||
|
||||
1. `wait --url-contains`
|
||||
2. `wait --text`
|
||||
3. `is visible`
|
||||
4. `get value`
|
||||
5. `get count`
|
||||
6. `errors list` when debugging or validating stability
|
||||
|
||||
7. If the assertion fails, run the failure protocol before making claims.
|
||||
|
||||
### Form playbook
|
||||
|
||||
Use this for login, signup, checkout, search, and settings forms.
|
||||
|
||||
1. Wait for the first required field.
|
||||
2. Populate fields with `fill` unless the task is specifically about typing behavior.
|
||||
3. Submit with `click`, `press Enter`, or the control the user would actually use.
|
||||
4. Verify success using URL, text, and visibility checks.
|
||||
|
||||
```bash
|
||||
cmux browser surface:<ID> wait --selector "#email" --timeout-ms 10000
|
||||
cmux browser surface:<ID> fill "#email" --text "$TEST_EMAIL"
|
||||
cmux browser surface:<ID> fill "#password" --text "$TEST_PASSWORD"
|
||||
cmux browser surface:<ID> click "button[type='submit']" --snapshot-after
|
||||
cmux browser surface:<ID> wait --url-contains "/dashboard" --timeout-ms 10000
|
||||
cmux browser surface:<ID> is visible "#dashboard"
|
||||
```
|
||||
|
||||
If submission should fail, verify the expected error text or blocked state instead of forcing success assertions.
|
||||
|
||||
### Navigation playbook
|
||||
|
||||
Use this when the task is about routing, links, history, or page transitions.
|
||||
|
||||
1. Trigger navigation.
|
||||
2. Wait for URL or page content to settle.
|
||||
3. Verify the destination.
|
||||
|
||||
```bash
|
||||
cmux browser surface:<ID> navigate https://example.com/docs --snapshot-after
|
||||
cmux browser surface:<ID> wait --url-contains "/docs" --timeout-ms 10000
|
||||
cmux browser surface:<ID> get title
|
||||
```
|
||||
|
||||
### Inspection playbook
|
||||
|
||||
Use this when the task is observational rather than interactive.
|
||||
|
||||
1. Prefer `find` to discover the right selector.
|
||||
2. Use `get` or `is` for structured assertions.
|
||||
3. Use `snapshot` or `screenshot` only when human review is useful.
|
||||
|
||||
### State playbook
|
||||
|
||||
Use this when the task depends on auth, persisted preferences, or reproducible setup.
|
||||
|
||||
1. Decide whether the task should start fresh or with persisted state.
|
||||
2. If fresh-session behavior matters, do not load saved state.
|
||||
3. If setup reuse is justified, use `cookies`, `storage`, or `state load`.
|
||||
4. After state changes, reload or navigate as needed and verify the expected state is visible.
|
||||
|
||||
### Tabs, dialogs, frames, and downloads playbook
|
||||
|
||||
- Tabs: `tab list`, `tab new`, `tab switch`, then verify with `get url` or visible text.
|
||||
- Dialogs: trigger the dialog, then immediately `dialog accept` or `dialog dismiss`.
|
||||
- Frames: enter with `frame <selector>`, complete the work, then return with `frame main`.
|
||||
- Downloads: trigger the download, run `download --path ...`, then verify the file with shell tools if needed.
|
||||
|
||||
## Failure protocol
|
||||
|
||||
Run this whenever a flow fails or results are ambiguous:
|
||||
|
||||
```bash
|
||||
cmux browser surface:<ID> console list
|
||||
cmux browser surface:<ID> errors list
|
||||
cmux browser surface:<ID> screenshot --out /tmp/cmux-failure.png
|
||||
cmux browser surface:<ID> snapshot --interactive --compact
|
||||
cmux browser surface:<ID> get url
|
||||
cmux browser surface:<ID> get title
|
||||
```
|
||||
|
||||
Report all of these if available:
|
||||
|
||||
- Failed action
|
||||
- Expected behavior
|
||||
- Actual behavior
|
||||
- Current URL
|
||||
- Current title
|
||||
- Relevant visible text
|
||||
- Console findings
|
||||
- Browser error findings
|
||||
- Artifact paths
|
||||
|
||||
## Flaky triage
|
||||
|
||||
If an interaction fails, use this exact order:
|
||||
|
||||
1. Check existence: `cmux browser surface:<ID> get count "<selector>"`
|
||||
2. Check visibility: `cmux browser surface:<ID> is visible "<selector>"`
|
||||
3. Check enabled state: `cmux browser surface:<ID> is enabled "<selector>"`
|
||||
4. Scroll into view: `cmux browser surface:<ID> scroll-into-view "<selector>"`
|
||||
5. Retry the action once
|
||||
6. If it still fails, stop retrying and run the failure protocol
|
||||
|
||||
## Reporting format
|
||||
|
||||
Use this concise result format:
|
||||
|
||||
```md
|
||||
## Browser Test Result
|
||||
|
||||
Status: PASS | FAIL | BLOCKED
|
||||
Tested URL: <url>
|
||||
Scenario: <what was tested>
|
||||
Result: <one-sentence outcome>
|
||||
|
||||
Evidence:
|
||||
|
||||
- <assertion or command result>
|
||||
- <assertion or command result>
|
||||
|
||||
Artifacts:
|
||||
|
||||
- Screenshot: <path or none>
|
||||
- Snapshot: <brief summary or none>
|
||||
- Console/errors: <brief summary>
|
||||
|
||||
Notes:
|
||||
<caveats, blockers, or likely cause if supported by evidence>
|
||||
```
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- Interacting before the page or element is ready
|
||||
- Assuming navigation succeeded without verifying URL or text
|
||||
- Using brittle selectors when stable ones exist
|
||||
- Treating `eval` as a substitute for user behavior
|
||||
- Ignoring `console` or `errors` output during failures
|
||||
- Reusing saved state in tests that should start fresh
|
||||
- Reporting success without at least one explicit assertion
|
||||
|
||||
## Gotcha: implicit Enter form submission
|
||||
|
||||
Some forms rely on the browser’s default behavior where pressing Enter in an input submits the form. In `cmux`, `fill`, `focus`, and `press Enter` may all appear to succeed without actually triggering submission.
|
||||
Rules:
|
||||
|
||||
- Never assume Enter submitted the form just because `press Enter` returned `OK`.
|
||||
- Always verify submission through URL change, visible success state, or expected content.
|
||||
- If Enter does not submit and there are no console/browser errors, suspect an automation limitation.
|
||||
- Retry once with `focus`, `focus-webview`, and `type "...\\n"`.
|
||||
- If still unsuccessful, validate the feature through the expected destination state and report that implicit Enter submission could not be reliably proven in `cmux`.
|
||||
Reference in New Issue
Block a user