nodriver — undetected browser automation

Tick or untick a checkbox, or select a radio button, and verify it took. Use this instead of fill for anything with a checked state. fill types over a field's text, which a checkbox does not have — and its read-back compares `value`, which a checkbox never changes, so a fill could report success while nothing was selected. Idempotent: asking for the state it is already in is reported and does not click. Otherwise it delivers a real CDP click, on the element or, when the input is visually hidden behind a styled label (the usual custom-control pattern), on the label that controls it. The state is read back afterwards, so a failure is an error rather than a success you cannot trust.

Set a single browser cookie. Useful for injecting a known session token, consent flag or A/B bucket without walking through a login flow. This creates a session cookie: no expiry, gone when the browser closes. To restore a full cookie set including expiry and SameSite, use load_session. Cookies are browser-wide, not per tab.

Write entries into the current page's localStorage. Merges into what is already there rather than clearing it. Handy for setting feature flags, consent state or auth tokens before the page's own scripts read them. localStorage is scoped per origin, so navigate to the site first — writing on about:blank goes nowhere. Most pages read these values only at startup, so reload after setting them.

Send this browser's traffic through a proxy, with credentials if it wants them. The proxy itself is a launch flag, so it needs a browser restart — which on an ephemeral profile also drops its cookies. Authentication is handled live: an authenticating proxy stops Chrome at a native dialog that no page and no other CDP command can dismiss, so the page just never loads and nothing says why. Answering it means enabling the Fetch domain, which pauses every request for a round trip, so that only happens when a username is actually set. A proxy that does not ask for credentials costs nothing extra. Call with no arguments to see what is configured. The password is never echoed back. Values set here override the NODRIVER_PROXY environment variable.

Quit one browser's Chrome and free its name, releasing all memory behind it. Use it when an agent is finished with its browser. The difference to close_browser: close_browser quits Chrome but keeps the browser, so its selected profile and runtime flags survive and the next call relaunches Chrome with them. shutdown_browser discards that too, and the name starts fresh if it is ever used again. The "default" browser cannot be retired, since it is the server itself; shutting it down quits its Chrome and resets it. A browser you attached to with use_running_browser is only detached from, never closed: it belongs to the user.

Capture a V8 heap snapshot of the page, for memory-leak debugging. Writes the raw .heapsnapshot file for Chrome DevTools -> Memory -> Load. The usual workflow is two snapshots taken around a suspect interaction, then comparing retained objects between them. On a heavy page a snapshot can be hundreds of megabytes and take several seconds; the response reports the resulting file size.

Capture the page, the viewport or a single element as an image. Do NOT use this to read a page. take_snapshot gives you the same content as searchable text, is dramatically smaller, and yields the uids every interaction tool needs. Use a screenshot only when you genuinely need pixels: layout and styling checks, visual regression, or text that exists only inside an image. Element capture needs a uid from the current snapshot. Without file_path the image is returned inline as a base64 data URL.

Read the page as compact text, with a uid for every element. This is the primary way to see a page, and the source of the uids that click, fill, hover, drag and upload_file all take. Prefer it over take_screenshot for anything but a genuine visual check: it is searchable, far smaller, and it is what makes interaction possible at all. The output is the accessibility tree — roles, names, values and states, indented by nesting — with Chrome-internal and purely presentational nodes filtered out unless `verbose` is set. A URL on the same origin as the page is printed relative to it — the root node carries the absolute one, so nothing is lost and a link-dense page costs noticeably less to read. uids stay stable across snapshots for elements that did not change, but any page change can invalidate them. Whenever a tool reports "unknown uid", take a fresh snapshot and use the new uid. Output is capped at 200 000 characters. Frames are included and marked, so an element inside an iframe gets a uid like any other and click, fill and evaluate_script work on it unchanged. For plain page text without uids, get_page_content is cheaper; to find elements by CSS selector, use query_selector.

Type text into whatever element currently has focus. Appends at the caret instead of replacing, and needs something focused already — click the field first, or use fill, which takes a uid, clears the field and needs no separate focus step. Prefer fill for ordinary form filling. Use type_text when you must add to existing content, or for widgets that only react to raw key events such as contenteditable, rich-text and canvas editors.

Attach a local file to a file input on the page. Sets the input's files directly over CDP, so no OS file-picker dialog ever opens — clicking an upload button normally would open one, and that blocks every further tool call until a human dismisses it. Chrome renders a file input with an internal shadow button, and that is what the accessibility tree exposes, so the uid you can see is usually not the input itself. This resolves to the real input: the element, one inside it, the input a label controls, or one just above in the tree. The result is read back. If the page's own uploader consumed the file straight away, the response says so, which is a successful upload rather than an empty input.

Switch the browser to a named persistent profile. Use it to pick up the cookies, logins and extensions stored in an earlier session, so a run starts out already authenticated. Restarts the browser and closes every open page. The profile has to exist already — create it first with create_profile. Only one browser may use a profile at a time; a second instance pointed at the same one fails to start.

Drive a Chrome that is already running, instead of launching a new one. This is how you use a browser you are already signed into. Chrome locks its user-data-dir, so the profile holding your real logins cannot be opened a second time — attaching to the running instance is the only way in, and it saves rebuilding every login through the automation. The user starts Chrome themselves, once: chrome --remote-debugging-port=9222 --user-data-dir=/path/to/profile then this tool attaches to it. Every tool then acts on that browser and its real tabs. `--user-data-dir` is not optional, and it must not be Chrome's own default directory. Since Chrome 136 the port is refused there — Chrome starts normally, says nothing, and nothing ever listens, which is a confusing way to fail. So the everyday profile cannot be reached by adding the flag to it; it has to be a directory of its own, and a copy of an existing profile is accepted (`--profile-directory` then picks which profile inside it). SECURITY: that profile becomes part of the agent's reach. Whatever it is signed into — mail, bank, company systems — is reachable from here, because a cookie jar is all or nothing. Point this at a profile you are willing to expose, not your everyday one. While attached, close_browser and every profile switch only detach; they never close a browser they did not start. Return to a self-launched browser with use_temp_profile or use_profile.

Switch back to a fresh ephemeral profile, created and deleted per session. This is the default. It leaves nothing behind on disk and lets many nodriver instances run concurrently without colliding on a profile directory. Restarts the browser and closes all open pages. The profile you are leaving is not deleted — a persistent one keeps its cookies for the next use_profile. Anything held in the outgoing temp profile is gone.

Wait until one of several texts appears on the page, then snapshot it. The right way to wait after an action that starts loading — far more reliable than guessing a delay, and it returns the moment the text shows up instead of always burning the whole timeout. On success the page snapshot is included in the response, so no separate take_snapshot call is needed. Polls the visible text twice a second. To wait for an element rather than for wording, use wait_for_selector.

Wait until an element matching a CSS selector appears on the page. The structural counterpart to wait_for: use it when you know the markup but not the wording, or when the wording is localised. Polls about three times a second and returns as soon as the element shows up. Unlike wait_for it does not return a snapshot, so follow with take_snapshot when you intend to interact.