robotio

Modern Rust library for cross-platform desktop automation. This package provides high-performance mouse automation capabilities for Node.js applications.

Features

• 🖱️ Cross-platform mouse control - Windows, macOS, and Linux support
• ⚡ High performance - Native Rust implementation with NAPI-RS bindings
• 🔒 Memory safe - Built with Rust's memory safety guarantees
• 📦 Prebuilt binaries - No compilation required for common platforms
• 🎯 Precise control - Sub-pixel accuracy for mouse positioning
• 🎲 Comprehensive API - Movement, clicking, scrolling, and position reading

Supported Platforms

| Platform | Architecture | Status | |----------|--------------|--------| | macOS | x64, ARM64 | ✅ Full support | | Windows | x64, x86, ARM64 | ✅ Full support | | Linux | x64, ARM64, ARMv7 | ✅ Full support | | Linux (musl) | x64, ARM64 | ✅ Full support | | FreeBSD | x64 | ✅ Full support |

Installation

npm install robotio

yarn add robotio

pnpm add robotio

Quick Start

import { Mouse, MouseButton } from 'robotio';

// Create a mouse instance
const mouse = new Mouse();

// Get current mouse position
const position = mouse.getPosition();
console.log(`Mouse is at (${position.x}, ${position.y})`);

// Move mouse to a specific position
await mouse.moveTo({ x: 100, y: 200 });

// Click the left mouse button
await mouse.click(MouseButton.Left);

// Right-click
await mouse.click(MouseButton.Right);

// Double-click
await mouse.doubleClick(MouseButton.Left);

// Press and release
await mouse.press(MouseButton.Left);
await new Promise(resolve => setTimeout(resolve, 100));
await mouse.release(MouseButton.Left);

// Scroll
await mouse.scroll(1, 3); // Scroll up 3 notches
await mouse.scroll(-1, 3); // Scroll down 3 notches

// Set delay between operations
mouse.setDelay(50); // 50ms delay

API Reference

Mouse Class

Constructor

const mouse = new Mouse();

Methods

getPosition(): Point

Get the current mouse cursor position.

Returns: Point - Object with x and y coordinates

moveTo(point: Point): Promise<void>

Move the mouse cursor to the specified position.

Parameters:

• point: Point - Target position with x and y coordinates

click(button: MouseButton): Promise<void>

Perform a single click with the specified mouse button.

Parameters:

• button: MouseButton - The mouse button to click

doubleClick(button: MouseButton): Promise<void>

Perform a double-click with the specified mouse button.

Parameters:

• button: MouseButton - The mouse button to double-click

press(button: MouseButton): Promise<void>

Press and hold the specified mouse button.

Parameters:

• button: MouseButton - The mouse button to press

release(button: MouseButton): Promise<void>

Release the specified mouse button.

Parameters:

• button: MouseButton - The mouse button to release

scroll(direction: number, clicks: number): Promise<void>

Scroll the mouse wheel.

Parameters:

• direction: number - Scroll direction (1 for up, -1 for down)
• clicks: number - Number of scroll clicks

setDelay(ms: number): void

Set the delay between mouse operations.

Parameters:

• ms: number - Delay in milliseconds

getDelay(): number

Get the current delay between mouse operations.

Returns: number - Current delay in milliseconds

Types

Point

interface Point {
  x: number;
  y: number;
}

MouseButton

enum MouseButton {
  Left = 1,
  Right = 2,
  Middle = 3
}

Platform-Specific Notes

Windows

• Uses Win32 API (SendInput, SetCursorPos, GetCursorPos)
• May require administrator privileges for some applications
• UAC settings can affect input simulation

macOS

• Uses CoreGraphics framework
• Requires Accessibility permissions in System Preferences
• Grant permission to Terminal or your Node.js application

Linux

• Uses X11 and XTest extension
• Requires libxtst6 and libx11-6 packages
• Works with X11 window managers (not Wayland)
• For headless environments, use xvfb-run

Development

Building from Source

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone repository
git clone https://github.com/robotio/robotio.git
cd robotio

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

Platform-Specific Setup

See our detailed platform setup guides:

• Linux Testing Guide
• Windows Testing Guide

Testing

# Run all tests
pnpm test

# Run Rust tests only
cargo test

# Run TypeScript tests only
pnpm test:ts

# Run cross-platform test
node test_cross_platform.js

# Run platform-specific tests
node test_linux_setup.js     # Linux
node test_windows_setup.js   # Windows

Troubleshooting

Common Issues

Linux: "Failed to open X11 display"

# Install X11 dependencies
sudo apt-get install libxtst6 libx11-6

# For headless environments
sudo apt-get install xvfb
xvfb-run -a node your-script.js

macOS: "Operation not permitted"

• Go to System Preferences → Security & Privacy → Privacy → Accessibility
• Add Terminal or your Node.js application to the list

Windows: "SendInput failed"

• Run as Administrator if needed
• Check UAC settings
• Ensure no applications are blocking input

Performance Tips

• Use setDelay(0) for maximum speed in automation scenarios
• Batch multiple operations when possible
• Consider using press() and release() for complex interactions

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

Apache-2.0 - see LICENSE file for details.

Related Projects

• Other desktop automation tools and libraries for various platforms

Changelog

See CHANGELOG.md for version history and changes.