SPARTA

SPARTA is a session orchestration layer for parallel Android QA automation with Appium.

It focuses on the part that usually breaks first in large mobile test farms:

• picking the right Appium server
• leasing a collision-free systemPort
• keeping that lease alive
• releasing or reclaiming it safely

What SPARTA Is Good At

• multiple Appium server coordination
• capacity-aware session placement
• lease-based systemPort allocation
• local memory mode for fast onboarding
• Redis-backed node-agent leases for more durable shared usage
• automation-friendly HTTP APIs and example Node.js clients

Release Status

Current repo state: v0.3.0

Status Matrix

Area	Status	Notes
Control-plane register / allocate / heartbeat / release	Stable	Covered by tests and examples
Node-agent memory backend	Stable	Best default for local onboarding
Node-agent Redis backend	Stable	Durable lease state for shared use
Multiple Appium servers	Stable	Supports capacity-aware balancing and filtering
Server tags / metadata filters	Stable	Use requiredTags and requiredMetadata on allocation
1000 logical session placement simulation	Verified	Run npm run benchmark:scale
Multi-instance control-plane durability	Not yet	Control-plane state is still in-memory
UI / RBAC / metrics exporter	Not yet	Deliberately out of scope for this release

Five-Minute Path

npm install
npm --workspace @sparta/node-agent run start -- --host 127.0.0.1 --port 8731 --port-range 8200-8299
npm --workspace @sparta/control-plane run start -- --host 127.0.0.1 --port 4400

If you want durable node-agent leases:

npm run redis:up
npm --workspace @sparta/node-agent run start -- --backend redis --redis-url redis://127.0.0.1:6379 --redis-prefix sparta:node-agent

If you want a full local stack with containers:

docker compose -f docker-compose.local.yml up --build

Config Surface

SPARTA uses the SPARTA_* prefix as the canonical env surface.

Main variables:

• SPARTA_CONTROL_PLANE_HOST
• SPARTA_CONTROL_PLANE_PORT
• SPARTA_SELECTION_POLICY
• SPARTA_NODE_AGENT_HOST
• SPARTA_NODE_AGENT_PORT
• SPARTA_NODE_AGENT_LEASE_BACKEND
• SPARTA_REDIS_URL
• SPARTA_REDIS_PREFIX
• SPARTA_AUTH_TOKEN

Config file examples:

• control-plane.config.example.json
• node-agent.config.example.json
• .env.example

Legacy aliases such as CONTROL_PLANE_*, NODE_AGENT_*, LEASE_STORE_MODE, and REDIS_URL are still accepted for compatibility.

Proof Points

• root test suite passes across all workspaces with npm test
• 1000 logical session placement simulation is included via npm run benchmark:scale
• burst allocation test proves one server is not overbooked under concurrent allocation requests
• background routine test proves poller/janitor loops do not overlap when work runs longer than the interval
• control-plane scheduling supports multiple Appium servers, tags, metadata filters, and least-loaded or round-robin policy

Repo Layout

• apps/control-plane for scheduling and session lifecycle orchestration
• apps/node-agent for host-local lease management and cleanup
• packages/lease-manager for reusable in-memory and Redis-backed lease allocation
• packages/shared-types for shared payload contracts and constants
• examples/developer-test-runner for runnable consumer integrations
• benchmarks/ for scale simulation and end-to-end load / soak harnesses
• benchmarks/results for generated benchmark reports
• docs/ for onboarding, deployment, scale, troubleshooting, and glossary
• openapi.yaml for the HTTP contract

Read The Docs In This Order

• Getting Started
• Glossary
• Deployment
• Scale Guide
• Benchmark Guide
• Examples
• Lease Lifecycle
• Troubleshooting
• OpenAPI Spec

Honest Production Note

SPARTA v0.3.0 is ready for local teams, CI pilots, and early self-hosting.

The most production-friendly shape today is:

• one active control-plane instance
• one node-agent per lease domain or host
• Redis enabled on node-agents when you want durable lease coordination
• Appium managed separately and registered explicitly

If you want multi-control-plane durability, that is the next major hardening step, not something this repo pretends to have already solved.