DOCSEARCHbyAlgolia
Submit Docs

HumanCursor Documentation

repository·main·Indexed 19 days ago

https://github.com/riflosnake/humancursor

A Python package (v1.1.5) designed to simulate realistic human-like mouse movements with variable speed, acceleration, and curvature to bypass bot detection. It includes WebCursor for Selenium-based web automation in Chrome and Edge, SystemCursor for system-wide control via pyautogui, and HCScripter for recording physical movements into Python scripts.

Tokens
1.1K
Snippets
6
Records
6
Agent score
17%

What's inside HumanCursor

  2. Use HCScripter to create automated scripts without coding

    main

    The HCScripter app allows you to record physical mouse movements and turn them into a Python script.

    1. Run the launcher via terminal/powershell: python -m humancursor.HCScripter.launch
    2. Specify the output filename and save location in the GUI.
    3. Turn on the movement listener using the ON/OFF button.
    4. Use key commands to record actions:
      • Z -> Move
      • CTRL -> Click
      • CTRL (press and hold) -> Drag and drop
    5. Press Finish to generate the .py script.
    python -m humancursor.HCScripter.launch

  3. Run HumanCursor demonstrations

    main

    You can run built-in tests to see how the cursor movement looks in real-time.

    System Cursor Demo: python -m humancursor.test.system

    Web Cursor Demo: python -m humancursor.test.web

    # System Demo
python -m humancursor.test.system

# Web Demo
python -m humancursor.test.web

  4. Use SystemCursor for system-wide mouse automation

    main

    The SystemCursor class is used for controlling the physical system mouse (powered by pyautogui).

    Unlike WebCursor, SystemCursor does not have access to web elements. It only supports methods that accept [x, y] coordinate lists as input. Supported methods include:

    • move_to()
    • click_on()
    • drag_and_drop()
    from humancursor import SystemCursor

cursor = SystemCursor()

  5. Use WebCursor for web automation

    main

    The WebCursor class is designed for web automation using Selenium. It is fully supported for Chrome and Edge.

    To use it, import WebCursor and instantiate it by passing a Selenium driver object. The methods can accept either a WebElement or a list of [x, y] coordinates.

    Key Parameters:

    • relative_position: A list of floats [x, y] from 0 to 1 representing the position within an element (e.g., [0.5, 0.5] for the center).
    • absolute_offset: If True, coordinate lists are interpreted as absolute pixel movements rather than webpage coordinates.
    • steady: If True, attempts to make movement in a straighter line while still mimicking human behavior.
    from humancursor import WebCursor

cursor = WebCursor(driver)

  6. WebCursor API Reference

    main

    Methods available on the WebCursor instance:

    • move_to(destination, relative_position=[...], absolute_offset=False, steady=False): Moves the cursor to a WebElement or [x, y] coordinates.
    • click_on(destination, relative_position=[...], click_duration=None): Clicks on a WebElement or [x, y] coordinates. click_duration allows holding the click for a specific number of seconds.
    • drag_and_drop(element1, element2, drag_from_relative_position=[...]): Drags from the first element/coordinate to the second.
    • move_by_offset(x, y): Moves the cursor by the specified pixel offsets.
    • control_scroll_bar(element, amount_by_percentage=..., orientation='vertical'|'horizontal'): Sets a slider or scroll bar to a specific level (0.0 to 1.0).
    • scroll_into_view_of_element(element): Automatically scrolls an element into view.
    • show_cursor(): Injects JavaScript to display a red dot over the cursor (use for visual testing only).
    # Example usage of WebCursor methods
cursor.move_to(element, relative_position=[0.5, 0.5])
cursor.move_to([450, 600], absolute_offset=True)
cursor.move_by_offset(200, 170)
cursor.click_on(element, click_duration=1.7)
cursor.drag_and_drop(element1, element2)
cursor.control_scroll_bar(element, amount_by_percentage=0.75)
cursor.scroll_into_view_of_element(element)