Add AGC, API contract, and E2E tests for refactoring protection

Unit tests (+18):
- TestMicAgcConfig (9): disable/restore AGC with mock USB device,
graceful handling of missing device, import errors, USB failures
- TestApiContracts (9): verify exact response shapes for /api/state,
config, moves, datasets, record, create-dataset, experiments —
protects against accidental field renames during frontend refactoring

E2E tests (+7):
- TestFormEdgeCases: duration persists in localStorage
- TestCommunitySection (3): section exists, expands, fetch button works
- TestHfUploadSection (3): username field and sync button presence

Total: 113 unit + 51 E2E + 37 hardware = 201 tests

TESTING.md

@@ -161,6 +161,8 @@ pytest tests/ --browser chromium
 | TestConcurrentStateChanges | 4 | Concurrent operations rejected when busy |
 | TestDurationEdgeCases | 3 | Duration boundary validation (gt=0.5, le=300) |
 | TestSyncDatasetExtended | 4 | Sync endpoint edge cases and validation |
+| TestMicAgcConfig | 9 | Mic AGC disable/restore with mock USB device |
+| TestApiContracts | 9 | API response shapes (refactoring protection) |
 
 ### E2E browser tests (`tests/e2e/test_ui.py`)
 
@@ -179,7 +181,9 @@ pytest tests/ --browser chromium
 | TestSwitchDataset | 2 | Dataset switching and dropdown population |
 | TestAudioSourceRadios | 3 | Audio source radio buttons and upload area toggle |
 | TestSettingsPanel | 3 | Settings expand, experimental toggle, root display |
-| TestFormEdgeCases | 4 | Empty/long/special labels and localStorage persistence |
+| TestFormEdgeCases | 5 | Empty/long/special labels and localStorage persistence |
+| TestCommunitySection | 3 | Community datasets section expand and fetch button |
+| TestHfUploadSection | 3 | HF username field and sync button presence |
 
 ### Hardware tests (`tests/test_hardware.py`)
 

tests/e2e/test_ui.py

@@ -636,3 +636,73 @@ class TestFormEdgeCases:
 
         restored = page.locator("#label").input_value()
         assert restored == "persistent-label"
+
+    def test_duration_persists_across_reload(self, page: Page, base_url: str):
+        """Duration is saved to the server (preferred_duration) and restored on reload."""
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        dur_input = page.locator("#duration")
+        dur_input.fill("7.5")
+        dur_input.dispatch_event("change")
+        # Wait for debounced POST /api/experiments to complete
+        page.wait_for_timeout(2000)
+
+        page.reload()
+        page.wait_for_timeout(2000)
+
+        restored = page.locator("#duration").input_value()
+        assert restored == "7.5"
+
+
+# ──────── Community section tests ─────────────────────────────────
+
+
+class TestCommunitySection:
+    def test_community_section_exists(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        section = page.locator("#community-details")
+        expect(section).to_be_attached()
+
+    def test_community_section_expands(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        summary = page.locator("#community-details > summary")
+        summary.scroll_into_view_if_needed()
+        summary.click()
+        page.wait_for_timeout(500)
+        fetch_btn = page.locator("#fetch-community-btn")
+        expect(fetch_btn).to_be_visible()
+
+    def test_fetch_community_button_clickable(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        summary = page.locator("#community-details > summary")
+        summary.scroll_into_view_if_needed()
+        summary.click()
+        fetch_btn = page.locator("#fetch-community-btn")
+        expect(fetch_btn).to_be_enabled()
+
+
+# ──────── HF upload section tests ─────────────────────────────────
+
+
+class TestHfUploadSection:
+    def test_hf_username_field_exists(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        username = page.locator("#hf-username")
+        expect(username).to_be_attached()
+
+    def test_sync_button_exists(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        sync_btn = page.locator("#sync-btn")
+        expect(sync_btn).to_be_attached()
+
+    def test_sync_button_disabled_without_selection(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        sync_btn = page.locator("#sync-btn")
+        expect(sync_btn).to_be_disabled()

tests/run_tests.py

@@ -55,6 +55,8 @@ TEST_CLASS_DESCRIPTIONS: dict[str, tuple[str, str]] = {
     "TestConcurrentStateChanges": ("unit", "Concurrent operations rejected when busy"),
     "TestDurationEdgeCases": ("unit", "Duration boundary validation (gt=0.5, le=300)"),
     "TestSyncDatasetExtended": ("unit", "Sync endpoint edge cases and validation"),
+    "TestMicAgcConfig": ("unit", "Mic AGC disable/restore with mock USB device"),
+    "TestApiContracts": ("unit", "API response shapes (refactoring protection)"),
     # E2E
     "TestPageLoad": ("e2e", "Page loads and main sections visible"),
     "TestIdleState": ("e2e", "Idle state display and controls"),
@@ -70,6 +72,8 @@ TEST_CLASS_DESCRIPTIONS: dict[str, tuple[str, str]] = {
     "TestAudioSourceRadios": ("e2e", "Audio source radio buttons and upload area toggle"),
     "TestSettingsPanel": ("e2e", "Settings expand, experimental toggle, root display"),
     "TestFormEdgeCases": ("e2e", "Empty/long/special labels and localStorage persistence"),
+    "TestCommunitySection": ("e2e", "Community datasets section expand and fetch button"),
+    "TestHfUploadSection": ("e2e", "HF username field and sync button presence"),
     # Hardware
     "TestHardwareStartup": ("hardware", "Robot reaches idle after startup"),
     "TestHardwareRecording": ("hardware", "Record and verify motion capture"),

tests/test_api.py

@@ -7,6 +7,7 @@ Tests the HTTP API layer, state machine, data validation, and persistence.
 import json
 from io import BytesIO
 from pathlib import Path
+from unittest.mock import MagicMock, patch
 
 import pytest
 from fastapi.testclient import TestClient
@@ -917,3 +918,192 @@ class TestSyncDatasetExtended:
         resp = client.post("/api/record", json={"duration": 3.0, "record_audio": False})
         assert resp.status_code == 409
         assert "downloaded" in resp.json()["detail"].lower()
+
+
+# ──────── Mic AGC config tests ────────────────────────────────────
+
+
+class TestMicAgcConfig:
+    """Tests for _disable_mic_agc / _restore_mic_agc."""
+
+    AGC_PATCH = "reachy_mini.media.audio_control_utils.init_respeaker_usb"
+
+    def _make_mock_respeaker(self, agc_value=None):
+        """Create a mock ReSpeaker device."""
+        mock = MagicMock()
+        mock.read.return_value = agc_value if agc_value is not None else [1]
+        return mock
+
+    def test_disable_agc_writes_zero(self, marionette: Marionette):
+        mock_dev = self._make_mock_respeaker(agc_value=[1])
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._disable_mic_agc()
+        mock_dev.read.assert_called_once_with("PP_AGCONOFF")
+        mock_dev.write.assert_called_once_with("PP_AGCONOFF", [0])
+        mock_dev.close.assert_called_once()
+        assert marionette._original_agc == [1]
+
+    def test_disable_agc_saves_original_value(self, marionette: Marionette):
+        mock_dev = self._make_mock_respeaker(agc_value=[0])
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._disable_mic_agc()
+        assert marionette._original_agc == [0]
+
+    def test_disable_agc_no_device(self, marionette: Marionette):
+        """Gracefully skips when no USB device is found."""
+        with patch(self.AGC_PATCH, return_value=None):
+            marionette._disable_mic_agc()  # Should not raise
+        assert not hasattr(marionette, "_original_agc") or marionette._original_agc is None
+
+    def test_disable_agc_import_error(self, marionette: Marionette):
+        """Gracefully skips when audio_control_utils is not importable."""
+        with patch.dict("sys.modules", {"reachy_mini.media.audio_control_utils": None}):
+            marionette._disable_mic_agc()  # Should not raise
+
+    def test_disable_agc_usb_error(self, marionette: Marionette):
+        """Gracefully handles USB communication errors."""
+        mock_dev = self._make_mock_respeaker()
+        mock_dev.read.side_effect = OSError("USB transfer failed")
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._disable_mic_agc()  # Should not raise
+
+    def test_restore_agc_writes_original(self, marionette: Marionette):
+        marionette._original_agc = [1]
+        mock_dev = self._make_mock_respeaker()
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._restore_mic_agc()
+        mock_dev.write.assert_called_once_with("PP_AGCONOFF", [1])
+        mock_dev.close.assert_called_once()
+
+    def test_restore_agc_skips_when_no_original(self, marionette: Marionette):
+        """Skips restore when AGC was never disabled (no _original_agc)."""
+        mock_dev = self._make_mock_respeaker()
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._restore_mic_agc()  # Should not raise
+        mock_dev.write.assert_not_called()
+
+    def test_restore_agc_skips_when_original_is_none(self, marionette: Marionette):
+        marionette._original_agc = None
+        mock_dev = self._make_mock_respeaker()
+        with patch(self.AGC_PATCH, return_value=mock_dev):
+            marionette._restore_mic_agc()
+        mock_dev.write.assert_not_called()
+
+    def test_restore_agc_device_gone(self, marionette: Marionette):
+        """Gracefully handles device disconnected at restore time."""
+        marionette._original_agc = [1]
+        with patch(self.AGC_PATCH, return_value=None):
+            marionette._restore_mic_agc()  # Should not raise
+
+
+# ──────── API contract tests (refactoring protection) ──────────────
+
+
+class TestApiContracts:
+    """Verify exact response shapes that the frontend depends on.
+
+    These tests protect against accidental field renames or removals
+    during frontend refactoring.
+    """
+
+    def test_state_top_level_keys(self, client: TestClient):
+        data = client.get("/api/state").json()
+        required = {
+            "server_time", "mode", "message", "active_move",
+            "phase_start_at", "phase_end_at",
+            "countdown_ends_at",
+            "recording_started_at", "recording_duration", "recording_stats",
+            "pending_recording", "pending_playback",
+            "moves", "config", "datasets",
+        }
+        assert required == required.intersection(data.keys()), (
+            f"Missing keys: {required - data.keys()}"
+        )
+
+    def test_config_keys(self, client: TestClient):
+        config = client.get("/api/state").json()["config"]
+        required = {
+            "default_duration", "preferred_duration", "countdown_seconds",
+            "motion_sample_rate", "audio_available",
+            "active_dataset_path", "dataset_root_path",
+            "hf_username", "features", "feature_support",
+        }
+        assert required.issubset(config.keys()), (
+            f"Missing config keys: {required - config.keys()}"
+        )
+
+    def test_datasets_payload_shape(self, client: TestClient):
+        datasets = client.get("/api/state").json()["datasets"]
+        assert "active_id" in datasets
+        assert "root_path" in datasets
+        assert "entries" in datasets
+        assert isinstance(datasets["entries"], list)
+
+    def test_dataset_entry_keys(self, client: TestClient):
+        entries = client.get("/api/state").json()["datasets"]["entries"]
+        assert len(entries) >= 1, "Should have at least one default dataset"
+        entry = entries[0]
+        required = {"id", "label", "path", "folder", "origin"}
+        assert required.issubset(entry.keys()), (
+            f"Missing dataset entry keys: {required - entry.keys()}"
+        )
+
+    def test_move_payload_keys(
+        self, client: TestClient, marionette: Marionette, sample_move_json: dict
+    ):
+        data_dir = marionette._dataset_dir
+        (data_dir / "contract-test.json").write_text(json.dumps(sample_move_json))
+        marionette._refresh_recordings()
+
+        moves = client.get("/api/state").json()["moves"]
+        assert len(moves) >= 1
+        move = moves[0]
+        required = {
+            "id", "label", "duration", "created_at",
+            "has_audio", "description", "is_uploaded",
+        }
+        assert required.issubset(move.keys()), (
+            f"Missing move keys: {required - move.keys()}"
+        )
+
+    def test_error_responses_have_detail(self, client: TestClient):
+        """All 4xx responses should include a 'detail' field."""
+        # 409: record while busy
+        from marionette.main import Marionette as M
+        # 422: invalid payload
+        resp = client.post("/api/record", json={"duration": -1})
+        assert resp.status_code == 422
+        assert "detail" in resp.json()
+
+        # 400: play without move_id
+        resp = client.post("/api/play", json={})
+        assert resp.status_code == 422
+        assert "detail" in resp.json()
+
+    def test_record_response_shape(self, client: TestClient):
+        resp = client.post("/api/record", json={
+            "duration": 2.0, "record_audio": False,
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "accepted" in data
+        assert "move_id" in data
+        assert "label" in data
+
+    def test_create_dataset_response_shape(self, client: TestClient):
+        resp = client.post("/api/datasets", json={"name": "contract-ds"})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "status" in data
+        assert "dataset" in data
+        ds = data["dataset"]
+        assert "id" in ds
+        assert "label" in ds
+        assert "folder" in ds
+
+    def test_experiments_response_shape(self, client: TestClient):
+        resp = client.post("/api/experiments", json={"motion_models": True})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "status" in data
+        assert "features" in data