Orchard

View Source

CI Hex.pm Documentation License Downloads Elixir

An Elixir package for managing Apple simulators with automatic lifecycle management using OTP supervision trees. Built on top of AXe for UI automation and Apple's simctl for simulator control.

Requirements

  • macOS only - Apple device management requires macOS
  • Xcode Command Line Tools
  • Elixir 1.14 or later

Installation

Add orchard to your list of dependencies in mix.exs:

def deps do
  [
    {:orchard, "~> 0.1.0"}
  ]
end

On first use, Orchard will automatically download the AXe CLI binary. You can also manually download it:

mix orchard.download

Configuration

You can configure the AXe version or provide a custom path:

# config/config.exs
config :orchard,
  axe_version: "1.0.0",  # Optional: specify AXe version
  axe_path: "/usr/local/bin/AXe"  # Optional: use custom AXe binary

Usage

# List all simulators
{:ok, simulators} = Orchard.Simulator.list()

# Boot a simulator (starts a GenServer to manage it)
{:ok, simulator} = Orchard.Simulator.boot(simulator)

# The simulator is now managed by a GenServer that:
# - Monitors its state every second
# - Automatically terminates if the simulator is removed
# - Provides a supervised process for all operations

# Install an app on a simulator
:ok = Orchard.Simulator.install_app(simulator, "/path/to/app.app")

# UI Automation with AXe
:ok = Orchard.Simulator.tap(simulator, 100, 200)
:ok = Orchard.Simulator.type_text(simulator, "Hello World")
{:ok, ui_tree} = Orchard.Simulator.describe_ui(simulator)

# Take a screenshot
:ok = Orchard.Simulator.screenshot(simulator, "/tmp/screenshot.png")

# Shutdown the simulator
:ok = Orchard.Simulator.shutdown(simulator)

Architecture

Orchard uses Erlang/OTP supervision trees to manage simulators and devices:

  • Each booted simulator runs in its own SimulatorServer GenServer
  • The SimulatorSupervisor manages all simulator processes
  • Simulators are automatically monitored and cleaned up
  • Crashed processes are restarted by the supervisor

Features

Simulator Management

  • List all available simulators
  • Boot and shutdown simulators
  • Install and launch apps
  • Automatic state monitoring via GenServers
  • Supervised processes with automatic cleanup

UI Automation (via AXe)

  • Tap at specific coordinates
  • Type text
  • Swipe gestures
  • Hardware button presses
  • Get accessibility hierarchy information

System Integration

  • Screenshot capture
  • Video recording
  • App installation/uninstallation
  • Process supervision with MuonTrap

Platform Support

  • macOS only - Requires Apple developer tools
  • Automatic AXe CLI download and management
  • Fails gracefully on unsupported platforms

How It Works

Orchard combines several technologies:

  1. AXe CLI - For UI automation and simulator listing
  2. Apple's simctl - For simulator control operations
  3. Erlang/OTP - For process supervision and state management
  4. MuonTrap - For reliable system process management

When you boot a simulator, Orchard:

  1. Starts a dedicated GenServer process for that simulator
  2. Monitors the simulator's state every second
  3. Automatically cleans up if the simulator is removed
  4. Provides a consistent interface for all operations

The AXe binary is automatically downloaded on first use or can be manually downloaded using mix orchard.download.

License

MIT