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 realistic mouse simulation by default.

from sentience 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 (SentienceBrowser): 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)

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)

click_rect() / clickRect() - Click by Coordinates

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

from sentience 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 (SentienceBrowser): 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)

type_text() / typeText() - Type into Input

Types text into an input field.

from sentience 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 (SentienceBrowser): Browser instance
• element_id / elementId (int/number): Element ID from snapshot
• text (str/string): Text to type
• take_snapshot / takeSnapshot (bool, optional): Capture snapshot after typing (default: False)

press() - Keyboard Input

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

from sentience import press

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

Parameters:

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

Returns: ActionResult

Complete Example

from sentience import SentienceBrowser, snapshot, find, click, type_text, press

with SentienceBrowser(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")