Skip to content
On this page

Humanizer

WebSkrap's humanizer drives the real mouse and keyboard with human timing instead of mechanical input. human_click waits for a visible target, scrolls it into view with the mouse wheel, moves the mouse along a curved eased path, and clicks near the target center with a human button hold; human_type clicks into a field the same way and types one key at a time. Both send trusted input through the CDP Input domain.

async with WebSkrapClient() as client:
    session = await client.session("default")
    page = await session.new_page()
    await page.goto("https://example.com", wait_until="domcontentloaded", timeout_s=30)
    await session.human_click(page, "button[type='submit']")

Use it when a normal page interaction should look closer to a manual browser click. It is useful for flows with hover-sensitive controls, scroll-dependent layouts, or simple behavioral checks that treat instant coordinate jumps as synthetic.

The cursor follows a Bezier curve with randomized control points and eased spacing, so it accelerates and slows near the target instead of tracing a straight, evenly spaced line. The algorithm is adapted from HumanCursor and reimplemented without adding a dependency.

What a page's scripts see, compared with mechanical input (human=False):

Signal Mechanical Humanizer
Scrolling to an off-screen target a jump with no wheel events wheel events in notch-sized steps with short pauses
Cursor before the click moves straight to the target center a curved path of mousemove events
Button hold (mousedown to mouseup) no pause 60-140 ms
Typing fill: no key events each key held 30-90 ms, 40-160 ms apart, with an occasional longer pause

Before any pointer event, the humanizer checks with elementFromPoint that nothing covers the exact click point, in the element's own frame and shadow root, and raises a usage error if something does. The check runs in an isolated world, so the page sees no event from it.

If the mouse wheel cannot move the target into view, for example inside an inner scroll container the cursor is not over, a direct scroll finishes the job.

If the target loses its bounding box, the humanizer scrolls it into view, waits 300–600 ms, and measures it once more. An empty box after that attempt raises a usage error.

The cursor ends at the click point. The random offset stays within the target, up to 12 CSS pixels horizontally and 10 vertically. Before pressing, the humanizer pauses for 200–500 ms and checks the target again. It refuses the click if the target becomes hidden, disabled, or no longer receives input at that point. This also catches changes caused by hover handlers.

There is no fixed delay after a click. Wait for the expected page change in your flow.

Typing

await session.human_type(page, "input[name='q']", "running shoes")

The text is appended to what the field holds. Characters that a US keyboard cannot type are inserted as text. timeout is honored.

Where it applies automatically

  • Cookie consent dismissal (decline_cookies) clicks the reject control with the humanized click, including notices inside CMP iframes. The banner is usually the first thing clicked on a page, and the page's bot script sees that click too.
  • Persistent sessions: webskrap browser click / dblclick and MCP browser_interact with click or dblclick use the humanized click, and type uses human typing. fill still sets the value at once, for speed.

Humanized input is slower by design: a click takes roughly half a second to a second, and typing about a tenth of a second per character.

Direct click fallback

Pass human=False to click the element's center at once. The visibility, enabled and strict-match checks still apply.

await session.human_click(page, "button[type='submit']", human=False, timeout=5_000)

Click options

human_click takes click_count (1 for a click, 2 for a double-click) and timeout in milliseconds. The target is a CSS selector or a snapshot ref (e12). A CSS selector that matches more than one element is refused.

await session.human_click(page, "button[type='submit']", click_count=2, timeout=10_000)