humanize

Documentation

Overview

Package humanize provides human-like browser interactions including typing, scrolling, mouse movement, and element actions.

Key features:

• Typing with realistic delays and optional typos
• Physics-based scrolling with cubic bezier easing
• Mouse movement with bezier curves and natural speed variation
• Element actions (hover, drag-and-drop, file upload)

Example usage:

// Type with humanization
err := humanize.TypeWithHumanize(element, "hello world",
    humanize.WithTypoRate(0.02),
    humanize.WithTypingSpeed(30, 120))

// Scroll with physics
err := humanize.ScrollToBottom(page,
    humanize.WithPhysics(),
    humanize.WithDuration(500))

// Move mouse naturally
err := humanize.MoveTo(page, element,
    humanize.WithMouseSpeed(50, 150))

Index

• func ApplyDefaults(config *TypingConfig)
• func ApplyMouseDefaults(config *MouseMovementConfig)
• func ApplyScrollDefaults(config *ScrollConfig)
• func ClickWithMouse(page *rod.Page, el *rod.Element) error
• func CubicBezier(t float64) float64
• func DragAndDrop(page *rod.Page, source, target *rod.Element) error
• func GenerateControlPoints(start, end Point, deviation float64) (Point, Point)
• func Hover(el *rod.Element) error
• func MoveTo(page *rod.Page, el *rod.Element, opts ...MouseOption) error
• func ScrollBy(page *rod.Page, direction ScrollDirection, amount int, opts ...ScrollOption) error
• func ScrollToBottom(page *rod.Page, opts ...ScrollOption) error
• func SimulateTypingDelay(min, max int)
• func TypeWithHumanize(el *rod.Element, text string, opts ...TypingOption) error
• func UploadFile(fileInput *rod.Element, filepath string) error
• type MouseMovementConfig
• type MouseOption
  • func WithMouseDeviation(deviation float64) MouseOption
  • func WithMouseSpeed(min, max int) MouseOption
• type Point
  • func CalculatePath(start, end Point, steps int) []Point
  • func CalculatePathWithConfig(start, end Point, steps int, config *MouseMovementConfig) []Point
  • func CubicBezierPoint(p0, p1, p2, p3 Point, t float64) Point
• type ScrollConfig
• type ScrollDirection
• type ScrollOption
  • func WithDuration(duration int) ScrollOption
  • func WithPhysics() ScrollOption
• type TypingConfig
• type TypingOption
  • func WithTypingSpeed(min, max int) TypingOption
  • func WithTypoRate(rate float32) TypingOption

Functions

func ApplyDefaults

func ApplyDefaults(config *TypingConfig)

ApplyDefaults sets default values for TypingConfig

func ApplyMouseDefaults

func ApplyMouseDefaults(config *MouseMovementConfig)

ApplyMouseDefaults sets default values for MouseMovementConfig

func ApplyScrollDefaults

func ApplyScrollDefaults(config *ScrollConfig)

ApplyScrollDefaults sets default values for ScrollConfig

func ClickWithMouse

func ClickWithMouse(page *rod.Page, el *rod.Element) error

ClickWithMouse clicks an element with human-like mouse movement

func CubicBezier

func CubicBezier(t float64) float64

CubicBezier implements cubic bezier easing function Uses (0.25, 0.1, 0.25, 1.0) control points for natural motion

func DragAndDrop

func DragAndDrop(page *rod.Page, source, target *rod.Element) error

DragAndDrop drags one element to another with human-like movement

func GenerateControlPoints

func GenerateControlPoints(start, end Point, deviation float64) (Point, Point)

GenerateControlPoints creates two random control points for cubic bezier curve deviation controls how far control points can be from the straight line (0.0-1.0)

func Hover

func Hover(el *rod.Element) error

Hover hovers over an element with human-like mouse movement

func MoveTo

func MoveTo(page *rod.Page, el *rod.Element, opts ...MouseOption) error

MoveTo moves the mouse to a target element with human-like movement

func ScrollBy

func ScrollBy(page *rod.Page, direction ScrollDirection, amount int, opts ...ScrollOption) error

ScrollBy scrolls the page by the specified amount of pixels

func ScrollToBottom

func ScrollToBottom(page *rod.Page, opts ...ScrollOption) error

ScrollToBottom scrolls to the bottom of the page

func SimulateTypingDelay

func SimulateTypingDelay(min, max int)

SimulateTypingDelay simulates realistic typing delay

func TypeWithHumanize

func TypeWithHumanize(el *rod.Element, text string, opts ...TypingOption) error

TypeWithHumanize types text into an element with human-like timing and optional typos.

Usage:

err := humanize.TypeWithHumanize(element, "hello world")
err := humanize.TypeWithHumanize(element, "test",
    humanize.WithTypoRate(0.02),
    humanize.WithTypingSpeed(30, 120))

func UploadFile

func UploadFile(fileInput *rod.Element, filepath string) error

UploadFile uploads a file to an input element

Types

type MouseMovementConfig

type MouseMovementConfig struct {
	MinSpeed  int     // pixels per second (min)
	MaxSpeed  int     // pixels per second (max)
	UseCurves bool    // use bezier curves for natural paths
	Deviation float64 // randomness in path (0.0-1.0)
}

MouseMovementConfig holds configuration for mouse movement

type MouseOption

type MouseOption func(*MouseMovementConfig)

MouseOption is a function that configures MouseMovementConfig

func WithMouseDeviation

func WithMouseDeviation(deviation float64) MouseOption

WithMouseDeviation sets the path deviation (0.0-1.0)

func WithMouseSpeed

func WithMouseSpeed(min, max int) MouseOption

WithMouseSpeed sets the mouse speed range (min and max pixels per second)

type Point

type Point struct {
	X, Y float64
}

Mouse movement with cubic bezier curves for natural-looking paths.

The mouse movement uses cubic bezier curves with random control points to create natural, human-like mouse paths. The bezier formula is:

B(t) = (1-t)³·P₀ + 3·(1-t)²·t·P₁ + 3·(1-t)·t²·P₂ + t³·P₃

Where:

• P₀ is the start point (current mouse position)
• P₃ is the end point (target element center)
• P₁, P₂ are control points randomly generated based on deviation

Control points are generated perpendicular to the direct path with random offsets, creating variety in mouse movements while still reaching the target accurately.

Example:

// Move with high deviation (more curved paths)
err := humanize.MoveTo(page, element, humanize.WithMouseDeviation(0.5))

// Move with low deviation (gentle curves)
err := humanize.MoveTo(page, element, humanize.WithMouseDeviation(0.1))

// Move in straight line (no curves)
err := humanize.MoveTo(page, element, humanize.WithMouseDeviation(0.0))

Point represents a 2D coordinate

func CalculatePath

func CalculatePath(start, end Point, steps int) []Point

CalculatePath calculates a bezier curve path from start to end with default config

func CalculatePathWithConfig

func CalculatePathWithConfig(start, end Point, steps int, config *MouseMovementConfig) []Point

CalculatePathWithConfig calculates a path from start to end using bezier curves. If config is nil, uses default configuration. Panics if config.Deviation is not in range [0.0, 1.0].

func CubicBezierPoint

func CubicBezierPoint(p0, p1, p2, p3 Point, t float64) Point

CubicBezierPoint calculates a point on a cubic bezier curve at parameter t (0 to 1) Formula: B(t) = (1-t)³·P₀ + 3·(1-t)²·t·P₁ + 3·(1-t)·t²·P₂ + t³·P₃

type ScrollConfig

type ScrollConfig struct {
	// UsePhysics enables cubic bezier easing for smooth motion
	UsePhysics bool
	// ScrollDuration is the base duration for scroll animation (milliseconds)
	ScrollDuration int
}

ScrollConfig holds configuration for humanized scrolling

type ScrollDirection

type ScrollDirection int

ScrollDirection represents scroll direction

const (
	ScrollUp ScrollDirection = iota
	ScrollDown
	ScrollLeft
	ScrollRight
)

type ScrollOption

type ScrollOption func(*ScrollConfig)

ScrollOption is a function that configures ScrollConfig

func WithDuration

func WithDuration(duration int) ScrollOption

WithDuration sets the scroll duration

func WithPhysics

func WithPhysics() ScrollOption

WithPhysics enables physics-based scrolling (cubic bezier easing)

type TypingConfig

type TypingConfig struct {
	// TypoRate is the probability (0.0-1.0) of making a typo
	TypoRate float32
	// MinTypingDelay is the minimum delay between keystrokes (milliseconds)
	MinTypingDelay int
	// MaxTypingDelay is the maximum delay between keystrokes (milliseconds)
	MaxTypingDelay int
}

TypingConfig holds configuration for humanized typing

type TypingOption

type TypingOption func(*TypingConfig)

TypingOption is a function that configures TypingConfig

func WithTypingSpeed

func WithTypingSpeed(min, max int) TypingOption

WithTypingSpeed sets the typing speed range (min and max delay in milliseconds)

func WithTypoRate

func WithTypoRate(rate float32) TypingOption

WithTypoRate sets the typo rate