Action API

Interact with elements on the page using clicks, typing, and keyboard input.

click() - Click by Element ID

Clicks an element by ID. Uses Playwright mouse click by default, with optional human-like cursor movement via CursorPolicy (NEW in 2026-01-15).

from predicate import click

result = click(browser, button.id)
if result.success:
    print

Parameters:

• browser (PredicateBrowser): Browser instance
• element_id / elementId (int/number): Element ID from snapshot
• use_mouse / useMouse (bool, optional): Use Playwright's mouse.click() (default: True) or JS-based click
• take_snapshot / takeSnapshot (bool, optional): Capture snapshot after click (default: False)
• cursor_policy / cursorPolicy (CursorPolicy | object, optional): Opt-in human-like cursor movement before clicking (multi-step path with optional jitter/overshoot + pause). Adds cursor metadata to the action result.

Returns: ActionResult with:

• success: Whether click succeeded
• duration_ms: Time taken in milliseconds
• outcome: "navigated", "dom_updated", or "error"
• url_changed: Whether URL changed after click
• snapshot_after: Snapshot object (if take_snapshot=True)
• cursor: Cursor metadata (if cursor_policy is provided)

Human-like Cursor Movement (CursorPolicy)

Use CursorPolicy(mode="human", ...) to move the cursor along a human-like path before clicking. This is useful for demos, bot-detection sensitive pages, and trace/debugging.

from predicate import CursorPolicy, PredicateBrowser, click, find, snapshot

with PredicateBrowser() as browser:
    browser.page.goto("https://example.com")
    browser.page.wait_for_load_state("networkidle"

click_rect() / clickRect() - Click by Coordinates

Clicks at the center of a rectangle. Shows visual feedback (red border).

from predicate import click_rect

# Click at specific coordinates
click_rect(browser, {"x": 100, "y": 200, "w": 50, "h": 30})

Parameters:

• browser (PredicateBrowser): Browser instance
• rect (dict/object): Rectangle {"x": 100, "y": 200, "w": 50, "h": 30} or BBox object
• highlight (bool, optional): Show red border highlight (default: True)
• highlight_duration / highlightDuration (float, optional): How long to show highlight in seconds (default: 2.0)
• take_snapshot / takeSnapshot (bool, optional): Capture snapshot after click (default: False)
• cursor_policy / cursorPolicy (CursorPolicy | object, optional): Opt-in human-like cursor movement before clicking. Adds cursor metadata to the action result.

type_text() / typeText() - Type into Input

Types text into an input field.

from predicate import type_text

# Find input and type
snap = snapshot(browser)
email_input = find(snap, "role=textbox")
type_text(browser, email_input.id, "user@example.com")

Parameters:

• browser (PredicateBrowser): Browser instance
• element_id / elementId (int/number): Element ID from snapshot
• text (str/string): Text to type
• delay_ms (int/number, optional): Delay between keystrokes in milliseconds (default: 0). Use ~10ms to mimic human typing speed.
• take_snapshot / takeSnapshot (bool, optional): Capture snapshot after typing (default: False)

Human-like Typing

Use the delay_ms parameter to add realistic delays between keystrokes:

from predicate import type_text

# Instant typing (default)
type_text(browser, input.id, "Hello world")

# Human-like typing with 10ms delay between keystrokes
type_text(browser, input.id, "Hello world", delay_ms

scroll_to() / scrollTo() - Scroll Element into View

Scrolls an element into view using the native browser scrollIntoView() API.

from predicate import scroll_to

# Scroll element to center of viewport with smooth animation
scroll_to(browser, element.id, behavior="smooth", block="center")

# Instant scroll to top of viewport
scroll_to(browser, element.id, behavior

Parameters:

• browser (PredicateBrowser): Browser instance
• element_id / elementId (int/number): Element ID from snapshot
• behavior (str/string, optional): Scroll behavior - "smooth" or "instant" (default: "smooth")
• block (str/string, optional): Vertical alignment - "start", "center", "end", or "nearest" (default: "center")

Returns: ActionResult

press() - Keyboard Input

Presses a keyboard key (Enter, Escape, Tab, etc.).

from predicate import press

press(browser, "Enter")   # Submit form
press(browser, "Escape")  # Close modal

Parameters:

• browser (PredicateBrowser): Browser instance
• key (str/string): Key name (e.g., "Enter", "Escape", "Tab", "ArrowDown")

Returns: ActionResult

Complete Example

from predicate import PredicateBrowser, snapshot, find, click, type_text, press

with PredicateBrowser(api_key="sk_...") as browser:
    browser.page.goto("https://example.com/login")
    
    # Take snapshot