Track previously untracked test support files

- HARDWARE_TEST_PLAN.md: hardware test design document
- check_audio.py: audio subsystem check utility
- check_robot.py: robot connectivity check
- pose_utils.py: trajectory comparison utilities for motion accuracy tests

tests/HARDWARE_TEST_PLAN.md

@@ -0,0 +1,143 @@
+# Hardware Test Plan — Comprehensive Robot Integration Tests
+
+## Approach
+
+Use the Wireless unit connected over the network. Tests run from the laptop
+using the same code paths as production (Marionette `run()` loop + HTTP API).
+The reachy_mini SDK handles wireless streaming transparently.
+
+## Existing Tests (8 passing, 3 audio skipped)
+
+- Startup reaches idle
+- Silent recording captures motion at ~100Hz
+- Playback of silent move completes
+- Record and delete lifecycle
+- Recording produces correct JSON (frame count, timestamps, pose structure)
+- Full record → replay → delete lifecycle
+- Stop cancels queued recording
+- Recording transitions through countdown → recording → idle
+
+## New Tests to Add
+
+### 1. Record-while-playing (motion accuracy)
+
+**Idea:** Play a known move and simultaneously record it. Compare the
+recorded motion to the original. This exercises the full pipeline and
+measures end-to-end accuracy.
+
+**How it works:**
+1. Load a reference move from disk (an existing recording in the test dataset)
+2. Start a recording via POST /api/record (silent, same duration as reference)
+3. Immediately start playback of the reference move via `_stream_playback()`
+   in a background thread (directly on the Marionette instance, bypassing
+   the API since the API only allows one operation at a time)
+4. Wait for recording to complete
+5. Load the newly recorded move from disk
+6. Compare frame-by-frame using `distance_between_poses()`
+
+**What to measure:**
+- **Per-frame magic distance** between reference and recorded head poses
+- **RMSE** of magic distances over the full trajectory
+- **Max error** (worst single frame)
+- **Mean error**
+- **Antenna RMSE** (L2 of joint angle differences)
+
+**Thresholds (tunable):**
+- Mean magic distance < 50 (50mm or 50 degrees equivalent — generous)
+- Max magic distance < 100
+- RMSE < 60
+
+These are deliberately loose — we want to catch "robot didn't move" or
+"completely wrong pose" bugs, not sub-millimeter tracking.
+
+**Challenge:** The API doesn't support simultaneous record + play.
+**Solution:** We use the `hw_marionette` instance directly:
+- Call `_stream_playback()` in a thread to move the robot
+- Separately, the `_capture_motion()` records what actually happens
+- OR: We do it in two phases: first play a reference move, then start
+  recording and play it again. The recording captures the actual motion.
+
+Actually, simplest approach:
+1. First, ensure a reference move exists (record a 3s silent move)
+2. POST /api/record to start recording (3s, silent)
+3. During the countdown + recording, play the reference move via the SDK directly
+4. After recording completes, compare the two JSONs
+
+### 2. Timing / performance benchmarks
+
+**Tests:**
+- **Startup time**: How long from `run()` start to `mode=idle`?
+  Already measured implicitly (STARTUP_TIMEOUT=30s), but add explicit timing.
+- **Recording start latency**: Time from POST /api/record to mode=countdown.
+  Should be < 200ms.
+- **Playback start latency**: Time from POST /api/play to actual motor movement.
+  Measured by comparing first frame timestamp to request time.
+- **Recording frame rate**: Verify actual ~100Hz (already tested via frame count).
+- **Playback smoothness**: During playback, poll pose at high rate, verify
+  it changes continuously (no freezes > 200ms).
+
+### 3. Audio tests (expanded, with duration comparison)
+
+**Tests:**
+- **Duration match**: Record with mic, verify WAV duration matches requested
+  duration within 0.5s tolerance.
+- **Waveform not silent**: Play a known sound file on the robot speaker while
+  recording with mic. Verify the recorded WAV has energy (RMS > threshold),
+  not just zeros.
+- **Playback-with-audio completes**: Play a move that has audio, verify timing.
+
+### 4. Pose comparison utilities
+
+Create a test helper module `tests/pose_utils.py` with:
+
+```python
+from reachy_mini.utils.interpolation import distance_between_poses
+import numpy as np
+
+def compare_trajectories(ref_times, ref_frames, rec_times, rec_frames):
+    """Compare two recorded trajectories frame-by-frame.
+
+    Interpolates the recorded trajectory to match reference timestamps.
+    Returns dict with RMSE, max_error, mean_error, per-frame distances.
+    """
+    ...
+```
+
+### 5. Multi-move benchmark
+
+Record and play back 3 different moves:
+- A short move (1s)
+- A medium move (3s)
+- A longer move (5s)
+
+For each, measure recording frame rate, playback completion time, and
+verify the move data is well-formed.
+
+## File Changes
+
+| Action | File |
+|--------|------|
+| Create | `tests/pose_utils.py` — trajectory comparison helpers |
+| Modify | `tests/test_hardware.py` — add new test classes |
+| Modify | `tests/run_tests.py` — update class descriptions |
+| Modify | `TESTING.md` — document new test classes |
+
+## Test Classes (proposed)
+
+| Class | Tests | Description |
+|-------|-------|-------------|
+| TestMotionAccuracy | 2-3 | Play reference move while recording, compare trajectories |
+| TestPerformance | 3-4 | Startup timing, recording latency, frame rate, playback smoothness |
+| TestHardwareAudio | 3 | (existing) Audio recording and playback |
+
+## Open Questions
+
+1. Can we play a move via the SDK while the Marionette API is recording?
+   The run() loop handles one job at a time, but `set_target_head_pose()`
+   is a direct SDK call that should work independently.
+
+2. What's a reasonable accuracy threshold? Need to calibrate on one run,
+   then set thresholds with margin.
+
+3. Should benchmarks be hard-fail or just print results? Suggest: print
+   results always, fail only on extreme regressions.

tests/check_audio.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Quick check: can the robot play audio from this laptop?"""
+
+import sys
+import time
+
+from reachy_mini import ReachyMini
+
+
+def main() -> int:
+    wav = "/home/remi/reachy_mini_apps/reachy_mini/examples/recorded_audio.wav"
+    print("Connecting to robot...")
+    with ReachyMini() as r:
+        mode = r.connection_mode
+        has_media = hasattr(r, "media") and r.media is not None
+        print(f"Connection mode: {mode}")
+        print(f"Has media: {has_media}")
+        if not has_media:
+            print("FAIL: no media backend")
+            return 1
+        try:
+            print(f"Playing {wav} ...")
+            r.media.play_sound(wav)
+            time.sleep(3)
+            print("OK: play_sound completed")
+            return 0
+        except Exception as e:
+            print(f"FAIL: {e}")
+            return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/check_robot.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Quick check: is the robot reachable?
+
+Usage:
+    python tests/check_robot.py
+
+Exits 0 if the robot is connected, 1 otherwise.
+"""
+
+import sys
+import threading
+
+
+def main() -> int:
+    result = [None, None]  # [reachy, error]
+
+    def _connect():
+        try:
+            from reachy_mini import ReachyMini
+            reachy = ReachyMini(media_backend="no_media")
+            pose = reachy.get_current_head_pose()
+            result[0] = pose
+        except Exception as exc:
+            result[1] = str(exc)
+
+    t = threading.Thread(target=_connect, daemon=True)
+    t.start()
+    t.join(timeout=10)
+
+    if t.is_alive():
+        print("FAIL: connection timed out after 10s")
+        return 1
+    if result[1]:
+        print(f"FAIL: {result[1]}")
+        return 1
+
+    print(f"OK: robot connected, head pose shape = {result[0].shape}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/pose_utils.py

@@ -0,0 +1,116 @@
+"""Pose comparison utilities for hardware integration tests.
+
+Provides trajectory comparison using distance_between_poses() from
+the reachy_mini SDK.  Returns per-frame and aggregate metrics (RMSE,
+max, mean) for translation, rotation, and "magic distance".
+"""
+
+import numpy as np
+from dataclasses import dataclass
+
+from reachy_mini.utils.interpolation import distance_between_poses
+
+
+@dataclass
+class TrajectoryMetrics:
+    """Aggregate metrics from comparing two trajectories."""
+
+    n_frames: int
+    # Magic distance (mm + degrees combined)
+    magic_mean: float
+    magic_rmse: float
+    magic_max: float
+    magic_p95: float
+    # Translation (meters)
+    trans_mean: float
+    trans_rmse: float
+    trans_max: float
+    # Rotation (radians)
+    rot_mean: float
+    rot_rmse: float
+    rot_max: float
+    # Per-frame arrays
+    magic_distances: np.ndarray
+    trans_distances: np.ndarray
+    rot_distances: np.ndarray
+
+    def summary(self) -> str:
+        return (
+            f"Trajectory comparison ({self.n_frames} frames):\n"
+            f"  Magic:  mean={self.magic_mean:.1f}  rmse={self.magic_rmse:.1f}  "
+            f"max={self.magic_max:.1f}  p95={self.magic_p95:.1f}\n"
+            f"  Trans:  mean={self.trans_mean*1000:.1f}mm  "
+            f"rmse={self.trans_rmse*1000:.1f}mm  max={self.trans_max*1000:.1f}mm\n"
+            f"  Rot:    mean={np.degrees(self.rot_mean):.1f}deg  "
+            f"rmse={np.degrees(self.rot_rmse):.1f}deg  max={np.degrees(self.rot_max):.1f}deg"
+        )
+
+
+def frames_to_poses(frames: list[dict]) -> list[np.ndarray]:
+    """Extract head poses (4x4 matrices) from recorded frames."""
+    poses = []
+    for f in frames:
+        head = f["head"]
+        poses.append(np.array(head, dtype=np.float64))
+    return poses
+
+
+def compare_trajectories(
+    ref_times: list[float],
+    ref_frames: list[dict],
+    rec_times: list[float],
+    rec_frames: list[dict],
+) -> TrajectoryMetrics:
+    """Compare two recorded trajectories frame-by-frame.
+
+    Interpolates the recorded trajectory timestamps to match the reference
+    timestamps using nearest-neighbor lookup, then computes per-frame
+    distances using distance_between_poses().
+
+    Args:
+        ref_times: timestamps from the reference recording
+        ref_frames: frame dicts from the reference recording
+        rec_times: timestamps from the new recording
+        rec_frames: frame dicts from the new recording
+
+    Returns:
+        TrajectoryMetrics with per-frame and aggregate distances.
+    """
+    ref_poses = frames_to_poses(ref_frames)
+    rec_poses = frames_to_poses(rec_frames)
+    rec_times_arr = np.array(rec_times)
+
+    trans_dists = []
+    rot_dists = []
+    magic_dists = []
+
+    for i, (t, ref_pose) in enumerate(zip(ref_times, ref_poses)):
+        # Find nearest recorded frame by timestamp
+        idx = int(np.argmin(np.abs(rec_times_arr - t)))
+        rec_pose = rec_poses[idx]
+
+        d_trans, d_rot, d_magic = distance_between_poses(ref_pose, rec_pose)
+        trans_dists.append(d_trans)
+        rot_dists.append(d_rot)
+        magic_dists.append(d_magic)
+
+    trans_arr = np.array(trans_dists)
+    rot_arr = np.array(rot_dists)
+    magic_arr = np.array(magic_dists)
+
+    return TrajectoryMetrics(
+        n_frames=len(ref_times),
+        magic_mean=float(np.mean(magic_arr)),
+        magic_rmse=float(np.sqrt(np.mean(magic_arr**2))),
+        magic_max=float(np.max(magic_arr)),
+        magic_p95=float(np.percentile(magic_arr, 95)),
+        trans_mean=float(np.mean(trans_arr)),
+        trans_rmse=float(np.sqrt(np.mean(trans_arr**2))),
+        trans_max=float(np.max(trans_arr)),
+        rot_mean=float(np.mean(rot_arr)),
+        rot_rmse=float(np.sqrt(np.mean(rot_arr**2))),
+        rot_max=float(np.max(rot_arr)),
+        magic_distances=magic_arr,
+        trans_distances=trans_arr,
+        rot_distances=rot_arr,
+    )