Awesome
HumanCursor: A Python package for simulating human mouse movements
<div style="display:flex;flex-direction:row;"> <img src="https://user-images.githubusercontent.com/108073687/234356166-719efddc-4618-4d32-b40e-2055d17b3edd.jpg" width="40%" height="300"> <img src="https://media.giphy.com/media/D2D9BfjscHEG1DzBKu/giphy.gif" width="45%" height="300"> </div>HumanCursor is a Python package that allows you to simulate realistic human mouse movements on the web and the system. It can be used for automating scripts that require mouse interactions, such as web scraping, automated tasks, testing, or gaming.
Content:
Features
- HumanCursor uses a
natural motion algorithm
that mimics the wayhumans
move the mouse cursor, withvariable speed
,acceleration
, andcurvature
. - Can perform various mouse actions, such as
clicking
,dragging
,scrolling
, andhovering
. - Designed specifically to
bypass security measures and bot detection software
. - Includes:
- 🚀
HCScripter
app to create physical cursor automated scripts without coding. - 🌐
WebCursor
module for web cursor code automation.- Fully supported for
Chrome
andEdge
, not optimal/tested for Firefox and Safari, usingSelenium
.
- Fully supported for
- 🤖
SystemCursor
module for physical cursor code automation.
- 🚀
Requirements
Python >= 3.7
- Download the installer, run it and follow the steps.
- Make sure to check the box that says
Add Python to PATH
during installation. - Reboot computer.
Installation
To install, you can use pip:
pip install --upgrade humancursor
Usage
HCScripter
To quickly create an automated system script, you can use HCScripter
, which registers mouse actions from point to point using key commands and creates a script file for you.
After installing humancursor
package, open up terminal/powershell
and just copy paste this command which runs launch.py
file inside the folder named HCScripter
of humancursor
package:
python -m humancursor.HCScripter.launch
A window will show up looking like this:
<img width="270" alt="Screenshot 2023-11-29 165810" src="https://github.com/riflosnake/HumanCursor/assets/108073687/bc162443-1390-44fd-9dd9-69a8e0a9953b">Firstly, you can specify the name
of the python file which will contain the script and choose the location
where that file should be saved.
Then, you can turn on movement listener by pressing the ON/OFF
button, where it will start registering your movements, by these commands below:
- Press
Z
->Move
- Press
CTRL
->Click
- Press and hold
CTRL
->Drag and drop
After completing your script, press Finish
button and the script file .py should be ready to go!
WebCursor
To use HumanCursor for Web, you need to import the WebCursor
class, and create an instance:
from humancursor import WebCursor
cursor = WebCursor(driver)
Then, you can use the following methods to simulate mouse movements and actions:
cursor.move_to()
: Moves the mouse cursor to the element or location on the webpage.cursor.click_on()
: Clicks on the element or location on the webpage.cursor.drag_and_drop()
: Drags the mouse cursor from one element and drops it to another element on the screen.cursor.move_by_offset()
: Moves the cursor by x and y pixels.cursor.control_scroll_bar()
: Sets the scroll bar to a certain level, can be a volume, playback slider or anything. Level is set by float number from 0 to 1, meaning fullnesscursor.scroll_into_view_of_element()
: Scrolls into view of element if not already there, it is called automatically from above functions.
These functions can accept as destination, either the WebElement
itself, or a list of 'x' and 'y' coordinates
.
Some parameters explained:
relative_position
: Takes a list of x and y percentages as floats from 0 to 1, which indicate the exact position by width and height inside an element for example, if you set it to [0.5, 0.5], it will move the cursor to the center of the element.absolute_offset
: If you input a list of coordinates instead of webelement, if you turn this to True, the coordinates will be interpreted as absolute movement by pixels, and not like coordinates in the webpage.steady
: Tries to make movement in straight line, mimicking human, if set to True
SystemCursor
<div style="display:flex;flex-direction:row;"> <img src="https://media.giphy.com/media/U9Y3uFwjVlCzoB4HJX/giphy.gif" width="30%" height="280"> <img src="https://media.giphy.com/media/D7geMT10Eatk2X2DUF/giphy.gif" width="30%" height="280"> <img src="https://media.giphy.com/media/J3DyvU4raVEGvFiDjg/giphy.gif" width="30%" height="280"> </div> To use HumanCursor for your system mouse, you need to import the `SystemCursor` class, and create an instance just like we did above:from humancursor import SystemCursor
cursor = SystemCursor()
The SystemCursor
class, which should be used for controlling the system mouse (with pyautogui), only inherits the move_to()
, click_on()
and drag_and_drop
functions, accepting only the list of 'x' and 'y' coordinates as input, as there are no elements available.
DEMONSTRATION:
To quickly check how the cursor moves, you can do this:
SystemCursor
python -m humancursor.test.system
WebCursor
python -m humancursor.test.web
Some code examples:
cursor.move_to(element) # moves to element
cursor.move_to(element, relative_position=[0.5, 0.5]) # moves to the center of the element
cursor.move_to([450, 600]) # moves to coordinates relative to viewport x: 450, y: 600
cursor.move_to([450, 600], absolute_offset=True) # moves 450 pixels to the right and 600 pixels down
cursor.move_by_offset(200, 170) # moves 200 pixels to the right and 170 pixels down
cursor.move_by_offset(-10, -20) # moves 10 pixels to the left and 20 pixels up
cursor.click_on([170, 390]) # clicks on coordinates relative to viewport x: 170, y: 390
cursor.click_on(element, relative_position=[0.2, 0.5]) # clicks on 0.2 x width, 0.5 x height position of the element.
cursor.click_on(element, click_duration=1.7) # clicks and holds on element for 1.7 seconds
cursor.drag_and_drop(element1, element2) # clicks and hold on first element, and moves to and releases on the second
cursor.drag_and_drop(element, [640, 320], drag_from_relative_position=[0.9, 0.9]) # drags from element on 0.9 x width, 0.9 x height (far bottom right corner) and moves to and releases to coordinates relative to viewport x: 640, y: 320
cursor.control_scroll_bar(element, amount_by_percentage=0.75) # sets a slider to 75% full
cursor.controll_scroll_bar(element, amount_by_percentage=0.2, orientation='vertical') # sets a vertical slider to 20% full
cursor.scroll_into_view_of_element(element) # scrolls into view of element if not already in it
cursor.show_cursor() # injects javascript that will display a red dot over the cursor on webpage. Should be called only for visual testing before script and not actual work.
License
HumanCursor is licensed under the MIT License. See LICENSE for more information.