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/dblclickand MCPbrowser_interactwithclickordblclickuse the humanized click, andtypeuses human typing.fillstill 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)