saltylab-firmware/jetson/ros2_ws/src/saltybot_tests/README.md

SaltyBot Integration Test Suite (Issue #504)

Comprehensive automated testing for the SaltyBot full stack. Verifies all nodes start, topics publish, TF tree is complete, and system remains stable.

What's Tested

Main Test (test_launch.py)

• ✅ All critical nodes start within 30 seconds
• ✅ Required topics are advertised
• ✅ TF tree is complete
• ✅ Sensor data publishing (odometry, IMU, LIDAR, camera)
• ✅ Person detection topic available
• ✅ No immediate node crashes
• ✅ System stability for 30 seconds (all nodes remain alive)

Subsystem Tests (test_subsystems.py)

• Sensor Health: LIDAR scan rate, RealSense RGB/depth, IMU publishing
• Perception: YOLOv8 person detection node alive and publishing
• Navigation: Odometry continuity, TF broadcasts active
• Communication: Rosbridge server running, critical topics bridged

Running Tests

Quick Test (follow mode, ~45 seconds)

cd jetson/ros2_ws
colcon build --packages-select saltybot_tests
source install/setup.bash

# Run all tests
pytest install/saltybot_tests/lib/saltybot_tests/../../../share/saltybot_tests/ -v -s

# Or directly
ros2 launch launch_testing launch_test.py ./src/saltybot_tests/test/test_launch.py

Individual Test File

pytest src/saltybot_tests/test/test_launch.py -v -s
pytest src/saltybot_tests/test/test_subsystems.py -v

With colcon test

colcon test --packages-select saltybot_tests --event-handlers console_direct+

Test Modes

Follow Mode (Default - Fastest)

• ✅ Sensors: RPLIDAR, RealSense D435i
• ✅ Person detection: YOLOv8n
• ✅ Person follower controller
• ✅ UWB positioning
• ✅ Rosbridge WebSocket
• ❌ SLAM (not required)
• ❌ Nav2 (not required)
• Startup time: ~30 seconds
• Best for: Quick CI/CD validation

Indoor Mode (Full Stack)

• Everything in follow mode +
• ✅ SLAM: RTAB-Map with RGB-D + LIDAR
• ✅ Nav2 navigation stack
• Startup time: ~45 seconds
• Best for: Complete system validation

Test Output

Success Example

test_launch.py::TestSaltyBotStackLaunch::test_01_critical_nodes_start PASSED
test_launch.py::TestSaltyBotStackLaunch::test_02_required_topics_advertised PASSED
test_launch.py::TestSaltyBotStackLaunch::test_03_tf_tree_complete PASSED
test_launch.py::TestSaltyBotStackLaunch::test_04_odometry_publishing PASSED
test_launch.py::TestSaltyBotStackLaunch::test_05_sensors_publishing PASSED
test_launch.py::TestSaltyBotStackLaunch::test_06_person_detection_advertised PASSED
test_launch.py::TestSaltyBotStackLaunch::test_07_no_immediate_crashes PASSED
test_launch.py::TestSaltyBotStackLaunch::test_08_system_stability_30s PASSED

Failure Example

FAILED test_launch.py::TestSaltyBotStackLaunch::test_02_required_topics_advertised
  AssertionError: Required topics not advertised: ['/uwb/target', '/person/detections']
  Advertised: ['/camera/color/image_raw', '/scan', ...]

CI Integration

Add to your CI/CD pipeline:

- name: Run Integration Tests
  run: |
    source /opt/ros/humble/setup.bash
    colcon build --packages-select saltybot_tests
    colcon test --packages-select saltybot_tests --event-handlers console_direct+

Troubleshooting

Nodes Don't Start

• Check hardware connections: RPLIDAR, RealSense, UWB anchors
• Review full_stack.launch.py for required serial ports
• Check logs: ros2 run rqt_graph rqt_graph

Topics Missing

• Verify nodes are alive: ros2 node list
• Check topic list: ros2 topic list
• Inspect topics: ros2 topic echo /scan (first 10 messages)

TF Tree Incomplete

• Verify robot_description is loaded
• Check URDF: ros2 param get /robot_state_publisher robot_description
• Monitor transforms: ros2 run tf2_tools view_frames.py

Sensor Data Not Publishing

• RPLIDAR: Check /dev/ttyUSB0 permissions
• RealSense: Check USB connection, device list: rs-enumerate-devices
• IMU: Verify RealSense firmware is current

Test Timeout

• Integration tests default to 120s per test
• Increase timeout in conftest.py if needed
• Check system load: top or htop

Architecture

saltybot_tests/
├── test/
│   ├── test_launch.py          ← Main launch_testing tests
│   ├── test_subsystems.py      ← Detailed subsystem checks
│   └── conftest.py
├── saltybot_tests/
│   ├── test_helpers.py         ← NodeChecker, TFChecker, TopicMonitor
│   └── __init__.py
├── package.xml                 ← ROS2 metadata
├── setup.py                    ← Python build config
└── README.md

Key Features

NodeChecker

Waits for nodes to appear in the ROS graph. Useful for verifying startup sequence.

TFChecker

Ensures TF tree is complete (all required frame transforms exist).

TopicMonitor

Tracks message counts and publishing rates for sensors.

Contributing

Add new integration tests in test/:

1. Create test_feature.py with unittest.TestCase subclass
2. Use NodeChecker, TFChecker, TopicMonitor helpers
3. Follow test naming: test_01_critical_functionality
4. Run locally: pytest test/test_feature.py -v -s

Performance Targets

Component	Startup	Rate	Status
Robot description	<1s	N/A	✅
RPLIDAR driver	<2s	10 Hz	✅
RealSense	<2s	30 Hz	✅
Person detection	<6s	5 Hz	✅
Follower	<9s	10 Hz	✅
Rosbridge	<17s	N/A	✅
Full stack stable	30s	N/A	✅

See Also

• full_stack.launch.py — Complete startup sequence
• ROS2 launch_testing — Test framework
• Issue #504: Robot integration test suite