tractive-device-farm

An Appium 2.x plugin that manages a fleet of Android and iOS devices/simulators, allocates them to incoming WebDriver sessions, records the sessions, and serves a web UI for both device management and session inspection.

This package is the merged successor of two earlier packages — tractive-appium-device-farm and tractive-appium-dashboard — which used to be loaded together and call each other over HTTP. They are now one plugin. See MIGRATION.md if you're upgrading from 1.x.

What it does

• Device manager. Discovers connected Android devices, iOS real devices, and iOS simulators. Allocates them to incoming createSession requests. Supports cloud providers (BrowserStack, pCloudy, Sauce Labs, LambdaTest).
• Session recorder. Tracks each WebDriver session: command log, HTTP logs, screenshots, video, profiling data. Persisted in SQLite.
• Dashboard UI. React app served at /device-farm/dashboard for browsing builds and sessions.
• Device-farm UI. React app served at /device-farm for inspecting devices, uploading apps, viewing logs, and managing users.
• Authentication. Optional bearer-token auth (--plugin-tractive-device-farm-auth). Bootstrapped admin row seeded in SQLite (admin / admin — change after first login or wire in a real auth flow before exposing the UI beyond a trusted network).

Install

appium plugin install --source=npm tractive-device-farm

postinstall runs sequelize-cli db:migrate to ensure the dashboard's SQLite schema is up to date.

Run

appium server \
  --use-plugins=tractive-device-farm \
  --plugin-tractive-device-farm-platform=both \
  --plugin-tractive-device-farm-auth

Then open http://localhost:4723/device-farm/. Sign in with admin / admin.

To disable auth (back-compat, anyone-can-access mode), drop --plugin-tractive-device-farm-auth.

CLI flags

| Flag | Type | Notes | |---|---|---| | --plugin-tractive-device-farm-platform | android | ios | both | Required. | | --plugin-tractive-device-farm-androidDeviceType | real | emulator | both | Default both. | | --plugin-tractive-device-farm-iosDeviceType | real | simulator | both | Default both. | | --plugin-tractive-device-farm-maxSessions | number | | | --plugin-tractive-device-farm-auth | flag | Enable bearer-token auth (see below). | | --plugin-tractive-device-farm-hub | URL | Run as a node and register devices with a hub. | | --plugin-tractive-device-farm-emulators | array | Emulators to launch on startup. | | --plugin-tractive-device-farm-skipChromeDownload | bool | Skip Chromedriver download. |

URLs and storage

| | Path / location | |---|---| | Device-farm UI | /device-farm/ | | Dashboard UI | /device-farm/dashboard/ | | API | /device-farm/api/* | | WebDriver | /wd/hub/* (Appium's own path, not gated by plugin auth) | | Auth DB | ~/.appium-device-farm/auth.db (override: DEVICE_FARM_AUTH_DB) | | Dashboard DB | ~/.cache/appium-dashboard-plugin/database.sqlite | | Session videos | ~/.cache/appium-dashboard-plugin/videos/ |

Authentication

When --plugin-tractive-device-farm-auth is set:

• Admin row is seeded on first run (admin / admin, fixed UUID 00000000-0000-0000-0000-0000000000ad).
• Subsequent boots leave the row alone (INSERT OR IGNORE) — so password changes (when wired up) won't be clobbered.
• Every /device-farm/api/* route requires Authorization: Bearer <token> except POST /api/auth/login.
• /api/users requires admin role; returns 404 when auth is disabled (hides the endpoint).
• The dashboard UI shares the token via same-origin localStorage (df_token) — there's no second login.

To rotate the seeded admin, you can either edit the SQLite row directly or sign in once, create a real admin via the Users tab, and delete the bootstrapped row (DELETE FROM users WHERE is_bootstrapped = 1).

Hub / node mode

A node registers with a hub via POST /device-farm/api/register. Set --plugin-tractive-device-farm-hub=http://hub:4723. The hub aggregates devices from all nodes. (When auth is on, hub/node coordination needs a separate token — see the issue tracker, not implemented in 2.0.)

Documentation

Generated docs:

npm install
npm run build
npm run install-docs-deps
npm run build:docs

Contributing

npm install
npm run buildAndCopyWeb   # build both React apps into src/public
npm run build             # compile TypeScript
npm test                  # unit tests
npm run integration-android
npm run integration-ios

For day-to-day local development against a live device farm:

npm run reinstall-plugin  # rebuild + reinstall into APPIUM_HOME=/tmp/tractive-device-farm
npm run run-server        # appium server with the plugin enabled

The merged plugin's React code lives in two trees:

• web/ — the device-farm UI (React 18 + CRA).
• web-dashboard/ — the dashboard UI (React 17 + Craco). Built with REACT_APP_API_BASE_URL=/device-farm/dashboard so its router URLs land under /device-farm/dashboard/*; axios baseURL is hardcoded to /device-farm/api.

Thanks to contributors 💙