Emunium documentation
Emunium reads the page through a browser extension and acts through the operating system. Use Python locators to find elements, then move the desktop cursor, click, and type through native input.
Start an installed Chrome, Edge, Brave, or Chromium, or connect to a prepared Firefox-family profile, including Camoufox. The guides below include the full reference from the original README.
Install the package and make your first verified click.
Browser setupInstalled Chrome, Camoufox, profiles, and extension installation.
Locators & assertionsFind by role, label, or text. Wait for the state you need.
Human-like inputChoose natural, careful, or brisk. Tune the models when needed.
How it works
The extension finds elements and reads page state. Native input handles the mouse and keyboard. Before a click, Emunium checks that the page sees the pointer over the intended element. Typing checks keyboard focus.
| Task | How Emunium handles it |
|---|---|
| Find an element | Extension-based CSS, XPath, text, role, label, or test-ID lookup |
| Click or type | OS input: Win32 on Windows, X11 XTest on Linux, pyautogui on macOS |
| Wait for a result | Element conditions, navigation waits, response waits, and assertions |
| Keep a profile | A persistent profile or Browser.connect() |
| Automate the desktop | Image matching and optional OCR in standalone mode |
Before you run
Native input moves the real cursor and uses the desktop keyboard. Keep the browser visible and focused, and do not use the mouse or keyboard while the script runs. Headless sessions support DOM operations, not native input. Iframes are not supported.
Read Limitations for platform requirements and Running in parallel before adding workers.
Find the reference
Navigation, waiting, element handles, locators, mouse and keyboard, tabs, network waits, JavaScript, and errors each have their own page.
For non-browser work, see Standalone mode, PageParser and Locator, and Advanced utilities.
Source documentation
All 25 substantive sections of the supplied README are included as separate pages. Examples, option tables, formulas, and caveats are retained. Headings and internal links were adapted for the site; motion-model details are collapsible.
The original README and original CHANGELOG are available unabridged. This overview and the home page are navigation summaries. Release behavior is documented in the Changelog.
Emunium does not claim that native input is indistinguishable from a person’s input or that it guarantees avoidance of bot detection.