Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

8.8 KB
Raw Blame
from copy import deepcopy
import json
from pathlib import Path

import pytest

from dopplergeist.contracts import (
    event_measure_settings, validate_candidate, validate_event, validate_recording,
    validate_request, validate_result,
)


EXAMPLES = Path(__file__).resolve().parents[1] / "docs/examples"


def example(name):
    return json.loads((EXAMPLES / f"{name}.json").read_text())


def test_examples_roundtrip_without_mutating_inputs():
    for name, validator in (("analysis-request", validate_request), ("detected-event", validate_event),
                            ("job-result", validate_result), ("job-needs-input", validate_result)):
        original = example(name)
        before = deepcopy(original)
        clean = validator(original)
        assert validator(json.loads(json.dumps(clean, allow_nan=False))) == clean
        assert original == before
    request = {"schema_version": 1, "audio_path": "clip.mp3"}
    assert validate_request(request)["search"] == {"coverage": "conus"}
    assert "time_window" not in validate_request(request)


def test_time_window_is_recording_start_with_explicit_timezone():
    request = example("analysis-request")
    request["time_window"].update(start_utc="2026-09-08T12:00:00+02:00", end_utc="2026-09-08T10:00:00Z")
    assert validate_request(request)["time_window"]["start_utc"] == "2026-09-08T10:00:00Z"
    for invalid in ("2026-09-08", "2026-09-08T12:00:00", 1788861600):
        request["time_window"]["start_utc"] = invalid
        with pytest.raises(ValueError):
            validate_request(request)


@pytest.mark.parametrize("change", [
    {"schema_version": True}, {"schema_version": 2}, {"audio_path": ""},
    {"true_lat": 40.0}, {"events": []}, {"search": {"coverage": "global"}},
    {"search": {"coverage": "conus", "bounds_wsen": [-100, 40, -110, 45]}},
    {"search": {"coverage": "conus", "bounds_wsen": [-110, 40, float("nan"), 45]}},
])
def test_invalid_request_and_truth_fields_rejected(change):
    request = example("analysis-request")
    request.update(change)
    with pytest.raises(ValueError):
        validate_request(request)


def test_spain_request_accepts_real_madrid_region_and_requires_country_consistency():
    request = {"schema_version": 1, "audio_path": "recording.mp3",
               "search": {"country": "ES", "coverage": "spain",
                          "bounds_wsen": [-4.16, 40.05, -2.97, 40.95]}}
    clean = validate_request(request)
    assert clean["search"] == request["search"]

    request["search"]["coverage"] = "germany"
    with pytest.raises(ValueError, match="requires coverage spain"):
        validate_request(request)


def test_spain_request_rejects_bounds_outside_profile_envelope():
    request = {"schema_version": 1, "audio_path": "recording.mp3",
               "search": {"country": "ES", "bounds_wsen": [-20.0, 40.0, -3.0, 41.0]}}
    with pytest.raises(ValueError, match="must stay within Spain"):
        validate_request(request)


def test_untrusted_time_source_and_reversed_window_rejected():
    request = example("analysis-request")
    request["time_window"]["source"] = "file_mtime"
    with pytest.raises(ValueError, match="Time source"):
        validate_request(request)
    request["time_window"]["source"] = "user"
    request["time_window"]["start_utc"] = "2026-09-10T00:00:00Z"
    with pytest.raises(ValueError, match="reversed"):
        validate_request(request)


def test_ridge_time_and_frequency_are_recording_relative():
    event = example("detected-event")
    event["start_s"] = 100
    event["end_s"] = 160
    with pytest.raises(ValueError):
        validate_event(event)  # Chunk-local points were not shifted by +90 s.
    for point in event["ridge"]:
        point["time_s"] += 90
    validate_event(event)
    settings = event_measure_settings(event)
    assert settings["start_s"] == 100
    assert settings["band_hz"] == [80.0, 180.0]
    assert "ridge" not in settings and "quality" not in settings
    assert "f0_range_hz" not in settings  # No invented rest-frequency bounds.


@pytest.mark.parametrize("field,value", [("time_s", 40.0), ("frequency_hz", float("inf")), ("weight", -1)])
def test_invalid_ridge_samples_rejected(field, value):
    event = example("detected-event")
    event["ridge"][0][field] = value
    with pytest.raises(ValueError):
        validate_event(event)


def test_recording_metadata_labels_decoded_samples_and_source_hash():
    metadata = {"source_sha256": "a" * 64, "duration_s": 60, "sample_rate_hz": 4000,
                "channels": 1, "source_format": "mp3"}
    assert validate_recording(metadata) == metadata
    for change in ({"source_sha256": "missing"}, {"duration_s": 0}, {"channels": True}):
        with pytest.raises(ValueError):
            validate_recording(dict(metadata, **change))


def test_uncalibrated_radius_is_not_a_probability():
    candidate = example("job-result")["candidates"][0]
    candidate["uncertainty"]["coverage_probability"] = 0.95
    with pytest.raises(ValueError, match="Uncalibrated"):
        validate_candidate(candidate)
    candidate["uncertainty"]["kind"] = "calibrated"
    with pytest.raises(ValueError, match="calibration_reference"):
        validate_candidate(candidate)
    candidate["uncertainty"]["calibration_reference"] = "evaluation/heldout-report.json"
    validate_candidate(candidate)


def test_job_decisions_require_support_or_explanations():
    result = {"schema_version": 1, "job_id": "job", "status": "succeeded"}
    with pytest.raises(ValueError, match="requires a candidate"):
        validate_result(result)
    for status in ("inconclusive", "failed", "needs_input"):
        result["status"] = status
        with pytest.raises(ValueError):
            validate_result(result)
    result = example("job-needs-input")
    del result["required_fields"]
    with pytest.raises(ValueError, match="required_fields"):
        validate_result(result)


def test_ranked_candidates_must_be_comparable_and_reference_real_events():
    result = example("job-result")
    result["candidates"][0]["event_ids"] = ["absent-event"]
    with pytest.raises(ValueError, match="absent event"):
        validate_result(result)
    result = example("job-result")
    result["candidates"].append(deepcopy(result["candidates"][0]))
    result["candidates"][1]["score_kind"] = "unrelated_score"
    with pytest.raises(ValueError, match="comparable"):
        validate_result(result)
    result["candidates"][1]["score_kind"] = result["candidates"][0]["score_kind"]
    result["candidates"][1]["score"] = 100
    with pytest.raises(ValueError, match="descending"):
        validate_result(result)


def test_coverage_distinguishes_finished_search_from_available_data():
    result = example("job-result")
    result["coverage"] = {"search_complete": False, "data_status": "available",
                          "limitations": ["Only one tile searched; ADS-B capture can miss aircraft."]}
    assert validate_result(result)["coverage"]["search_complete"] is False
    result["coverage"]["search_complete"] = "yes"
    with pytest.raises(ValueError, match="Coverage"):
        validate_result(result)


@pytest.mark.parametrize("path", ["../other-job/file.json", "/etc/passwd", "C:\\private\\file", "nested/../../file"])
def test_artifact_paths_cannot_leave_job_directory(path):
    result = example("job-result")
    result["artifacts"]["report"] = path
    with pytest.raises(ValueError, match="relative"):
        validate_result(result)


def test_review_exclusions_are_optional_and_auditable():
    request = {"schema_version": 1, "audio_path": "clip.mp3",
               "excluded_event_ids": ["event-2", "event-1"], "review_source_job_id": "a" * 32}
    clean = validate_request(request)
    assert clean["excluded_event_ids"] == ["event-1", "event-2"]
    assert clean["review_source_job_id"] == "a" * 32
    assert "excluded_event_ids" not in validate_request({"schema_version": 1, "audio_path": "clip.mp3"})
    for change in ({"excluded_event_ids": []}, {"excluded_event_ids": ["event-1", "event-1"]},
                   {"excluded_event_ids": ["event-1"], "review_source_job_id": "not-a-job"},
                   {"review_source_job_id": "a" * 32}):
        invalid = {"schema_version": 1, "audio_path": "clip.mp3", **change}
        with pytest.raises(ValueError):
            validate_request(invalid)

    result = example("job-result")
    result["review"] = {"user_assisted": True, "excluded_event_ids": ["event-1"],
                        "source_job_id": "b" * 32}
    assert validate_result(result)["review"]["user_assisted"] is True
    for review in ({"user_assisted": False, "excluded_event_ids": ["event-1"]},
                   {"user_assisted": True, "excluded_event_ids": []},
                   {"user_assisted": True, "excluded_event_ids": ["event-1"],
                    "source_job_id": "../other"}):
        invalid = example("job-result")
        invalid["review"] = review
        with pytest.raises(ValueError):
            validate_result(invalid)