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:

Configuration File - Define devices and scenarios in YAML
Device Management API - Add/remove devices at runtime
Scenarios - Comprehensive error simulation concepts
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.

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