client/python/tests/README.md

Integration Tests for LeRobot Arena Python Client

Comprehensive integration tests for the LeRobot Arena Python client library.

Prerequisites

1. Server Running: Make sure the LeRobot Arena server is running on http://localhost:8000
2. Dependencies: Install test dependencies:

   pip install -e ".[dev]"
   

Running Tests

Quick Start

# Run all tests
python run_tests.py

# Or use pytest directly
pytest -v

Specific Test Categories

# REST API tests only
pytest tests/test_rest_api.py -v

# Producer tests only  
pytest tests/test_producer.py -v

# Consumer tests only
pytest tests/test_consumer.py -v

# Factory function tests only
pytest tests/test_factory_functions.py -v

# End-to-end integration tests only
pytest tests/test_integration.py -v

Advanced Options

# Run tests with detailed output
pytest -v -s

# Run specific test
pytest tests/test_producer.py::TestRoboticsProducer::test_send_joint_update -v

# Run tests matching pattern
pytest -k "producer" -v

# Stop on first failure
pytest -x

Test Structure

test_rest_api.py

• Room creation and deletion
• Listing rooms
• Getting room state and info
• Error handling for nonexistent rooms

test_producer.py

• Producer connection and disconnection
• Sending joint updates and state sync
• Emergency stop functionality
• Event callbacks
• Error conditions and validation
• Context manager support
• Multiple room handling

test_consumer.py

• Consumer connection and disconnection
• Receiving joint updates and state sync
• Event callbacks and message handling
• Multiple consumers per room
• State synchronization
• Error propagation

test_factory_functions.py

• create_client() factory function
• create_producer_client() convenience function
• create_consumer_client() convenience function
• Parameter validation
• Auto room creation
• Error handling

test_integration.py

• End-to-end producer-consumer workflows
• Multiple consumers receiving same messages
• Emergency stop propagation
• Producer reconnection scenarios
• Late-joining consumers
• High-frequency update handling
• Room state persistence

Test Fixtures

Core Fixtures

• producer: Clean RoboticsProducer instance
• consumer: Clean RoboticsConsumer instance
• test_room: Auto-created and cleaned up room
• connected_producer: Producer connected to test room
• connected_consumer: Consumer connected to test room
• producer_consumer_pair: Connected producer and consumer pair

Test Coverage

The test suite covers:

✅ REST API Operations

• ✅ Room CRUD operations
• ✅ State and info retrieval
• ✅ Error handling

✅ WebSocket Communication

• ✅ Connection establishment
• ✅ Message sending/receiving
• ✅ Connection cleanup

✅ Producer Functionality

• ✅ Joint updates and state sync
• ✅ Emergency stop
• ✅ Heartbeat
• ✅ Event callbacks

✅ Consumer Functionality

• ✅ Message reception
• ✅ State synchronization
• ✅ Event callbacks
• ✅ Multiple consumer support

✅ Factory Functions

• ✅ Client creation
• ✅ Auto room creation
• ✅ Parameter validation

✅ Edge Cases

• ✅ Network disconnections
• ✅ Invalid parameters
• ✅ Nonexistent rooms
• ✅ Duplicate connections
• ✅ High-frequency updates

✅ Integration Scenarios

• ✅ Full producer-consumer workflows
• ✅ Multi-consumer broadcasting
• ✅ Emergency stop propagation
• ✅ Reconnection handling
• ✅ Late consumer joining

Running Individual Test Categories

Each test file can be run independently:

# Test basic REST operations
pytest tests/test_rest_api.py

# Test producer functionality
pytest tests/test_producer.py

# Test consumer functionality  
pytest tests/test_consumer.py

# Test factory functions
pytest tests/test_factory_functions.py

# Test end-to-end scenarios
pytest tests/test_integration.py

Debugging Tests

For debugging failed tests:

# Run with full output
pytest -v -s --tb=long

# Run single test with debugging
pytest tests/test_producer.py::TestRoboticsProducer::test_send_joint_update -v -s

# Use pdb for interactive debugging
pytest --pdb

Expected Test Results

When all tests pass, you should see output like:

🧪 Running LeRobot Arena Python Client Integration Tests
============================================================
⚠️  Make sure the server is running on http://localhost:8000

========================= test session starts =========================
collected 45+ items

tests/test_rest_api.py::TestRestAPI::test_list_rooms_empty PASSED
tests/test_rest_api.py::TestRestAPI::test_create_room PASSED
...
tests/test_integration.py::TestIntegration::test_high_frequency_updates PASSED

========================= 45+ passed in X.XXs =========================

✅ All tests passed!

Troubleshooting

Common Issues

1. Server Not Running

   ConnectionRefusedError: [Errno 61] Connection refused
   

   Solution: Start the LeRobot Arena server on http://localhost:8000

2. WebSocket Connection Timeout

   TimeoutError: WebSocket connection timeout
   

   Solution: Check server health and network connectivity

3. Test Timing Issues

   • Some tests may be sensitive to timing
   • Increase sleep durations in tests if needed
   • Run tests on a faster machine if possible

4. Port Conflicts

   • Make sure port 8000 is available
   • Update TEST_SERVER_URL in conftest.py if using different port

Getting Help

If tests fail consistently:

1. Check server logs for errors
2. Run individual test files to isolate issues
3. Use verbose output (-v -s) to see detailed information
4. Check network connectivity and firewall settings