| Name | emunium JSON |
| Version |
2.0.2
JSON |
| download |
| home_page | https://github.com/DedInc/emunium |
| Summary | A Python module for automating interactions to mimic human behavior in standalone apps or browsers when using Selenium, Pyppeteer, or Playwright. |
| upload_time | 2024-06-08 07:13:33 |
| maintainer | None |
| docs_url | None |
| author | Maehdakvan |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🤖 Emunium
A Python module for automating interactions to mimic human behavior in standalone apps or browsers when using Selenium, Pyppeteer, or Playwright. Provides utilities to programmatically move the mouse cursor, click on page elements, type text, and scroll as if performed by a human user.
## 🚀 Quickstart (Standalone)
```python
from emunium import Emunium
emunium = Emunium()
elements = emunium.find_elements('field.png', min_confidence=0.8)
emunium.type_at(elements[0], 'Automating searches')
elements = emunium.find_elements('search_icon.png', min_confidence=0.8)
emunium.click_at(elements[0])
```
## 🚀 Quickstart (with Selenium)
```python
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from emunium import EmuniumSelenium
driver = webdriver.Chrome()
wait = WebDriverWait(driver, 10)
emunium = EmuniumSelenium(driver)
driver.get('https://duckduckgo.com/')
element = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[data-state="suggesting"]')))
emunium.type_at(element, 'Automating searches')
submit = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[aria-label="Search"]')))
emunium.click_at(submit)
driver.quit()
```
## 🚀 Quickstart (with Pyppeteer)
```python
import asyncio
from pyppeteer import launch
from emunium import EmuniumPpeteer
async def main():
browser = await launch(headless=False)
page = await browser.newPage()
emunium = EmuniumPpeteer(page)
await page.goto('https://duckduckgo.com/')
element = await page.waitForSelector('[data-state="suggesting"]')
await emunium.type_at(element, 'Automating searches')
submit = await page.waitForSelector('[aria-label="Search"]')
await emunium.click_at(submit)
await browser.close()
asyncio.get_event_loop().run_until_complete(main())
```
## 🚀 Quickstart (with Playwright)
```python
import asyncio
from playwright.async_api import async_playwright
from emunium import EmuniumPlaywright
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch(headless=False)
page = await browser.new_page()
emunium = EmuniumPlaywright(page)
await page.goto('https://duckduckgo.com/')
element = await page.wait_for_selector('[data-state="suggesting"]')
await emunium.type_at(element, 'Automating searches')
submit = await page.wait_for_selector('[aria-label="Search"]')
await emunium.click_at(submit)
await browser.close()
asyncio.run(main())
```
## 🖱️ Moving the Mouse
The `move_to()` method moves the mouse cursor smoothly to the provided element with small randomizations in speed and path to seem human.
Options:
- `offset_x` and `offset_y` - offset mouse position from element center
## 🖱️ Clicking Elements
The `click_at()` method moves via `move_to()` and clicks at the center of the provided element.
Emunium supports multiple mouse click types:
```python
from emunium import ClickType
emunium.click_at(element) # left click
emunium.click_at(element, ClickType.RIGHT) # right click
emunium.click_at(element, ClickType.MIDDLE) # middle click
emunium.click_at(element, ClickType.DOUBLE) # double click
```
## 🔎 Finding Elements
In standalone mode, Emunium can locate elements on the screen using image matching with the `find_elements` method:
```python
elements = emunium.find_elements('search_icon.png', min_confidence=0.8)
```
The `find_elements` method takes the following parameters:
- `image_path` (required): The path to the image file to search for on the screen.
- `min_confidence` (optional, default 0.8): The minimum confidence level (between 0 and 1) for image matching. Higher values result in more precise matching but may miss some elements.
- `target_height` (optional): The expected height of the elements to find. If provided along with `target_width`, elements that don't match the specified size (within a tolerance based on `min_confidence`) will be filtered out.
- `target_width` (optional): The expected width of the elements to find. Must be provided together with `target_height`.
- `max_elements` (optional, default 0): The maximum number of elements to return. If set to 0 or not provided, all matching elements will be returned.
The `find_elements` method returns a list of dictionaries, each containing the 'x' and 'y' coordinates of the center point of a matched element.
## ⌨️ Typing Text
The `type_at()` method moves to the provided element via `move_to()`, clicks it via `click_to()`, and types the provided text in a "silent" way, spreading out key presses over time with small randomizations to mimic human typing.
Options:
- `characters_per_minute` - typing speed in characters per minute (default 280)
- `offset` - randomization (threshold) in milliseconds between key presses (default 20ms)
## 📜 Scrolling Pages
The `scroll_to()` method scrolls the page to bring the provided element into view using smooth scrolling.
Includes timeouts and checks to handle issues with scrolling getting stuck.
## 🏁 Conclusion
Emunium provides a set of utilities to help automate browser interactions in a more human-like way when using Selenium, Pyppeteer, or Playwright. By moving the mouse, clicking, typing, and scrolling in a less robotic fashion, tests can avoid detection and run more reliably.
While basic automation scripts can still get the job done, Emunium aims to make tests appear even more life-like. Using the randomizations and smooth behaviors it offers can be beneficial for automation projects that require avoiding detections.
Raw data
{
"_id": null,
"home_page": "https://github.com/DedInc/emunium",
"name": "emunium",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Maehdakvan",
"author_email": "visitanimation@google.com",
"download_url": "https://files.pythonhosted.org/packages/a7/85/52f5c3c25c0f0cb963c02d3e471739a2a901cb60d6463cbd4b1f9e67162e/emunium-2.0.2.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 Emunium\r\n\r\nA Python module for automating interactions to mimic human behavior in standalone apps or browsers when using Selenium, Pyppeteer, or Playwright. Provides utilities to programmatically move the mouse cursor, click on page elements, type text, and scroll as if performed by a human user.\r\n\r\n\r\n\r\n\r\n\r\n## \ud83d\ude80 Quickstart (Standalone)\r\n\r\n```python\r\nfrom emunium import Emunium\r\n\r\nemunium = Emunium()\r\n\r\nelements = emunium.find_elements('field.png', min_confidence=0.8)\r\n\r\nemunium.type_at(elements[0], 'Automating searches')\r\n\r\nelements = emunium.find_elements('search_icon.png', min_confidence=0.8)\r\nemunium.click_at(elements[0])\r\n```\r\n\r\n## \ud83d\ude80 Quickstart (with Selenium)\r\n\r\n```python\r\nfrom selenium import webdriver\r\nfrom selenium.webdriver.common.by import By\r\nfrom selenium.webdriver.support.ui import WebDriverWait\r\nfrom selenium.webdriver.support import expected_conditions as EC\r\nfrom emunium import EmuniumSelenium\r\n\r\ndriver = webdriver.Chrome()\r\nwait = WebDriverWait(driver, 10)\r\nemunium = EmuniumSelenium(driver)\r\n\r\ndriver.get('https://duckduckgo.com/')\r\n\r\nelement = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[data-state=\"suggesting\"]')))\r\n\r\nemunium.type_at(element, 'Automating searches')\r\n\r\nsubmit = wait.until(EC.element_to_be_clickable((By.CSS_SELECTOR, '[aria-label=\"Search\"]')))\r\nemunium.click_at(submit)\r\n\r\ndriver.quit()\r\n```\r\n\r\n## \ud83d\ude80 Quickstart (with Pyppeteer)\r\n\r\n```python\r\nimport asyncio\r\nfrom pyppeteer import launch\r\nfrom emunium import EmuniumPpeteer\r\n\r\nasync def main():\r\n browser = await launch(headless=False)\r\n page = await browser.newPage()\r\n emunium = EmuniumPpeteer(page)\r\n\r\n await page.goto('https://duckduckgo.com/')\r\n\r\n element = await page.waitForSelector('[data-state=\"suggesting\"]')\r\n await emunium.type_at(element, 'Automating searches')\r\n\r\n submit = await page.waitForSelector('[aria-label=\"Search\"]')\r\n await emunium.click_at(submit)\r\n\r\n await browser.close()\r\n\r\nasyncio.get_event_loop().run_until_complete(main())\r\n```\r\n\r\n## \ud83d\ude80 Quickstart (with Playwright)\r\n\r\n```python\r\nimport asyncio\r\nfrom playwright.async_api import async_playwright\r\nfrom emunium import EmuniumPlaywright\r\n\r\nasync def main():\r\n async with async_playwright() as p:\r\n browser = await p.chromium.launch(headless=False)\r\n page = await browser.new_page()\r\n emunium = EmuniumPlaywright(page)\r\n\r\n await page.goto('https://duckduckgo.com/')\r\n\r\n element = await page.wait_for_selector('[data-state=\"suggesting\"]')\r\n await emunium.type_at(element, 'Automating searches')\r\n\r\n submit = await page.wait_for_selector('[aria-label=\"Search\"]')\r\n await emunium.click_at(submit)\r\n\r\n await browser.close()\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## \ud83d\uddb1\ufe0f Moving the Mouse\r\n\r\nThe `move_to()` method moves the mouse cursor smoothly to the provided element with small randomizations in speed and path to seem human.\r\n\r\nOptions:\r\n- `offset_x` and `offset_y` - offset mouse position from element center\r\n\r\n## \ud83d\uddb1\ufe0f Clicking Elements\r\n\r\nThe `click_at()` method moves via `move_to()` and clicks at the center of the provided element.\r\n\r\nEmunium supports multiple mouse click types:\r\n\r\n```python\r\nfrom emunium import ClickType\r\n\r\nemunium.click_at(element) # left click\r\nemunium.click_at(element, ClickType.RIGHT) # right click \r\nemunium.click_at(element, ClickType.MIDDLE) # middle click\r\nemunium.click_at(element, ClickType.DOUBLE) # double click\r\n```\r\n\r\n## \ud83d\udd0e Finding Elements\r\n\r\nIn standalone mode, Emunium can locate elements on the screen using image matching with the `find_elements` method:\r\n\r\n```python\r\nelements = emunium.find_elements('search_icon.png', min_confidence=0.8)\r\n```\r\n\r\nThe `find_elements` method takes the following parameters:\r\n\r\n- `image_path` (required): The path to the image file to search for on the screen.\r\n- `min_confidence` (optional, default 0.8): The minimum confidence level (between 0 and 1) for image matching. Higher values result in more precise matching but may miss some elements.\r\n- `target_height` (optional): The expected height of the elements to find. If provided along with `target_width`, elements that don't match the specified size (within a tolerance based on `min_confidence`) will be filtered out.\r\n- `target_width` (optional): The expected width of the elements to find. Must be provided together with `target_height`.\r\n- `max_elements` (optional, default 0): The maximum number of elements to return. If set to 0 or not provided, all matching elements will be returned.\r\n\r\nThe `find_elements` method returns a list of dictionaries, each containing the 'x' and 'y' coordinates of the center point of a matched element.\r\n\r\n\r\n## \u2328\ufe0f Typing Text\r\n\r\nThe `type_at()` method moves to the provided element via `move_to()`, clicks it via `click_to()`, and types the provided text in a \"silent\" way, spreading out key presses over time with small randomizations to mimic human typing.\r\n\r\nOptions:\r\n- `characters_per_minute` - typing speed in characters per minute (default 280)\r\n- `offset` - randomization (threshold) in milliseconds between key presses (default 20ms)\r\n\r\n## \ud83d\udcdc Scrolling Pages\r\n\r\nThe `scroll_to()` method scrolls the page to bring the provided element into view using smooth scrolling.\r\n\r\nIncludes timeouts and checks to handle issues with scrolling getting stuck.\r\n\r\n## \ud83c\udfc1 Conclusion\r\n\r\nEmunium provides a set of utilities to help automate browser interactions in a more human-like way when using Selenium, Pyppeteer, or Playwright. By moving the mouse, clicking, typing, and scrolling in a less robotic fashion, tests can avoid detection and run more reliably.\r\n\r\nWhile basic automation scripts can still get the job done, Emunium aims to make tests appear even more life-like. Using the randomizations and smooth behaviors it offers can be beneficial for automation projects that require avoiding detections.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python module for automating interactions to mimic human behavior in standalone apps or browsers when using Selenium, Pyppeteer, or Playwright.",
"version": "2.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/DedInc/emunium/issues",
"Homepage": "https://github.com/DedInc/emunium"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "95849a0d5a77901cd600210ee948117193d60a14e45216d6a6186de75afd8143",
"md5": "ba3bc69e62f81b66fa752e5b04b2b016",
"sha256": "a9f0df889fa83de13df699e99d98d3fbe9a2529963544280f288a306576cd7ca"
},
"downloads": -1,
"filename": "emunium-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba3bc69e62f81b66fa752e5b04b2b016",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7775,
"upload_time": "2024-06-08T07:13:31",
"upload_time_iso_8601": "2024-06-08T07:13:31.576157Z",
"url": "https://files.pythonhosted.org/packages/95/84/9a0d5a77901cd600210ee948117193d60a14e45216d6a6186de75afd8143/emunium-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a78552f5c3c25c0f0cb963c02d3e471739a2a901cb60d6463cbd4b1f9e67162e",
"md5": "db4aa88cfb62577a3e6175c10f7ab412",
"sha256": "6177e9effd0529e7dbbfcea0d128b1fa198a242187ee8f737d3291ce55e8b6fd"
},
"downloads": -1,
"filename": "emunium-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "db4aa88cfb62577a3e6175c10f7ab412",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 7220,
"upload_time": "2024-06-08T07:13:33",
"upload_time_iso_8601": "2024-06-08T07:13:33.387469Z",
"url": "https://files.pythonhosted.org/packages/a7/85/52f5c3c25c0f0cb963c02d3e471739a2a901cb60d6463cbd4b1f9e67162e/emunium-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-08 07:13:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DedInc",
"github_project": "emunium",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "emunium"
}
