Skip to content

lifx-emulator (Standalone CLI)

The lifx-emulator package provides a ready-to-run CLI tool and HTTP management server.

Overview

This section covers the standalone emulator's advanced features for complex testing needs. These features are optional but powerful for:

  • Defining reproducible device setups via configuration files
  • Runtime device management
  • Comprehensive error simulation
  • Complex multi-scenario testing

Prerequisites

Before exploring advanced features, you should:

  • Be comfortable with basic emulator usage
  • Have completed at least the first 2-3 tutorials
  • Understand your testing requirements
  • Be familiar with REST APIs (for API features)

Learning Path

Read these guides in order from simple to complex:

  1. Configuration File - Define devices and scenarios in YAML
  2. Device Management API - Add/remove devices at runtime
  3. Scenarios - Comprehensive error simulation concepts
  4. Scenario API - REST API for managing test scenarios

Quick Concepts

Configuration File

Define your emulator setup in a YAML file instead of command-line arguments:

# lifx-emulator.yaml
api: true
color: 2
multizone: 1
devices:
  - product_id: 27
    label: "Living Room"

The emulator auto-detects lifx-emulator.yaml in the current directory, or use --config to specify a path. You can also set LIFX_EMULATOR_CONFIG to override the config path.

👉 Configuration Guide

Device Management API

Enable the HTTP API to manage devices at runtime:

lifx-emulator --color 1 --api

Access the web dashboard at http://localhost:8080 or use the REST API to add/remove devices dynamically.

👉 Device Management Guide

Testing Scenarios

Configure error conditions for comprehensive testing:

  • Packet loss (test retries)
  • Response delays (test timeouts)
  • Malformed data (test error handling)
  • Firmware version overrides

👉 Scenarios Guide

Scenario API

Manage scenarios via REST API with hierarchical scoping:

# Drop 100% of GetColor packets for all color devices
curl -X PUT http://localhost:8080/api/scenarios/types/color \
  -H "Content-Type: application/json" \
  -d '{"drop_packets": {"101": 1.0}}'

Supports device-specific, type-based, location-based, group-based, and global scenarios.

👉 Scenario API Reference

Feature Comparison

Feature Basic Advanced
Create devices ✅ ✅
Device discovery ✅ ✅
Control devices ✅ ✅
Runtime management ❌ ✅
Error simulation Basic Comprehensive
Web UI ❌ ✅
REST API ❌ ✅

When to Use Advanced Features

Use Configuration Files When:

  • You have complex device setups to reproduce
  • Sharing configurations with team members
  • Running tests in CI/CD pipelines
  • You want version-controlled emulator settings

Use Device Management API When:

  • Tests need dynamic device creation/removal
  • Running multi-stage test scenarios
  • Need visual monitoring during development
  • Integrating with external test orchestration

Use Scenarios When:

  • Testing retry logic and error handling
  • Simulating network issues (packet loss, delays)
  • Testing edge cases (malformed data, timeouts)
  • Validating firmware version compatibility
  • Testing client resilience

Combined Example

Use multiple advanced features together:

# Start with API and devices
lifx-emulator --api --color 2

# Configure global scenario for packet loss
curl -X PUT http://localhost:8080/api/scenarios/global \
  -H "Content-Type: application/json" \
  -d '{"drop_packets": {"101": 0.3}}'  # 30% packet loss

# Add device at runtime
curl -X POST http://localhost:8080/api/devices \
  -H "Content-Type: application/json" \
  -d '{"product_id": 32, "zone_count": 16}'

# Run your tests...

Next Steps

Choose a topic based on your needs, or read through all guides in order for comprehensive understanding.

  1. Configuration File - YAML-based configuration
  2. Device Management API - Add/remove devices at runtime
  3. Scenarios - Comprehensive error simulation concepts
  4. Scenario API - REST API for managing test scenarios