Ghost Cursor

https://github.com/xetera/ghost-cursor
Admin
Ghost Cursor generates realistic, human-like mouse movement data between coordinates or navigates...
Tokens:5,130
Snippets:35
Trust Score:9.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Ghost Cursor with NPM

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Use this command to add Ghost Cursor to your project dependencies using NPM.

```sh
npm install ghost-cursor
```

--------------------------------

### installMouseHelper

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Installs a mouse helper on the page, making the pointer visible. This is intended for debugging purposes and is automatically executed during Ghost Cursor initialization when `visible` is set to `true`.

```APIDOC
## installMouseHelper(page: Page): Promise<void>

### Description
Installs a mouse helper on the page, making the pointer visible. Gets executed in the `GhostCursor` initialization when passing `visible=true`. Use for debugging only.

### Parameters
#### Path Parameters
- **page** (Page) - Required - The page object to install the helper on.
```

--------------------------------

### Install Ghost Cursor with Yarn

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Use this command to add Ghost Cursor to your project dependencies using Yarn.

```sh
yarn add ghost-cursor
```

--------------------------------

### Puppeteer Integration with Ghost Cursor

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Demonstrates how to initialize and use GhostCursor with Puppeteer to automate browser interactions like clicking elements. Ensure both 'ghost-cursor' and 'puppeteer' are installed and imported.

```js
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)
  // shorthand for
  // await cursor.move(selector)
  // await cursor.click()
}
```

--------------------------------

### path

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Generates a sequence of points representing a mouse movement path between a start and end point, with optional configuration for path generation.

```APIDOC
## path(start: Vector, end: Vector | BoundingBox, options?: number | PathOptions): Vector[] | TimedVector[]

### Description
Generates a set of points for mouse movement between two coordinates.

### Parameters
#### Path Parameters
- **start** (Vector) - Required - Starting point of the movement.
- **end** (Vector | BoundingBox) - Required - Ending point (or bounding box) of the movement.
- **options** (number | PathOptions) - Optional - Additional options for generating the path. Can also be a number which will set `spreadOverride`.
  - `spreadOverride` (number) - Override the spread of the generated path.
  - `moveSpeed` (number) - Speed of mouse movement. Default is random.
  - `useTimestamps` (boolean) - Generate timestamps for each point based on the trapezoidal rule.
```

--------------------------------

### Generate Mouse Movement Path with Timestamps

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Generates a mouse movement path including timestamps for each coordinate, useful for more precise timing in simulations. Requires 'ghost-cursor' import.

```js
import { path } from "ghost-cursor"

const from = { x: 100, y: 100 }
const to = { x: 600, y: 700 }

const route = path(from, to, { useTimestamps: true })

/**
 * [
 *   { x: 100, y: 100, timestamp: 1711850430643 },
 *   { x: 114.78071695023473, y: 97.52340709495319, timestamp: 1711850430697 },
 *   { x: 129.1362373468682, y: 96.60141853603243, timestamp: 1711850430749 },
 *   { x: 143.09468422606352, y: 97.18676354029148, timestamp: 1711850430799 },
 *   { x: 156.68418062398405, y: 99.23217132478408, timestamp: 1711850430848 },
 *   ... and so on
 * ]
 */
```

--------------------------------

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

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Simulates a mouse click on a specified element or at a given selector.

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

### Description
Simulates a mouse click action. The cursor will move to the specified target (if provided) before performing the click. This method incorporates realistic mouse movement behaviors.

### Parameters
#### Method Parameters
- **selector** (string | ElementHandle) - Optional - A CSS selector or Puppeteer ElementHandle representing the target element to click.
- **options** (ClickOptions) - Optional - Additional options to customize the click behavior. These options extend those from `move`, `scrollIntoView`, and `getElement`.
  - **hesitate** (number) - Optional - Delay in milliseconds before the click action begins after moving. Defaults to `0`.
  - **waitForClick** (number) - Optional - Delay in milliseconds between the mousedown and mouseup events. Defaults to `0`.
  - **moveDelay** (number) - Optional - Delay in milliseconds after the mouse has finished moving before the click occurs. Defaults to `2000`. If `randomizeMoveDelay` is true, this value is randomized between 0 and `moveDelay`.
  - **button** (MouseButton) - Optional - The mouse button to use for the click (e.g., 'left', 'right', 'middle'). Defaults to `'left'`.
  - **clickCount** (number) - Optional - The number of times the button should be clicked. Defaults to `1`.
```

--------------------------------

### mouseDown / mouseUp

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Simulates a mouse button press (mouseDown) or release (mouseUp). Options allow specifying the button and click count.

```APIDOC
## mouseDown / mouseUp(options?: MouseButtonOptions): Promise<void>

### Description
Mouse button up or down.

### Method
```javascript
mouseDown, mouseUp
```

### Parameters
#### Query Parameters
- **options** (MouseButtonOptions) - Optional - Additional options for mouse action.
  - **button** (MouseButton) - Optional - Mouse button to click. Default is `left`.
  - **clickCount** (number) - Optional - Number of times to click the button. Default is `1`.

### Response
#### Success Response (void)
Indicates the mouse button action was completed.

### Request Example
```json
{
  "options": {
    "button": "right",
    "clickCount": 2
  }
}
```
```

--------------------------------

### Generate Mouse Movement Path

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Generates an array of coordinates representing a realistic mouse movement path between two points. Ensure 'ghost-cursor' is imported.

```js
import { path } from "ghost-cursor"

const from = { x: 100, y: 100 }
const to = { x: 600, y: 700 }

const route = path(from, to)

/**
 * [
 *   { x: 100, y: 100 },
 *   { x: 108.75573501957051, y: 102.83608396351725 },
 *   { x: 117.54686481838543, y: 106.20019239793275 },
 *   { x: 126.3749821408895, y: 110.08364505509256 },
 *   { x: 135.24167973152743, y: 114.47776168684264 }
 *   ... and so on
 * ]
 */
```

--------------------------------

### moveTo

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Moves the mouse cursor to a specific point defined by x and y coordinates. Options include controlling movement speed and delays.

```APIDOC
## moveTo(destination: Vector, options?: MoveToOptions): Promise<void>

### Description
Moves the mouse to the specified destination point.

### Method
```javascript
moveTo
```

### Parameters
#### Path Parameters
- **destination** (Vector) - Required - An object with `x` and `y` coordinates representing the target position. For example, `{ x: 500, y: 300 }`.

#### Query Parameters
- **options** (MoveToOptions) - Optional - Additional options for moving.
  - **moveSpeed** (number) - Optional - Speed of mouse movement. Default is random.
  - **moveDelay** (number) - Optional - Delay after moving the mouse in milliseconds. Default is `0`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
  - **randomizeMoveDelay** (boolean) - Optional - Randomize delay between actions from `0` to `moveDelay`. Default is `true`.

### Response
#### Success Response (void)
Indicates the mouse movement to the destination was completed successfully.

### Request Example
```json
{
  "destination": {
    "x": 500,
    "y": 300
  },
  "options": {
    "moveSpeed": 100
  }
}
```
```

--------------------------------

### getElement

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Retrieves an element from the DOM using a CSS selector or XPath. It includes an option to wait for the selector to appear.

```APIDOC
## getElement(selector: string | ElementHandle, options?: GetElementOptions): Promise<void>

### Description
Gets the element via a selector. Can use an XPath.

### Method
```javascript
getElement
```

### Parameters
#### Path Parameters
- **selector** (string | ElementHandle) - Required - CSS selector or ElementHandle to identify the target element.

#### Query Parameters
- **options** (GetElementOptions) - Optional - Additional options.
  - **waitForSelector** (number) - Optional - Time to wait for the selector to appear in milliseconds. Default is to not wait for selector.

### Response
#### Success Response (void)
Indicates the element was successfully retrieved.

### Request Example
```json
{
  "selector": "#unique-id",
  "options": {
    "waitForSelector": 5000
  }
}
```
```

--------------------------------

### moveBy

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Moves the mouse cursor by a specified amount (delta) in x and y directions. It shares the same options as the `moveTo` method for controlling speed and delays.

```APIDOC
## moveBy(delta: Vector, options?: MoveToOptions): Promise<void>

### Description
Moves the mouse by a specified amount.

### Method
```javascript
moveBy
```

### Parameters
#### Path Parameters
- **delta** (Vector) - Required - An object with `x` and `y` coordinates representing the distance to move. For example, `{ x: 10, y: 20 }`.

#### Query Parameters
- **options** (MoveToOptions) - Optional - Additional options for moving. Same as `moveTo` options.

### Response
#### Success Response (void)
Indicates the mouse movement by the specified delta was completed successfully.

### Request Example
```json
{
  "delta": {
    "x": 10,
    "y": 20
  },
  "options": {
    "moveDelay": 100
  }
}
```
```

--------------------------------

### Define Box Styling with CSS

Source: https://github.com/xetera/ghost-cursor/blob/master/src/__debug__/custom-page.html

This CSS defines the appearance and behavior of a box element, including its background, transition effects, dimensions, and positioning.

```css
.box { background: #eee; transition: all 0.4s; width: 50px; height: 50px; position: absolute; }
```

--------------------------------

### getRandomPagePoint

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Retrieves a random point within the bounds of the browser window.

```APIDOC
## getRandomPagePoint(page: Page): Promise<Vector>

### Description
Gets a random point on the browser window.

### Parameters
#### Path Parameters
- **page** (Page) - Required - The page object to get a random point from.
```

--------------------------------

### move

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Moves the mouse to a specified CSS selector or ElementHandle. It supports various options for controlling the movement, including padding, destination, delays, and speed.

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

### Description
Moves the mouse to the specified selector or element.

### Method
```javascript
move
```

### Parameters
#### Path Parameters
- **selector** (string | ElementHandle) - Required - CSS selector or ElementHandle to identify the target element.

#### Query Parameters
- **options** (MoveOptions) - Optional - Additional options for moving. Extends the `options` of the `scrollIntoView` and `getElement` functions.
  - **paddingPercentage** (number) - Optional - Percentage of padding to be added inside the element when determining the target point. Default is `0`. `100` will always move to center of element.
  - **destination** (Vector) - Optional - Destination to move the cursor to, relative to the top-left corner of the element. If specified, `paddingPercentage` is not used. If not specified (default), destination is random point within the `paddingPercentage`.
  - **moveDelay** (number) - Optional - Delay after moving the mouse in milliseconds. Default is `0`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
  - **randomizeMoveDelay** (boolean) - Optional - Randomize delay between actions from `0` to `moveDelay`. Default is `true`.
  - **maxTries** (number) - Optional - Maximum number of attempts to mouse-over the element. Default is `10`.
  - **moveSpeed** (number) - Optional - Speed of mouse movement. Default is random.
  - **overshootThreshold** (number) - Optional - Distance from current location to destination that triggers overshoot to occur. (Below this distance, no overshoot will occur). Default is `500`.

### Response
#### Success Response (void)
Indicates the mouse movement was completed successfully.

### Request Example
```json
{
  "selector": ".my-element",
  "options": {
    "paddingPercentage": 100,
    "moveDelay": 500,
    "randomizeMoveDelay": false
  }
}
```
```

--------------------------------

### toggleRandomMove(random: boolean): void

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Toggles the random mouse movement behavior on or off for the GhostCursor instance.

```APIDOC
## toggleRandomMove(random: boolean): void

### Description
Enables or disables the random mouse movement feature for the GhostCursor. When enabled, the cursor will exhibit more unpredictable movements.

### Parameters
#### Method Parameters
- **random** (boolean) - Required - Set to `true` to enable random movements, `false` to disable.
```

--------------------------------

### scrollIntoView

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Ensures a specified element is within the viewport by scrolling if necessary. Options control scroll speed, delay, and viewport margins.

```APIDOC
## scrollIntoView(selector: string | ElementHandle, options?: ScrollIntoViewOptions): Promise<void>

### Description
Scrolls the element into view. If already in view, no scroll occurs.

### Method
```javascript
scrollIntoView
```

### Parameters
#### Path Parameters
- **selector** (string | ElementHandle) - Required - CSS selector or ElementHandle to identify the target element.

#### Query Parameters
- **options** (ScrollIntoViewOptions) - Optional - Additional options for scrolling. Extends the `options` of the `getElement` and `scroll` functions.
  - **scrollSpeed** (number) - Optional - Scroll speed (when scrolling occurs). 0 to 100. 100 is instant. Default is `100`.
  - **scrollDelay** (number) - Optional - Time to wait after scrolling (when scrolling occurs). Default is `200`.
  - **inViewportMargin** (number) - Optional - Margin (in px) to add around the element when ensuring it is in the viewport. Default is `0`.

### Response
#### Success Response (void)
Indicates the element has been scrolled into view.

### Request Example
```json
{
  "selector": "#my-section",
  "options": {
    "scrollSpeed": 50,
    "inViewportMargin": 20
  }
}
```
```

--------------------------------

### getLocation

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Returns the current coordinates (x, y) of the mouse cursor.

```APIDOC
## getLocation(): Vector

### Description
Get current location of the cursor.

### Method
```javascript
getLocation
```

### Response
#### Success Response (Vector)
- **x** (number) - The x-coordinate of the cursor.
- **y** (number) - The y-coordinate of the cursor.

### Response Example
```json
{
  "x": 123,
  "y": 456
}
```
```

--------------------------------

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

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Initializes a new GhostCursor instance, which controls mouse interactions within a Puppeteer page.

```APIDOC
## new GhostCursor(page: puppeteer.Page, options?: GhostCursorOptions): GhostCursor

### Description
Creates a new GhostCursor instance to manage simulated mouse actions on a Puppeteer page. This includes methods for moving, clicking, and simulating human-like cursor behavior.

### Parameters
#### Constructor Parameters
- **page** (puppeteer.Page) - Required - The Puppeteer page object to interact with.
- **options** (GhostCursorOptions) - Optional - Configuration options for the GhostCursor instance.
  - **start** (Vector) - Optional - The initial position of the cursor. Defaults to `{ x: 0, y: 0 }`.
  - **performRandomMoves** (boolean) - Optional - Whether to perform random movements on initialization. Defaults to `false`.
  - **defaultOptions** (DefaultOptions) - Optional - Default options to apply to subsequent actions like `click`, `move`, etc.
  - **visible** (boolean) - Optional - Whether to make the cursor visible using `installMouseHelper()`. Defaults to `false`.
```

--------------------------------

### Track Box Clicks

Source: https://github.com/xetera/ghost-cursor/blob/master/src/__test__/custom-page.html

Adds an event listener to a box element to track if it has been clicked.

```javascript
window.boxWasClicked = false
box.addEventListener('click', () => {
  window.boxWasClicked = true
})
```

--------------------------------

### scrollTo

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Scrolls the page to a specific destination point (x, y coordinates) or to predefined positions like 'top' or 'bottom'. Options can be passed to control scroll behavior.

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

### Description
Scrolls to the specified destination point.

### Method
```javascript
scrollTo
```

### Parameters
#### Path Parameters
- **destination** (Partial<Vector> | 'top' | 'bottom' | 'left' | 'right') - Required - An object with `x` and `y` coordinates representing the target position. For example, `{ x: 500, y: 300 }`. Can also be a string: `'top'`, `'bottom'`, `'left'`, or `'right'`.

#### Query Parameters
- **options** (ScrollOptions) - Optional - Additional options for scrolling. Extends the `options` of the `scroll` function.

### Response
#### Success Response (void)
Indicates the page has been scrolled to the specified destination.

### Request Example
```json
{
  "destination": {
    "x": 1000,
    "y": 500
  },
  "options": {
    "scrollSpeed": 80
  }
}
```
```

--------------------------------

### path(from: Vector, to: Vector, options?: { useTimestamps: boolean }): Vector[]

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Generates an array of coordinates representing a path between two points. Optionally includes timestamps for each point.

```APIDOC
## path(from: Vector, to: Vector, options?: { useTimestamps: boolean }): Vector[]

### Description
Generates an array of coordinates representing a path between two points. This function can simulate realistic mouse movements.

### Parameters
#### Path Parameters
- **from** (Vector) - Required - The starting coordinate { x: number, y: number }.
- **to** (Vector) - Required - The ending coordinate { x: number, y: number }.
- **options** (object) - Optional - Configuration for path generation.
  - **useTimestamps** (boolean) - Optional - If true, each point in the returned array will include a `timestamp` property.

### Returns
- **Vector[]** - An array of coordinate objects, potentially with timestamps, representing the generated path.
```

--------------------------------

### scroll

Source: https://github.com/xetera/ghost-cursor/blob/master/README.md

Scrolls the page by a specified distance (delta) in x and y directions. Options control scroll speed and delay.

```APIDOC
## scroll(delta: Partial<Vector>, options?: ScrollOptions): Promise<void>

### Description
Scrolls the page the distance set by `delta`.

### Method
```javascript
scroll
```

### Parameters
#### Path Parameters
- **delta** (Partial<Vector>) - Required - An object with `x` and `y` coordinates representing the distance to scroll from the current position.

#### Query Parameters
- **options** (ScrollOptions) - Optional - Additional options for scrolling.
  - **scrollSpeed** (number) - Optional - Scroll speed. 0 to 100. 100 is instant. Default is `100`.
  - **scrollDelay** (number) - Optional - Time to wait after scrolling. Default is `200`.

### Response
#### Success Response (void)
Indicates the page has been scrolled by the specified delta.

### Request Example
```json
{
  "delta": {
    "x": 0,
    "y": 100
  },
  "options": {
    "scrollDelay": 300
  }
}
```
```

--------------------------------

### Animate Box Position

Source: https://github.com/xetera/ghost-cursor/blob/master/src/__test__/custom-page.html

Uses JavaScript to randomly change the 'left' and 'top' CSS properties of a box element at intervals.

```javascript
const box = document.querySelector('#box1')
setTimeout(() => {
  box.style.left = Math.random() * 500
}, 1000)
setTimeout(() => {
  box.style.top = Math.random() * 500
}, 1000)
```
Tokens:
Raw