Commands: act on the page
click, fill, type and the other actions, wait, downloads, screenshot, pdf, screencast.
| command | args | result |
|---|---|---|
click | target; --button right|middle; --force; --until-gone [--max <n>] (JSON until_gone: true or the most clicks) | state; fails naming the element that covers the target; synthetic_click note if a DOM click was used (--force, an element with no box); no_effect note if the page did nothing in response. --until-gone clicks again (a “Load more” button) while the element is there, shown and enabled and each click changes the page, at most 50 clicks: it follows the element first clicked, lets what each click fetched land, waits for a disabled one while the page is loading, and stops when the element is gone, hidden or stays disabled, a click changes nothing, a click opens another page, or at the limit; clicks and stopped say how many and why. A later click that fails ends the clicks and is named in stopped, not an error |
fill | target, <value> or --value; --keys selects what the field holds and types the value key by key (apps that keep only typed input, observable-model forms); waits (up to the command timeout) for the field to be visible, enabled and editable, and the timeout error names the check that failed; --force skips the checks | state |
type | <text> or --value; optional --selector/--ref/--text to focus first | state |
press | <key> or --key; optional target to focus first | state |
select | target, option label(s)/value(s) (positional or repeated --value; labels match with whitespace collapsed); --add keeps what a multiple select already has. On a custom dropdown (an ARIA combobox: react-select and the like) it does what a user does: focuses it, opens it (ArrowDown, else a click), finds the option by its text in the listbox that opened (a portal at the end of <body> included), types to filter when it isn’t listed, and clicks it | state + selected |
hover | target | state; synthetic_hover note if the element could not be hovered |
mouse | move <x> <y> [--steps n], down, up, click <x> <y> [--count n], wheel <dx> <dy>; --button left|right|middle; an optional target makes x/y relative to its top-left corner, scrolling it into view when that point is out of it (down, up and wheel with a target go to its center; a target in a cross-origin frame is refused). A click at viewport coordinates outside the viewport is refused; a move may leave it (a drag out of the window) | state, plus mouse: {x, y, held} (viewport CSS pixels, the buttons still held) |
scroll | --by <px> (default 800) or --to top|bottom; or a target to scroll into view (--by and --to scroll inside it: a list that loads more at its end). --to bottom at the end already waits up to 2 s for more to load, then goes to the new end | {scrollY, scrollHeight, viewport}; with a target {scrollY, scrollHeight} of the page, plus the element’s scrollTop and elementScrollHeight when --by/--to scrolled inside it |
upload | target, file path(s) (positional or --file) | {files} |
wait | any of --selector <css> (visible), --text <t>, --url <part>, --gone <css>, --js <expr>, --idle (no fetch/XHR for 500 ms; also --load networkidle), --download [<glob>] (a finished download whose file name matches), --ms <n>; --timeout-ms | state + waited_ms (+ download); --ms alone: {waited_ms} |
downloads | --clear, --json, --dir <path> | #n state bytes path (url) per file the pages downloaded, saved under --download-dir with the name the page gave it (report (2).csv if taken). With --attach the browser keeps its own download folder and path is empty. --dir saves this session’s downloads in <path> from now on (created if missing; kept across reset), apart from other sessions’ and returns {dir} |
check / uncheck | target (a ref or a targeting flag) | state + checked, changed: clicks a checkbox/radio/switch only when its state differs, fails if the click didn’t change it |
dblclick / focus | target | state / {focused} |
drag | <from> <to> (each a ref or CSS selector), or --from-text <t> --to-text <t> | state and drag: {html5: true, dropped} for a draggable source (the drag events with one DataTransfer, which headless Chrome will not start from synthetic input; dropped is false when the target does not accept it), else the two points a held mouse moved between (sliders, pointer-driven sortable lists) |
keydown / keyup | <key> | holds / releases a key; held modifiers apply to later presses |
insert-text | <text>, optional target to focus first | state: text inserted at the caret in one go (paste, IME), no key events |
pdf | [<path>] or --path; --landscape; --background | {path, bytes} |
screenshot | [<path>] or --path; --full-page, or one element (a ref, as screenshot 12 card.png, --selector, a locator): scrolled into view, then cropped to its box, a fraction of the bytes for a vision model; --annotate (the viewport or --full-page) outlines each ref of a fresh ax read and labels it with its number, so a model reading the image can say click 12 about what it sees: the marks are drawn into the page for the capture only (a closed shadow root, aria-hidden, no pointer events) and removed after it, and the result adds refs, how many it labelled; --quality <1-100> (a JPEG at that quality, not a PNG: about a quarter of the bytes for a page of text); --timeout-ms <n> (give up on the capture after n ms; default: the session timeout) | {path, bytes} |
screencast | start <dir> [--quality <0-100>] [--size <w>x<h>], stop | start: {screencast, recording}; stop: {screencast, frames, ms, player}. From start on, Chrome sends a JPEG each time the active tab’s pixels change (none while the page is still); each is written to <dir>/frame-NNNNN.jpg with its time, and the recording follows the session to the tab it acts on. stop writes <dir>/index.html, which plays the frames at their pace (space, arrows, a scrubber, speed). Default 1280x720 at most, quality 60. Not on Lightpanda |
Made from docs/navigera.md.