screenkitten

Screenkitten 📱📸

A cross-platform Node.js library for taking screenshots on iOS simulators and Android devices/emulators.

Features

• 🍎 iOS Simulator Support - Take screenshots using xcrun simctl
• 🤖 Android Device/Emulator Support - Take screenshots using adb
• 🔄 Cross-platform - Unified API for both platforms
• 📁 Flexible Output - Save to custom paths or auto-generate temp files
• ⚡ AbortController Support - Cancel operations gracefully
• 🎯 TypeScript - Full type safety and IntelliSense
• 🔧 Configurable - Extensive options for both platforms
• 🚨 Rich Error Handling - Detailed error types with proper inheritance

Installation

npm install screenkitten

Quick Start

iOS Simulator

import { screenkitten } from 'screenkitten';

const ios = screenkitten({
  platform: 'ios',
  deviceId: 'booted', // Default: 'booted'
  type: 'png', // Default: 'png'
  outputPath: '/path/to/screenshot.png' // Optional: auto-generated if not provided
});

const screenshotPath = await ios.takeScreenshot();
console.log(`Screenshot saved to: ${screenshotPath}`);

Android Device/Emulator

import { screenkitten } from 'screenkitten';

const android = screenkitten({
  platform: 'android',
  deviceId: 'emulator-5554', // Optional: uses 'booted' by default
  outputPath: '/path/to/screenshot.png' // Optional: auto-generated if not provided
});

const screenshotPath = await android.takeScreenshot();
console.log(`Screenshot saved to: ${screenshotPath}`);

API Reference

Factory Function

screenkitten(options: ScreenkittenOptions)

Creates a platform-specific screenshot instance.

Parameters:

• options - Configuration object (see platform-specific options below)

Returns: ScreenkittenIOS or ScreenkittenAndroid instance

iOS Options

interface ScreenkittenOptionsIOS {
  platform: 'ios';
  deviceId?: string;        // Default: 'booted'
  xcrunPath?: string;       // Default: '/usr/bin/xcrun'
  type?: 'png' | 'jpeg';    // Default: 'png'
  display?: 'internal' | 'external'; // Default: 'internal'
  mask?: 'ignored' | 'alpha' | 'black'; // Default: 'ignored'
  outputPath?: string;      // Auto-generated if not provided
  abortSignal?: AbortSignal;
  onError?: OnErrorHandler;
}

Android Options

interface ScreenkittenOptionsAndroid {
  platform: 'android';
  deviceId?: string;        // Default: 'booted'
  adbPath?: string;         // Default: 'adb'
  outputPath?: string;      // Auto-generated if not provided
  abortSignal?: AbortSignal;
  onError?: OnErrorHandler;
}

Error Handling

You can control error behavior using the onError option:

type OnErrorHandler = 'throw' | 'ignore' | ((error: Error) => void);

Options:

• 'throw' (default) - Throws the error
• 'ignore' - Suppresses the error and returns the output path
• function - Custom error handler function

// Custom error handling
const ios = screenkitten({
  platform: 'ios',
  onError: (error) => {
    console.error('Screenshot failed:', error.message);
    // Custom logging, reporting, etc.
  }
});

Instance Methods

takeScreenshot(options?: Partial<ScreenkittenOptionsBase>): Promise<string>

Takes a screenshot and returns the path to the saved file.

Parameters:

• options - Optional override options for this specific screenshot

Returns: Promise that resolves to the screenshot file path

Example:

// Use instance defaults
const path1 = await ios.takeScreenshot();

// Override specific options for this screenshot
const path2 = await ios.takeScreenshot({
  outputPath: '/custom/path.png',
  deviceId: 'specific-device'
});

Abort Controller Support

Cancel screenshot operations gracefully:

const controller = new AbortController();

const ios = screenkitten({
  platform: 'ios',
  abortSignal: controller.signal
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const path = await ios.takeScreenshot();
  console.log('Screenshot saved:', path);
} catch (error) {
  if (error.name === 'ScreenkittenOperationAbortedError') {
    console.log('Screenshot was cancelled');
  }
}

Error Types

Screenkitten provides specific error types for different failure scenarios:

import {
  ScreenkittenError,                    // Base error class
  ScreenkittenDeviceNotFoundError,      // Device/simulator not found
  ScreenkittenXcrunNotFoundError,       // xcrun tool not found (iOS)
  ScreenkittenAdbNotFoundError,         // adb tool not found (Android)
  ScreenkittenIOSSimulatorError,        // iOS simulator not available
  ScreenkittenAndroidDeviceError,       // Android device not available
  ScreenkittenFileWriteError,           // Failed to write screenshot file
  ScreenkittenOperationAbortedError,    // Operation was aborted
  ScreenkittenScreenshotFailedError,    // Generic screenshot failure
  ScreenkittenInvalidTypeError          // Invalid screenshot type (iOS)
} from 'screenkitten';

All errors extend the base ScreenkittenError class, which extends the standard Error class.

Requirements

iOS

• macOS with Xcode and iOS Simulator
• xcrun tool (usually available at /usr/bin/xcrun)

Android

• Android SDK with adb tool
• Android device connected or emulator running

CommonJS Support

Screenkitten supports both ES modules and CommonJS:

// ES modules
import { screenkitten } from 'screenkitten';

// CommonJS
const { screenkitten } = require('screenkitten');

License

MIT

Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct.