Mouse and keyboard
Mouse
browser.click(selector, human=True, click_type=ClickType.LEFT, timeout=10.0)
browser.click_at(target, click_type=ClickType.LEFT, human=True, timeout=10.0)
browser.move_to(target, offset_x=None, offset_y=None, human=True, timeout=10.0)
browser.hover(target, ...) # same as move_to
browser.drag_and_drop(source, target, human=True, timeout=10.0)
browser.get_center(target) # -> Point {"x": int, "y": int}; also .x, .ytarget is a CSS selector or an Element. A selector is resolved with
wait_for_element(selector, timeout). Each method returns the element it acted
on (drag_and_drop returns None).
ClickType values: LEFT (default), RIGHT, MIDDLE, DOUBLE. A double click
is one cursor movement followed by two presses at the OS double-click interval.
human=True moves the cursor along a path planned by the browser’s motion
planner (see Human-like input); human=False puts it on
the target in one step.
A drag verifies the drop target while the button is held. If verification fails after the button went down, the cursor returns to the source, Escape is sent to cancel the drag, and only then is the button released.
Keyboard
browser.type(
selector, text, characters_per_minute=None, offset=None, human=True, timeout=10.0
)
browser.type_at(target, text, ..., click_type=ClickType.LEFT)Typing clicks the element (with the same verification as a click), then checks
that the element holds keyboard focus and that the browser window has OS focus.
If it does not after one focus() retry, NativeInputError is raised and no
keys are sent. Focus is checked again between chunks of text, so typing stops
as soon as focus moves elsewhere.
Element.type(..., settle=True) (the default) then waits until the page shows
the typed text, returning after at most 2 seconds with a logged warning;
settle=False returns as soon as the keys are sent. Browser.type and
Browser.type_at take no settle parameter and always wait this way.
How characters are delivered:
- Windows: every character is sent with
SendInputas a Unicode keystroke (KEYEVENTF_UNICODE). The active keyboard layout does not matter: Cyrillic, CJK, accented letters and emoji are typed as keystrokes, never pasted.\nis sent as Enter and\tas Tab. - Linux: every character is typed as a keystroke through X11 XTest, whatever the keyboard layout. A character the layout lacks (Cyrillic on a US layout, CJK, emoji) is typed on a spare keycode that emunium maps to it for a moment and restores afterwards; nothing is pasted. Run one emunium process per X display (one worker per display or Xvfb): two processes typing such characters on the same display can interfere.
- macOS: printable ASCII,
\nand\tare typed as key presses. Other characters are typed with thekeyboardpackage when it is installed and the process runs as root; otherwise they are pasted through the clipboard (Cmd+V). The previous clipboard text is restored afterwards if the clipboard still holds the pasted text.
human=True waits between keystrokes as the browser’s typing rhythm draws it
(see Typing rhythm). characters_per_minute (60 to 900)
overrides the rhythm’s median speed and offset (milliseconds, 0 to 1000 and
below the median interval 60000 / characters_per_minute) its random jitter;
None keeps the rhythm’s own values. With human=True, a value outside these
ranges raises InvalidArgumentError before any key is sent.
characters_per_minute of 0 or less, like
human=False, types without delay between keystrokes.
Fail-safe
- Windows and Linux: with the cursor in a corner of the primary screen (on
Linux, of the X screen), the next native action is refused with
NativeInputError. SetEMUNIUM_FAILSAFE=0to disable this check. - macOS: pyautogui’s own fail-safe applies and raises
pyautogui.FailSafeException.EMUNIUM_FAILSAFEhas no effect there.