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(f"Click succeeded: {result.outcome}")
    if result.url_changed:
        print(f"Navigated to: {browser.page.url}")

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")

    snap = snapshot(browser)
    link = find(snap, "role=link")
    if not link:
        raise RuntimeError("No link found on page")

    policy = CursorPolicy(
        mode="human",
        steps=18,  # more steps => smoother
        duration_ms=350,
        jitter_px=1.2,
        overshoot_px=6.0,
        pause_before_click_ms=30,
        seed=123,  # optional: deterministic for demos/tests
    )

    result = click(browser, link.id, use_mouse=True, cursor_policy=policy)
    print("clicked:", result.success, "outcome:", result.outcome)
    print("cursor meta:", result.cursor)

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})

# Click using element's bounding box
snap = snapshot(browser)
element = find(snap, "role=button")
click_rect(browser, {
    "x": element.bbox.x,
    "y": element.bbox.y,
    "w": element.bbox.width,
    "h": element.bbox.height
})

# Without highlight (for headless/CI)
click_rect(browser, {"x": 100, "y": 200, "w": 50, "h": 30}, highlight=False)

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=10)

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="instant", block="start")

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
    snap = snapshot(browser)
    
    # Find and fill email
    email_input = find(snap, "role=textbox")
    type_text(browser, email_input.id, "user@example.com")
    
    # Find and fill password
    snap = snapshot(browser)
    password_input = find(snap, "role=textbox", importance>500)
    type_text(browser, password_input.id, "password123")
    
    # Find and click submit button
    snap = snapshot(browser)
    submit_btn = find(snap, "role=button text~'Submit'")
    click(browser, submit_btn.id)
    
    # Or press Enter
    # press(browser, "Enter")