ghost-cursor

GhostCursor uses Bezier curves to create smooth, non-linear paths between points. To avoid the 'wonky' look of standard cubic curves, it picks random control points on only one side of the line.

Additionally, it uses Fitts's Law to calculate mouse speed and the density of points in the path, adjusting based on the distance to the target and the size of the element being interacted with.

You can install ghost-cursor using npm or yarn.

yarn add ghost-cursor
# or
npm install ghost-cursor

To simulate human-like interactions in Puppeteer, instantiate a GhostCursor by passing a Puppeteer page object. This allows you to use high-level methods like click and move that simulate realistic mouse behavior (overshooting, random target selection within elements, and variable speeds).

import { GhostCursor } from "ghost-cursor"
import puppeteer from "puppeteer"

const run = async (url) => {
  const selector = "#sign-up button"
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage()
  const cursor = new GhostCursor(page)
  await page.goto(url)
  await page.waitForSelector(selector)
  await cursor.click(selector)
}

When performRandomMoves: true is passed to the GhostCursor constructor, the library starts a recursive loop that picks random points on the page and moves the cursor to them. This simulates idle human activity.

These random movements are automatically paused when you call explicit actions like move(), click(), or moveTo(), and resumed once those actions (and their associated delays) are complete. You can manually control this behavior using toggleRandomMove(boolean).

To see internal logs, set the DEBUG environment variable to ghost-cursor:*.

Commands:

• OSX/Linux: DEBUG="ghost-cursor:*"
• Windows CMD: set DEBUG=ghost-cursor:*
• Windows PowerShell: $env:DEBUG = "ghost-cursor:*"

Moves the mouse to a specific { x, y } coordinate.

Signature: moveTo(destination: Vector, options?: MoveToOptions): Promise<void>

Options:

• moveSpeed (number): Speed of movement. Default is random.
• moveDelay (number): Delay after moving in ms. Default 0.
• randomizeMoveDelay (boolean): Randomize delay between 0 and moveDelay. Default true.

Moves the mouse by a relative amount.

Signature: moveBy(delta: Vector, options?: MoveToOptions): Promise<void>

Options:

• moveSpeed (number): Speed of movement. Default is random.
• moveDelay (number): Delay after moving in ms. Default 0.
• randomizeMoveDelay (boolean): Randomize delay between 0 and moveDelay. Default true.

Moves the mouse to a specified selector or element with realistic movement.

Signature: move(selector: string | ElementHandle, options?: MoveOptions): Promise<void>

Options:

• paddingPercentage (number): Percentage of padding inside the element for target selection. 100 moves to the center. Default 0.
• destination (Vector): Target point relative to the top-left of the element. If specified, paddingPercentage is ignored.
• moveDelay (number): Delay after moving in ms. Default 0.
• randomizeMoveDelay (boolean): Randomize delay between 0 and moveDelay. Default true.
• maxTries (number): Max attempts to mouse-over the element. Default 10.
• moveSpeed (number): Speed of movement. Default is random.
• overshootThreshold (number): Distance that triggers an overshoot/re-adjustment. Default 500.

The GhostCursor constructor creates a cursor instance capable of performing human-like actions on a Puppeteer page.

Signature: new GhostCursor(page: puppeteer.Page, options?: GhostCursorOptions): GhostCursor

Options:

• start (optional): Cursor start position. Default is { x: 0, y: 0 }.
• performRandomMoves (optional): Whether to initially perform random movements. Default is false.
• defaultOptions (optional): Set custom default options for click, move, moveTo, and randomMove functions.
• visible (optional): If true, makes the cursor visible using installMouseHelper(). Default is false.

Provides methods to manage page scrolling.

Scroll into view: scrollIntoView(selector: string | ElementHandle, options?: ScrollIntoViewOptions): Promise<void>

• scrollSpeed (number): 0 to 100 (100 is instant). Default 100.
• scrollDelay (number): Wait time after scrolling in ms. Default 200.
• inViewportMargin (number): Margin in px around the element. Default 0.

Scroll to destination: scrollTo(destination: Partial<Vector> | 'top' | 'bottom' | 'left' | 'right', options?: ScrollOptions): Promise<void>

Scroll by delta: scroll(delta: Partial<Vector>, options?: ScrollOptions): Promise<void>

• scrollSpeed (number): 0 to 100. Default 100.
• scrollDelay (number): Wait time after scrolling in ms. Default 200.

Simulates a mouse click at a specified selector or element.

Signature: click(selector?: string | ElementHandle, options?: ClickOptions): Promise<void>

Options:

• hesitate (number): Delay before initiating the click in ms. Default 0.
• waitForClick (number): Delay between mousedown and mouseup in ms. Default 0.
• moveDelay (number): Delay after moving the mouse in ms. Default 2000. If randomizeMoveDelay=true, delay is randomized from 0 to moveDelay.
• button (MouseButton): Mouse button to click. Default left.
• clickCount (number): Number of times to click. Default 1.

Use the path function to generate a sequence of coordinates representing human-like mouse movement between two points. You can optionally include timestamps for each point.

Arguments:

• start: Starting Vector { x, y }.
• end: Ending Vector { x, y } or BoundingBox.
• options (optional): Configuration object.
  • useTimestamps (boolean): If true, returns TimedVector[] instead of Vector[].
  • moveSpeed (number): Speed of movement (default is random).
  • spreadOverride (number): Override the spread of the generated path.