@device-farm/node

Node server package for the Device Farm project - connects devices to the hub for distributed testing.

📖 Documentation

All documentation has been consolidated in the main README.

Please refer to the main README for:

• Node Configuration - Complete configuration reference
• Embedded Appium Server - Built-in Appium server setup
• ADB Log Capture - Automatic Android log capture
• iOS Automation Setup - WebDriverAgent preparation
• Node Liveness & Heartbeat System - How nodes stay connected
• Available Scripts - Commands to run the node server

🚀 Quick Start

Using the Published Package (farm-runner)

After installing farm-runner globally or locally:

# Install globally
npm install -g farm-runner

# Start the node server
farm-runner
# or explicitly
farm-runner start

# With custom config
farm-runner start --config ./node.config.json

# Prepare WebDriverAgent for iOS devices
farm-runner run prepare-wda

# Prepare WDA with options
farm-runner run prepare-wda -m ~/path/to/profile.mobileprovision
farm-runner run prepare-wda --platform ios

# Show help
farm-runner --help
farm-runner run prepare-wda -h

From Root Directory (Development)

# Copy and edit the configuration file
cp packages/node/node.config.example.json packages/node/node.config.json

# Edit node.config.json with your hub credentials
# Then start the node server
npm run start:node

From Node Package Directory (Development)

# Copy and edit the configuration file
cp node.config.example.json node.config.json

# Edit node.config.json with your hub credentials
# Then start the server
npm run start

# Or use the CLI in development
npm run cli -- run prepare-wda

🔧 Minimal Configuration

Create packages/node/node.config.json:

{
  "hubUrl": "http://localhost:3000",
  "accessKey": "YOUR_ACCESS_KEY",
  "token": "YOUR_TOKEN",
  "name": "My Node"
}

The node will automatically:

• Detect and register connected devices
• Start an embedded Appium server
• Send heartbeats to the hub
• Process automation requests

🖥️ CLI Commands

When installed as farm-runner, the following commands are available:

Start the Node Server

# Default command - starts the node server
farm-runner
farm-runner start

# With custom configuration file
farm-runner start --config /path/to/node.config.json

Prepare WebDriverAgent (iOS)

# Interactive mode - prompts for options
farm-runner run prepare-wda

# With mobile provisioning profile
farm-runner run prepare-wda -m ~/Library/MobileDevice/Provisioning\ Profiles/profile.mobileprovision

# With custom WDA project path
farm-runner run prepare-wda -p ~/WebDriverAgent

# Specify platform (ios, tvos, or both)
farm-runner run prepare-wda --platform ios

# Complete example with all options
farm-runner run prepare-wda -m ./profile.mobileprovision -p ./WebDriverAgent --platform both

# Show help
farm-runner run prepare-wda --help

The prepare-wda command will:

1. Build and sign WebDriverAgent with your provisioning profile
2. Create a .ipa file
3. Upload it to the hub (if running)
4. Cache it locally for use by the node

📦 What This Package Does

• Device Detection: Automatically discovers connected Android and iOS devices
• Appium Integration: Runs an embedded Appium server (no global installation needed)
• Hub Communication: Registers with the hub and maintains connection via heartbeats
• Session Management: Creates and manages Appium sessions on local devices
• Log Capture: Automatically captures device logs (ADB logcat for Android)
• Capability Processing: Handles device-specific capabilities like WDA for iOS

🔗 Related Documentation

• Complete Configuration: See Node Configuration in main README
• Database Setup: See Database Setup in main README
• iOS Setup: See iOS Automation Setup in main README
• Heartbeat System: See Node Liveness & Heartbeat System in main README

📄 License

MIT