[AZ-600] Batch 80: refactor sitl_replay_builder to strategy pattern

Replace per-scenario fixture builders with a parameterized strategy
framework so future Derkachi-based scenarios compose existing pieces
instead of duplicating ~200 lines of orchestration per scenario.

New e2e/fixtures/sitl_replay_builder/builder.py:
- VideoSource ABC + StillImagesSource, Mp4PassthroughSource
- TlogSource ABC + SyntheticStationaryTlog, ImuCsvTlog
- FdrProjection ABC + RawFdrPassthrough, OutboundMessagesProjection
- FixtureBuilderConfig + build_fixtures(cfg) orchestrator
- Consolidated MAVLink pack_raw_imu / pack_attitude helpers
- Consolidated run_gps_denied_replay + write_observer_fixture

build_p01_fixtures.py: 423 -> 107 lines (75% reduction).
build_p02_fixtures.py: 292 -> 98 lines (66% reduction).
_common.py: deleted (folded into builder.py).

Tests reorganized:
- test_sitl_replay_builder_builder.py (new, 33 strategy-level tests)
- test_sitl_replay_builder.py (slimmed, 6 FT-P-01 integration)
- test_sitl_replay_builder_p02.py (slimmed, 7 FT-P-02 integration)

README documents the strategy framework + a worked example for
adding FT-P-04 in ~30 lines (no new strategy code required).

Regression gate: 700 passing (was 686; +14 from finer-grained
coverage of new strategy classes and the build_fixtures orchestrator).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-17 14:19:08 +03:00
parent 4e0717e543
commit 7fb3cb3f34
13 changed files with 2050 additions and 1272 deletions
@@ -1,9 +1,8 @@
"""Unit tests for `e2e/fixtures/sitl_replay_builder/build_p01_fixtures.py` (AZ-598).
"""Integration tests for `e2e/fixtures/sitl_replay_builder/build_p01_fixtures.py` (FT-P-01).
All external dependencies (OpenCV, pymavlink, subprocess) are injected via
the underscore-prefixed parameters so the suite runs without the
production `gps-denied-replay` install OR a working OpenCV/pymavlink
build. The actual end-to-end run is a manual operator step (see README).
Strategy-level unit tests for the underlying ``builder.py`` machinery live
in ``test_sitl_replay_builder_builder.py``. This file exercises the
FT-P-01 scenario composition end-to-end (with all external deps mocked).
"""
from __future__ import annotations
@@ -12,378 +11,76 @@ import json
import subprocess
import types
from pathlib import Path
from typing import Sequence
from unittest.mock import MagicMock
import pytest
import e2e.fixtures.sitl_replay_builder.build_p01_fixtures as bp
import e2e.fixtures.sitl_replay_builder.build_p01_fixtures as bp01
# encode_stills_to_mp4
def _mk_fake_writer():
def _mk_fake_video_writer() -> MagicMock:
w = MagicMock(name="VideoWriter")
w.write = MagicMock()
w.release = MagicMock()
return w
def test_encode_stills_to_mp4_empty_paths_raises(tmp_path: Path):
# Assert
with pytest.raises(FileNotFoundError, match="image_paths is empty"):
bp.encode_stills_to_mp4(
[], tmp_path / "out.mp4",
_video_writer_factory=lambda *a, **kw: _mk_fake_writer(),
_imread=lambda p: None,
)
def test_encode_stills_to_mp4_writes_each_frame(tmp_path: Path):
# Arrange
writer = _mk_fake_writer()
# Simulate (640, 480, 3) BGR frame via a stand-in object with .shape
frame = types.SimpleNamespace(shape=(480, 640, 3))
paths = [tmp_path / f"img-{i}.jpg" for i in range(3)]
# Act
count = bp.encode_stills_to_mp4(
paths, tmp_path / "out.mp4",
_video_writer_factory=lambda out, w, h: writer,
_imread=lambda p: frame,
)
# Assert
assert count == 3
assert writer.write.call_count == 3
assert writer.release.call_count == 1
def test_encode_stills_to_mp4_failed_read_raises(tmp_path: Path):
# Arrange
writer = _mk_fake_writer()
frame_ok = types.SimpleNamespace(shape=(480, 640, 3))
seen: list[Path] = []
def imread(path: Path):
seen.append(path)
return None if str(path).endswith("img-1.jpg") else frame_ok
# Assert
with pytest.raises(FileNotFoundError, match="failed to read .*img-1.jpg"):
bp.encode_stills_to_mp4(
[tmp_path / f"img-{i}.jpg" for i in range(3)],
tmp_path / "out.mp4",
_video_writer_factory=lambda out, w, h: writer,
_imread=imread,
)
# generate_stationary_tlog
def test_generate_stationary_tlog_writes_pairs(tmp_path: Path):
# Arrange — fake mavlink writer that records every write() call.
writer = MagicMock(name="MavlinkWriter")
writer.write = MagicMock()
writer.close = MagicMock()
# Act
pairs = bp.generate_stationary_tlog(
tmp_path / "out.tlog",
duration_s=2, hz=10,
_mavlink_writer_factory=lambda out: writer,
)
# Assert — 20 pairs (2s * 10Hz), each pair = 2 messages (RAW_IMU + ATTITUDE)
assert pairs == 20
assert writer.write.call_count == 40
assert writer.close.call_count == 1
def test_generate_stationary_tlog_rejects_nonpositive_duration(tmp_path: Path):
# Assert
with pytest.raises(ValueError, match="duration_s must be positive"):
bp.generate_stationary_tlog(
tmp_path / "out.tlog", duration_s=0,
_mavlink_writer_factory=lambda out: MagicMock(),
)
def test_generate_stationary_tlog_rejects_nonpositive_hz(tmp_path: Path):
# Assert
with pytest.raises(ValueError, match="hz must be positive"):
bp.generate_stationary_tlog(
tmp_path / "out.tlog", hz=0,
_mavlink_writer_factory=lambda out: MagicMock(),
)
def test_generate_stationary_tlog_real_pymavlink_round_trip(tmp_path: Path):
"""Sanity-check the real packers; tlog file is well-formed."""
# Act — use real pymavlink (it's in pyproject.toml deps)
pairs = bp.generate_stationary_tlog(
tmp_path / "out.tlog", duration_s=1, hz=10,
)
# Assert
assert pairs == 10
assert (tmp_path / "out.tlog").is_file()
assert (tmp_path / "out.tlog").stat().st_size > 0
# run_gps_denied_replay
def test_run_gps_denied_replay_builds_correct_cmd(tmp_path: Path):
# Arrange
captured: list[Sequence[str]] = []
def fake_runner(cmd):
captured.append(list(cmd))
return subprocess.CompletedProcess(args=cmd, returncode=0)
# Act
bp.run_gps_denied_replay(
tmp_path / "stills.mp4", tmp_path / "stationary.tlog",
tmp_path / "fdr.jsonl",
_runner=fake_runner,
)
# Assert
assert len(captured) == 1
cmd = captured[0]
assert cmd[0] == "gps-denied-replay"
assert "--video" in cmd and str(tmp_path / "stills.mp4") in cmd
assert "--tlog" in cmd and str(tmp_path / "stationary.tlog") in cmd
assert "--time-offset-ms" in cmd and "0" in cmd
assert "--fdr-out" in cmd and str(tmp_path / "fdr.jsonl") in cmd
def test_run_gps_denied_replay_creates_fdr_parent_dir(tmp_path: Path):
# Arrange
nested = tmp_path / "deep" / "nested" / "fdr.jsonl"
# Act
bp.run_gps_denied_replay(
tmp_path / "video.mp4", tmp_path / "tlog.tlog", nested,
_runner=lambda c: subprocess.CompletedProcess(c, 0),
)
# Assert
assert nested.parent.is_dir()
def test_run_gps_denied_replay_passes_extra_args(tmp_path: Path):
# Arrange
captured: list[Sequence[str]] = []
fake_runner = lambda c: (captured.append(list(c)) or subprocess.CompletedProcess(c, 0))
# Act
bp.run_gps_denied_replay(
tmp_path / "v.mp4", tmp_path / "t.tlog", tmp_path / "fdr.jsonl",
extra_args=["--pace=ASAP", "--log-level=INFO"],
_runner=fake_runner,
)
# Assert
cmd = captured[0]
assert "--pace=ASAP" in cmd and "--log-level=INFO" in cmd
# parse_fdr_for_outbound_estimates
def _write_jsonl(path: Path, records: list[dict]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("\n".join(json.dumps(r) for r in records))
def test_parse_fdr_missing_file_raises(tmp_path: Path):
# resolve_p01_image_paths
def test_resolve_p01_image_paths_missing_dir_raises(tmp_path: Path):
# Assert
with pytest.raises(FileNotFoundError, match="FDR JSONL not found"):
bp.parse_fdr_for_outbound_estimates(tmp_path / "missing.jsonl")
with pytest.raises(FileNotFoundError, match="input dir not found"):
bp01.resolve_p01_image_paths(tmp_path / "missing")
def test_parse_fdr_filters_by_kind(tmp_path: Path):
def test_resolve_p01_image_paths_sorted(tmp_path: Path):
# Arrange
fdr = tmp_path / "fdr.jsonl"
_write_jsonl(fdr, [
{"kind": "other", "payload": {"lat_deg": 99.0, "lon_deg": 99.0}},
{"kind": "outbound_position_estimate", "payload": {"lat_deg": 1.0, "lon_deg": 2.0}},
{"kind": "another", "payload": {"x": 0}},
{"kind": "outbound_position_estimate", "payload": {"lat_deg": 3.0, "lon_deg": 4.0}},
])
for n in (3, 1, 2):
(tmp_path / f"AD{n:06d}.jpg").touch()
(tmp_path / "ignored.txt").touch()
# Act
estimates = bp.parse_fdr_for_outbound_estimates(fdr)
paths = bp01.resolve_p01_image_paths(tmp_path)
# Assert
assert estimates == [
{"lat_deg": 1.0, "lon_deg": 2.0},
{"lat_deg": 3.0, "lon_deg": 4.0},
]
# Assert — only AD*.jpg, sorted by name
assert [p.name for p in paths] == ["AD000001.jpg", "AD000002.jpg", "AD000003.jpg"]
def test_parse_fdr_skips_missing_coords(tmp_path: Path):
# Arrange
fdr = tmp_path / "fdr.jsonl"
_write_jsonl(fdr, [
{"kind": "outbound_position_estimate", "payload": {"lat_deg": 1.0}}, # missing lon
{"kind": "outbound_position_estimate", "payload": {"lon_deg": 2.0}}, # missing lat
{"kind": "outbound_position_estimate", "payload": {"lat_deg": 1.0, "lon_deg": 2.0}},
])
# Act
estimates = bp.parse_fdr_for_outbound_estimates(fdr)
# Assert
assert estimates == [{"lat_deg": 1.0, "lon_deg": 2.0}]
def test_parse_fdr_custom_kind_and_keys(tmp_path: Path):
# Arrange
fdr = tmp_path / "fdr.jsonl"
_write_jsonl(fdr, [
{"kind": "geo_estimate", "payload": {"latitude": 10.0, "longitude": 20.0}},
])
# Act
estimates = bp.parse_fdr_for_outbound_estimates(
fdr, fdr_kind="geo_estimate", lat_key="latitude", lon_key="longitude"
)
# Assert
assert estimates == [{"lat_deg": 10.0, "lon_deg": 20.0}]
def test_parse_fdr_skips_blank_lines(tmp_path: Path):
# Arrange
fdr = tmp_path / "fdr.jsonl"
fdr.write_text(
'\n'
+ json.dumps({"kind": "outbound_position_estimate",
"payload": {"lat_deg": 1.0, "lon_deg": 2.0}})
+ '\n\n'
)
# Act
estimates = bp.parse_fdr_for_outbound_estimates(fdr)
# Assert
assert len(estimates) == 1
def test_parse_fdr_malformed_json_raises(tmp_path: Path):
# Arrange
fdr = tmp_path / "fdr.jsonl"
fdr.write_text(
json.dumps({"kind": "x", "payload": {}}) + "\n"
+ "{not valid json\n"
)
# Assert
with pytest.raises(ValueError, match="malformed FDR JSON at .*:2"):
bp.parse_fdr_for_outbound_estimates(fdr)
# write_outbound_messages_fixture
def test_write_outbound_messages_length_mismatch_raises(tmp_path: Path):
# Assert
with pytest.raises(ValueError, match="length mismatch"):
bp.write_outbound_messages_fixture(
tmp_path / "out.json",
image_ids=["a.jpg", "b.jpg"],
estimates=[{"lat_deg": 1.0, "lon_deg": 2.0}],
)
def test_write_outbound_messages_preserves_nulls(tmp_path: Path):
# Arrange
out = tmp_path / "outbound.json"
# Act
bp.write_outbound_messages_fixture(
out,
image_ids=["a.jpg", "b.jpg", "c.jpg"],
estimates=[{"lat_deg": 1.0, "lon_deg": 2.0}, None, {"lat_deg": 3.0, "lon_deg": 4.0}],
)
# Assert
payload = json.loads(out.read_text())
assert payload == {
"messages": [
{"image_id": "a.jpg", "lat_deg": 1.0, "lon_deg": 2.0},
None,
{"image_id": "c.jpg", "lat_deg": 3.0, "lon_deg": 4.0},
]
}
def test_write_outbound_messages_creates_parent(tmp_path: Path):
# Arrange
out = tmp_path / "deeply" / "nested" / "outbound.json"
# Act
bp.write_outbound_messages_fixture(
out, image_ids=["a.jpg"], estimates=[{"lat_deg": 1.0, "lon_deg": 2.0}],
)
# Assert
assert out.is_file()
# write_observer_fixture
def test_write_observer_fixture_schema(tmp_path: Path):
# Arrange
out = tmp_path / "observer.json"
# Act
bp.write_observer_fixture(out)
# Assert — round-trips into the same dict consumed by sitl_observer.get_observer.
payload = json.loads(out.read_text())
assert "gps_state" in payload
assert payload["gps_state"]["primary_source"] == "MAV"
assert "parameters" in payload
# build_p01_fixtures end-to-end (mocked)
# build_p01_fixtures end-to-end
def test_build_p01_fixtures_no_images_raises(tmp_path: Path):
# Arrange
cfg = bp.BuilderConfig(
(tmp_path / "empty").mkdir()
cfg = bp01.BuilderConfig(
input_dir=tmp_path / "empty", output_dir=tmp_path / "out",
fc_kind="ardupilot", host="sitl-host",
)
(tmp_path / "empty").mkdir()
# Assert
with pytest.raises(FileNotFoundError, match="no AD\\?\\?\\?\\?\\?\\?.jpg images"):
bp.build_p01_fixtures(cfg)
bp01.build_p01_fixtures(cfg)
def test_build_p01_fixtures_end_to_end_with_mocks(tmp_path: Path):
# Arrange — synthesize 3 fake AD000NN.jpg files (one per "image"),
# mock OpenCV / pymavlink / subprocess, and pre-stage a fake FDR JSONL.
# Arrange — 3 fake AD000NN.jpg files, mocked OpenCV / pymavlink / subprocess
input_dir = tmp_path / "in"
output_dir = tmp_path / "out"
input_dir.mkdir()
for n in range(1, 4):
(input_dir / f"AD{n:06d}.jpg").touch()
writer = _mk_fake_writer()
writer = _mk_fake_video_writer()
frame = types.SimpleNamespace(shape=(480, 640, 3))
mav_writer = MagicMock(write=MagicMock(), close=MagicMock())
def fake_runner(cmd):
# Find the --fdr-out path and pre-populate it with 3 records.
fdr_path = Path(cmd[cmd.index("--fdr-out") + 1])
_write_jsonl(fdr_path, [
{"kind": "outbound_position_estimate", "payload": {"lat_deg": 1.0, "lon_deg": 2.0}},
@@ -392,13 +89,13 @@ def test_build_p01_fixtures_end_to_end_with_mocks(tmp_path: Path):
])
return subprocess.CompletedProcess(cmd, 0)
cfg = bp.BuilderConfig(
cfg = bp01.BuilderConfig(
input_dir=input_dir, output_dir=output_dir,
fc_kind="ardupilot", host="sitl-host",
)
# Act
result_dir = bp.build_p01_fixtures(
result_dir = bp01.build_p01_fixtures(
cfg,
_runner=fake_runner,
_video_writer_factory=lambda out, w, h: writer,
@@ -420,7 +117,7 @@ def test_build_p01_fixtures_end_to_end_with_mocks(tmp_path: Path):
def test_build_p01_fixtures_fewer_estimates_than_frames_pads_nulls(tmp_path: Path):
# Arrange — 3 frames, FDR yields 1 estimate; expect 2 null entries.
# Arrange — 3 frames, FDR yields 1 estimate; expect 2 null entries
input_dir = tmp_path / "in"
output_dir = tmp_path / "out"
input_dir.mkdir()
@@ -434,16 +131,16 @@ def test_build_p01_fixtures_fewer_estimates_than_frames_pads_nulls(tmp_path: Pat
])
return subprocess.CompletedProcess(cmd, 0)
cfg = bp.BuilderConfig(
cfg = bp01.BuilderConfig(
input_dir=input_dir, output_dir=output_dir,
fc_kind="ardupilot", host="sitl-host",
)
# Act
bp.build_p01_fixtures(
bp01.build_p01_fixtures(
cfg,
_runner=fake_runner,
_video_writer_factory=lambda out, w, h: _mk_fake_writer(),
_video_writer_factory=lambda out, w, h: _mk_fake_video_writer(),
_imread=lambda p: types.SimpleNamespace(shape=(480, 640, 3)),
_mavlink_writer_factory=lambda out: MagicMock(write=MagicMock(), close=MagicMock()),
)
@@ -456,7 +153,7 @@ def test_build_p01_fixtures_fewer_estimates_than_frames_pads_nulls(tmp_path: Pat
def test_build_p01_fixtures_more_estimates_than_frames_truncates(tmp_path: Path, caplog):
# Arrange — 2 frames, FDR yields 4 estimates; expect 2 retained + warn.
# Arrange — 2 frames, FDR yields 4 estimates; expect 2 retained + WARN
input_dir = tmp_path / "in"
output_dir = tmp_path / "out"
input_dir.mkdir()
@@ -471,17 +168,17 @@ def test_build_p01_fixtures_more_estimates_than_frames_truncates(tmp_path: Path,
])
return subprocess.CompletedProcess(cmd, 0)
cfg = bp.BuilderConfig(
cfg = bp01.BuilderConfig(
input_dir=input_dir, output_dir=output_dir,
fc_kind="ardupilot", host="sitl-host",
)
# Act
with caplog.at_level("WARNING"):
bp.build_p01_fixtures(
bp01.build_p01_fixtures(
cfg,
_runner=fake_runner,
_video_writer_factory=lambda out, w, h: _mk_fake_writer(),
_video_writer_factory=lambda out, w, h: _mk_fake_video_writer(),
_imread=lambda p: types.SimpleNamespace(shape=(480, 640, 3)),
_mavlink_writer_factory=lambda out: MagicMock(write=MagicMock(), close=MagicMock()),
)