@v1:e3). Refs are generated by gsd-browser snapshot and are the preferred approach because they are stable, versioned, and fully described by the browser’s internal element model. Always re-run gsd-browser snapshot after navigation or significant DOM changes before using refs from a previous snapshot.
gsd-browser snapshot
Scan the page and assign versioned refs (@vN:eM) to interactive elements. Refs returned by a snapshot are valid until the page changes; after any navigation or DOM mutation, take a fresh snapshot before using ref-based commands.
Focus the snapshot on a subset of elements. Accepted values:
| Mode | What it captures |
|---|---|
interactive (default) | Buttons, inputs, links, and selects |
form | Form fields with current values and labels |
dialog | Content inside open modals or dialogs |
navigation | Navigation links and menus |
errors | Error messages and validation hints |
headings | h1–h6 elements |
visible_only | Every visible element on the page |
Scope the snapshot to a specific region of the page using a CSS selector.
Maximum number of elements to include. Defaults to
40. Increase this on complex single-page apps.gsd-browser get-ref
Retrieve metadata for a specific element ref, including its bounding box, ARIA role, CSS selector, and structural signature. Use this to inspect an element before interacting with it or to debug a stale-ref problem.
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.gsd-browser click
Click an element identified by a CSS selector or by exact coordinates. To click by ref, use gsd-browser click-ref instead.
CSS selector of the element to click. Omit when clicking by coordinates.
Horizontal coordinate in CSS pixels. Must be used with
--y.Vertical coordinate in CSS pixels. Must be used with
--x.gsd-browser click-ref
Click an element identified by its snapshot ref. Prefer this over click when you have a fresh snapshot — refs encode element identity more precisely than CSS selectors.
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.gsd-browser type
Type text into an input element. By default the text is filled atomically; use --slowly when you need realistic keystroke-by-keystroke input (e.g. to trigger autocomplete handlers).
CSS selector of the target input, textarea, or content-editable element.
The text to type into the element.
Type character-by-character with realistic delays between keystrokes. Useful for triggering autocomplete, search suggestions, or other keystroke-driven event listeners.
Clear any existing value in the field before typing the new text.
Press Enter after typing to submit the field or form.
gsd-browser fill-ref
Type text into an element identified by its snapshot ref.
A versioned ref string in
@vN:eM format, as returned by gsd-browser snapshot.The text to type into the element.
Clear any existing value before typing.
Press Enter after typing.
Type character-by-character instead of atomically filling the field.
gsd-browser press
Dispatch a keyboard event for a single key or a key combination. Use key names from the DOM KeyboardEvent.key spec, joined by + for modifiers.
Key name or combination. Examples:
Enter, Escape, Tab, ArrowDown, Meta+A, Control+C, Shift+Tab.gsd-browser hover
Move the mouse pointer over an element to trigger hover states, tooltips, or dropdown menus that only appear on mouse-over.
CSS selector of the element to hover over.
gsd-browser scroll
Scroll the page up or down. Use --direction to choose the direction and --amount to control how far.
Scroll direction:
up or down.Number of pixels to scroll. Defaults to
300.gsd-browser select-option
Select an option from a <select> dropdown element by matching its label text or value attribute.
CSS selector of the
<select> element.The option label (visible text) or value attribute to select.
gsd-browser set-checked
Set the checked state of a checkbox or radio button. Pass --checked to check the element; omit it to uncheck.
CSS selector of the checkbox or radio
<input> element.Set the element to the checked state. Omit this flag to uncheck the element.
gsd-browser drag
Drag an element from a source to a target using either CSS selectors or explicit coordinates. The drag movement is interpolated across several steps to produce realistic pointer events.
CSS selector of the element to drag from.
CSS selector of the element to drop onto.
Starting X coordinate in CSS pixels (coordinate-based mode).
Starting Y coordinate in CSS pixels (coordinate-based mode).
Ending X coordinate in CSS pixels (coordinate-based mode).
Ending Y coordinate in CSS pixels (coordinate-based mode).
Number of interpolation steps between start and end positions. Higher values produce smoother motion. Defaults to
10.Mouse button held during the drag:
left (default), right, or middle.gsd-browser upload-file
Set one or more files on a <input type="file"> element. Pass local file paths as space-separated positional arguments.
CSS selector of the
<input type="file"> element.One or more local file paths to attach to the input.
gsd-browser set-viewport
Resize the browser viewport using a named preset or exact pixel dimensions. Use this to test responsive layouts or simulate device screen sizes.
A named viewport preset:
| Preset | Dimensions |
|---|---|
mobile | 390 × 844 |
tablet | 768 × 1024 |
desktop | 1280 × 800 |
wide | 1920 × 1080 |
Viewport width in pixels. Use with
--height for custom dimensions.Viewport height in pixels. Use with
--width for custom dimensions.