# @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](../../README.md).**

Please refer to the main README for:

- **[Node Configuration](../../README.md#-node-configuration)** - Complete configuration reference
- **[Embedded Appium Server](../../README.md#-embedded-appium-server)** - Built-in Appium server setup
- **[ADB Log Capture](../../README.md#-adb-log-capture)** - Automatic Android log capture
- **[iOS Automation Setup](../../README.md#-ios-automation-setup)** - WebDriverAgent preparation
- **[Node Liveness & Heartbeat System](../../README.md#-node-liveness--heartbeat-system)** - How nodes stay connected
- **[Available Scripts](../../README.md#-available-scripts)** - Commands to run the node server

## 🚀 Quick Start

### Using the Published Package (farm-runner)

After installing `farm-runner` globally or locally:

```bash
# 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)

```bash
# 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)

```bash
# 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`:

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

```bash
# 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)

```bash
# 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](../../README.md#-node-configuration) in main README
- **Database Setup**: See [Database Setup](../../README.md#-database-setup) in main README
- **iOS Setup**: See [iOS Automation Setup](../../README.md#-ios-automation-setup) in main README
- **Heartbeat System**: See [Node Liveness & Heartbeat System](../../README.md#-node-liveness--heartbeat-system) in main README

## 📄 License

MIT
