npm package: @sannysoft/testrobo
Description: Modern Rust library for cross-platform desktop automation
Latest version: 0.0.7

# robotio

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

[![CI](https://github.com/robotio/robotio/actions/workflows/ci.yml/badge.svg)](https://github.com/robotio/robotio/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/robotio.svg)](https://www.npmjs.com/package/robotio)

## 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

```bash
npm install robotio
```

```bash
yarn add robotio
```

```bash
pnpm add robotio
```

## Quick Start

```typescript
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
```typescript
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`
```typescript
interface Point {
  x: number;
  y: number;
}
```

#### `MouseButton`
```typescript
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

```bash
# 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](./LINUX_TESTING.md)
- [Windows Testing Guide](./WINDOWS_TESTING.md)

### Testing

```bash
# 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"**
```bash
# 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](LICENSE) file for details.

## Related Projects

- Other desktop automation tools and libraries for various platforms

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.