Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
21.9 KB
Raw Blame
"""Forward geocoding (/api/geo/geocode): Nominatim behind a mock, never the network."""

import math

import pytest

from azimut.api import satellite
from azimut.engine import geo

# The suite's autouse fixture replaces geo.reverse_geocode with an offline stub,
# so the two tests below — the ones that care about what goes out on the wire —
# hold on to the real function, captured at import time.
_REAL_REVERSE = geo.reverse_geocode


class _FakeResponse:
    def __init__(self, payload):
        self._payload = payload

    def raise_for_status(self):
        pass

    def json(self):
        return self._payload


def _fake_get(payload):
    calls = {}

    def fake(url, params=None, headers=None, timeout=None):
        calls["url"] = url
        calls["params"] = params
        calls["headers"] = headers
        return _FakeResponse(payload)

    return fake, calls


def test_geocode_returns_top_match(client, monkeypatch):
    fake, calls = _fake_get(
        [{"lat": "48.8584", "lon": "2.2945", "display_name": "Tour Eiffel, Paris, France"}]
    )
    monkeypatch.setattr(geo.httpx, "get", fake)

    result = client.get("/api/geo/geocode", params={"q": "tour eiffel"}).json()
    assert result["lat"] == 48.8584
    assert result["lon"] == 2.2945
    assert result["display_name"] == "Tour Eiffel, Paris, France"
    assert "OpenStreetMap" in result["attribution"]
    # polite Nominatim usage: identified UA, single result requested
    assert calls["params"]["q"] == "tour eiffel"
    assert calls["params"]["limit"] == 1
    assert calls["headers"]["User-Agent"]


def test_geocode_answers_in_english(client, monkeypatch):
    # the query goes out in whatever language it was typed; only the answer is
    # pinned, so "Москва" comes back as a name the analyst can read
    fake, calls = _fake_get([{"lat": "55.75", "lon": "37.61", "display_name": "Moscow, Russia"}])
    monkeypatch.setattr(geo.httpx, "get", fake)

    result = client.get("/api/geo/geocode", params={"q": "Москва"}).json()
    assert calls["params"]["q"] == "Москва"
    assert calls["params"]["accept-language"] == "en"
    assert result["display_name"] == "Moscow, Russia"


def test_reverse_stays_in_the_local_language(monkeypatch):
    # the Post and Proof composers read this endpoint and name a place the way
    # it is named where it is — asking for English here would change their copy
    fake, calls = _fake_get({"display_name": "Москва, Россия", "address": {"country": "Россия"}})
    monkeypatch.setattr(geo.httpx, "get", fake)

    result = _REAL_REVERSE(55.75, 37.61)
    assert "accept-language" not in calls["params"]
    assert result["display_name"] == "Москва, Россия"


def test_reverse_asks_for_a_language_only_when_told_to(monkeypatch):
    fake, calls = _fake_get({"display_name": "Moscow, Russia", "address": {}})
    monkeypatch.setattr(geo.httpx, "get", fake)

    _REAL_REVERSE(55.75, 37.61, language="en")
    assert calls["params"]["accept-language"] == "en"


def test_geocode_no_match_is_404(client, monkeypatch):
    fake, _ = _fake_get([])
    monkeypatch.setattr(geo.httpx, "get", fake)
    response = client.get("/api/geo/geocode", params={"q": "zzzz nowhere zzzz"})
    assert response.status_code == 404


def test_geocode_empty_query_is_422(client):
    response = client.get("/api/geo/geocode", params={"q": "   "})
    assert response.status_code == 422


def test_geocode_reads_a_coordinate_without_the_network(client, monkeypatch):
    """A Sheet cell already holding coordinates is a point, not a place name to send out."""
    calls = []
    monkeypatch.setattr(geo.httpx, "get", lambda *a, **k: calls.append(k) or _FakeResponse([]))

    body = client.get("/api/geo/geocode", params={"q": "50.4501, 30.5234"}).json()

    assert body == {"lat": 50.4501, "lon": 30.5234, "display_name": None, "attribution": None}
    assert calls == []


def test_geocode_network_failure_is_404(client, monkeypatch):
    def boom(*args, **kwargs):
        raise OSError("network down")

    monkeypatch.setattr(geo.httpx, "get", boom)
    # engine swallows the error (best-effort) → API reports no match
    response = client.get("/api/geo/geocode", params={"q": "paris"})
    assert response.status_code == 404


# -- /api/geo/parse: pure offline conversion, no network -------------------------------


def test_parse_returns_every_format(client):
    result = client.post("/api/geo/parse", json={"text": "48.8583701, 2.2944813"}).json()
    assert result["lat"] == pytest.approx(48.8583701)
    assert result["lon"] == pytest.approx(2.2944813)
    # flat keys the Post Composer reads by name stay in place
    assert result["dms"].endswith('E')
    assert "+" in result["plus_code"]
    # the ordered list the Coordinates tool renders
    assert [f["id"] for f in result["formats"]] == [
        "dd", "ddm", "dms", "utm", "mgrs", "plus_code", "geohash",
    ]
    # map links are built in the browser (lib/maplinks.js), from one verified table
    assert "links" not in result


def test_parse_accepts_the_formats_it_emits(client):
    for text in ("31U 448251 5411952", "u09tunqu9", "48°51.502'N 2°17.669'E"):
        response = client.post("/api/geo/parse", json={"text": text})
        assert response.status_code == 200, text
        body = response.json()
        assert body["lat"] == pytest.approx(48.858, abs=1e-2)
        assert body["lon"] == pytest.approx(2.294, abs=1e-2)


def test_parse_rejects_gibberish_with_422(client):
    assert client.post("/api/geo/parse", json={"text": "hello world"}).status_code == 422


# -- /api/geo/sky ---------------------------------------------------------------
#
# The geometry itself is covered in tests/test_sky.py. What matters here is the
# contract the panel reads: local and UTC side by side, states instead of errors,
# a curve that spans the day, and validation at the edge.


def test_sky_reports_every_instant_in_local_time_and_utc(client):
    response = client.get(
        "/api/geo/sky",
        params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30", "time": "14:20"},
    )
    assert response.status_code == 200
    body = response.json()
    assert body["zone"]["name"] == "Europe/Paris"
    assert body["zone"]["abbreviation"] == "CEST"
    assert body["moment"]["local"].startswith("2026-07-30T14:20")
    assert body["moment"]["utc"] == "2026-07-30T12:20:00Z"
    for stamp in (body["sun"]["rise"], body["sun"]["set"], body["sun"]["transit"]):
        assert stamp["utc"].endswith("Z")
        assert stamp["offset"] == "+02:00"
        assert stamp["abbreviation"] == "CEST"


def test_sky_gives_the_positions_at_the_moment_asked_for(client):
    response = client.get(
        "/api/geo/sky",
        params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30", "time": "14:20"},
    )
    body = response.json()
    assert 180 < body["sun"]["azimuth"] < 220  # early afternoon, past due south
    assert body["sun"]["altitude"] > 50
    assert 0 <= body["moon"]["illuminated"] <= 1
    assert body["moon"]["phase"]
    assert isinstance(body["moon"]["waxing"], bool)
    assert body["moon"]["distance_km"] > 300_000


def test_sky_defaults_to_local_midday_today(client):
    """No date and no time: the point's own today, read at local noon."""
    body = client.get("/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945}).json()
    assert body["moment"]["local"][11:16] == "12:00"
    assert body["date"] == body["moment"]["local"][:10]


def test_sky_reports_the_midnight_sun_as_a_state(client):
    body = client.get(
        "/api/geo/sky", params={"lat": 69.6492, "lon": 18.9553, "date": "2026-06-21"}
    ).json()
    assert body["sun"]["state"] == "always_up"
    assert body["sun"]["rise"] is None
    assert body["sun"]["set"] is None
    assert body["sun"]["transit_altitude"] > 40


def test_sky_reports_polar_night_as_a_state(client):
    body = client.get(
        "/api/geo/sky", params={"lat": -89.0, "lon": 0.0, "date": "2026-06-21"}
    ).json()
    assert body["sun"]["state"] == "always_down"
    assert body["twilight"]["astronomical"]["state"] == "always_down"


def test_sky_carries_the_moon_events_as_lists(client):
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30"}
    ).json()
    assert isinstance(body["moon"]["rises"], list)
    assert len(body["moon"]["rise_azimuths"]) == len(body["moon"]["rises"])
    assert len(body["moon"]["set_azimuths"]) == len(body["moon"]["sets"])


def test_sky_curve_spans_the_day_in_minutes_from_local_midnight(client):
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30"}
    ).json()
    curve = body["curve"]
    assert curve["minutes"][0] == 0
    assert curve["minutes"][-1] == 1440
    for key in ("sun_altitude", "sun_azimuth", "moon_altitude", "moon_azimuth"):
        assert len(curve[key]) == len(curve["minutes"])


def test_sky_curve_follows_a_daylight_saving_day(client):
    """The x axis is minutes of the local day, so it is 23 hours long in March."""
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-03-29"}
    ).json()
    assert body["curve"]["minutes"][-1] == 1380
    assert body["zone"]["abbreviation"] == "CEST"


def test_sky_curve_carries_the_wall_clock_of_each_sample(client):
    """Anything that labels a sample to the reader reads this, because the wall
    clock cannot be divided out of the minute count."""
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30"}
    ).json()
    curve = body["curve"]
    assert len(curve["clock"]) == len(curve["minutes"])
    assert curve["clock"][0] == "00:00"
    assert curve["clock"][6] == "01:00"
    assert curve["clock"][-1] == "00:00"  # the following midnight


def test_sky_clock_skips_the_hour_daylight_saving_took(client):
    """On the spring-forward day the local clock jumps from 02:00 to 03:00, so no
    sample reads 02:xx while the minute count runs straight through."""
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-03-29"}
    ).json()
    curve = body["curve"]
    assert not [stamp for stamp in curve["clock"] if stamp.startswith("02:")]
    assert "03:00" in curve["clock"]
    # the sample two hours of elapsed time in reads 03:00, not 02:00
    assert curve["clock"][curve["minutes"].index(120)] == "03:00"


def test_sky_clock_repeats_the_hour_daylight_saving_gave_back(client):
    """And on the autumn day 02:00 to 03:00 happens twice."""
    body = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-10-25"}
    ).json()
    assert body["curve"]["clock"].count("02:00") == 2


def test_sky_accepts_a_zone_override(client):
    body = client.get(
        "/api/geo/sky",
        params={
            "lat": 48.8584,
            "lon": 2.2945,
            "date": "2026-07-30",
            "time": "12:00",
            "zone": "UTC",
        },
    ).json()
    assert body["zone"]["name"] == "UTC"
    assert body["moment"]["utc"] == "2026-07-30T12:00:00Z"


@pytest.mark.parametrize("zone", ["Mars/Olympus", "../../../etc/passwd", "A" * 5000])
def test_sky_refuses_a_zone_it_cannot_load(client, zone):
    """Rather than answering in UTC under the name that was asked for, which would
    put every time in the response an offset out with nothing saying so."""
    response = client.get(
        "/api/geo/sky",
        params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30", "zone": zone},
    )
    assert response.status_code == 422


@pytest.mark.parametrize(
    "params",
    [
        {"lat": 91, "lon": 0},
        {"lat": 0, "lon": 181},
        {"lat": 0, "lon": 0, "date": "30-07-2026"},
        {"lat": 0, "lon": 0, "time": "25h"},
    ],
)
def test_sky_validates_at_the_edge(client, params):
    assert client.get("/api/geo/sky", params=params).status_code == 422


# -- /api/geo/zone --------------------------------------------------------------


@pytest.mark.parametrize(
    ("lat", "lon", "name"),
    [(49.99, 36.23, "Europe/Kyiv"), (40.71, -74.0, "America/New_York"), (-90, 0, "UTC")],
)
def test_zone_names_the_civil_zone_at_a_point(client, lat, lon, name):
    response = client.get("/api/geo/zone", params={"lat": lat, "lon": lon})
    assert response.status_code == 200
    # The name alone: the offset belongs to an instant, which the browser holds.
    assert response.json() == {"name": name}


@pytest.mark.parametrize("params", [{"lat": 91, "lon": 0}, {"lat": 0, "lon": 181}, {"lat": 0}])
def test_zone_validates_at_the_edge(client, params):
    assert client.get("/api/geo/zone", params=params).status_code == 422


# -- /api/geo/daylight ----------------------------------------------------------
#
# The geometry is covered in tests/test_sky.py. What matters here is the contract the
# Timeline reads: the point's own civil zone beside the spans, UTC instants whatever
# clock the axis is labelled with, and a window too wide answered as cut rather than
# paid for.


def test_daylight_carries_the_spans_and_the_point_s_own_zone(client):
    response = client.get(
        "/api/geo/daylight",
        params={
            "lat": 50.45, "lon": 30.52,
            "from": "2026-06-20T00:00:00Z", "to": "2026-06-22T00:00:00Z",
        },
    )
    assert response.status_code == 200
    body = response.json()
    assert body["zone"]["name"] == "Europe/Kyiv"
    assert body["zone"]["abbreviation"] == "EEST"
    assert body["zone"]["offset_minutes"] == 180
    assert body["truncated"] is False
    assert len(body["day"]) == 2
    for span in body["day"]:
        assert span["from"].endswith("Z") and span["to"].endswith("Z")
    # dusk is not a line, so the two runs are both given and civil encloses the day
    assert body["civil"][0]["from"] < body["day"][0]["from"]


def test_daylight_says_a_window_was_too_wide_rather_than_paying_for_it(client):
    body = client.get(
        "/api/geo/daylight",
        params={
            "lat": 50.45, "lon": 30.52,
            "from": "2026-01-01T00:00:00Z", "to": "2027-01-01T00:00:00Z",
        },
    ).json()
    assert body["truncated"] is True
    assert body["day"] == [] and body["civil"] == []
    # the zone still answers: it is what the axis is labelled with, and it costs
    # nothing to work out
    assert body["zone"]["name"] == "Europe/Kyiv"


@pytest.mark.parametrize(
    "params",
    [
        {"lat": 91, "lon": 0, "from": "2026-06-20T00:00:00Z", "to": "2026-06-21T00:00:00Z"},
        {"lat": 0, "lon": 0, "from": "yesterday", "to": "2026-06-21T00:00:00Z"},
        {"lat": 0, "lon": 0, "from": "2026-06-21T00:00:00Z", "to": "2026-06-20T00:00:00Z"},
        {"lat": 0, "lon": 0, "from": "2026-06-21T00:00:00Z"},
    ],
)
def test_daylight_validates_at_the_edge(client, params):
    assert client.get("/api/geo/daylight", params=params).status_code == 422


def test_daylight_does_not_touch_the_network(monkeypatch):
    import socket

    def explode(*args, **kwargs):
        raise AssertionError("daylight must be computed offline")

    monkeypatch.setattr(socket, "socket", explode)
    monkeypatch.setattr(socket, "create_connection", explode)
    body = satellite.daylight_for_window(
        lat=48.8584,
        lon=2.2945,
        start="2026-07-30T00:00:00Z",
        end="2026-07-31T00:00:00Z",
    )
    assert len(body["day"]) == 1


def test_sky_never_touches_the_network(client, monkeypatch):
    """Opening the panel must not phone out. The reverse geocode beside it in the
    same tool does; this route is pure computation, and stays that way."""
    import httpx

    def explode(*args, **kwargs):
        raise AssertionError("the sky is computed locally")

    monkeypatch.setattr(httpx.Client, "get", explode)
    monkeypatch.setattr(httpx.Client, "send", explode)
    response = client.get(
        "/api/geo/sky", params={"lat": 48.8584, "lon": 2.2945, "date": "2026-07-30"}
    )
    assert response.status_code == 200


# -- /api/geo/suggest: the search bar's instant layer, offline by construction ---------


def test_suggest_offers_cities_without_touching_the_network(client, monkeypatch):
    def explode(*args, **kwargs):
        raise AssertionError("a keystroke must never reach the geocoder")

    monkeypatch.setattr(geo.httpx, "get", explode)

    body = client.get("/api/geo/suggest", params={"q": "krama"}).json()
    assert body["cities"][0]["name"] == "Kramatorsk"
    assert body["cities"][0]["country_name"] == "Ukraine"
    assert "GeoNames" in body["attribution"]
    assert body["coords"] is None


def test_suggest_recognizes_coordinates_as_they_are_typed(client):
    body = client.get("/api/geo/suggest", params={"q": "50.4501, 30.5234"}).json()
    assert body["coords"] == {"lat": 50.4501, "lon": 30.5234}
    # a coordinate is not a place name, so the gazetteer stays quiet
    assert body["cities"] == []


def test_suggest_honors_the_limit_and_survives_an_empty_query(client):
    assert len(client.get("/api/geo/suggest", params={"q": "s", "limit": 3}).json()["cities"]) == 3
    blank = client.get("/api/geo/suggest", params={"q": "  "}).json()
    assert blank == {"coords": None, "cities": [], "attribution": None}


# -- /api/geo/places: the slow layer, dropped rather than queued -----------------------


def test_places_returns_several_matches(client, monkeypatch):
    fake, calls = _fake_get(
        [
            {"lat": "48.8584", "lon": "2.2945", "display_name": "Tour Eiffel, Paris", "type": "attraction"},
            {"lat": "48.86", "lon": "2.29", "display_name": "Rue de la Tour, Paris", "type": "road"},
        ]
    )
    monkeypatch.setattr(geo.httpx, "get", fake)

    body = client.get("/api/geo/places", params={"q": "tour eiffel"}).json()
    assert [place["display_name"] for place in body["places"]] == [
        "Tour Eiffel, Paris",
        "Rue de la Tour, Paris",
    ]
    assert body["places"][1]["kind"] == "road"
    assert body["busy"] is False
    assert "OpenStreetMap" in body["attribution"]
    assert calls["params"]["limit"] == 10  # one request feeds any limit the UI asks for


def test_places_is_dropped_rather_than_queued_when_the_pace_is_held(client, monkeypatch):
    fake, _ = _fake_get([{"lat": "1", "lon": "2", "display_name": "Somewhere"}])
    monkeypatch.setattr(geo.httpx, "get", fake)

    assert client.get("/api/geo/places", params={"q": "first"}).json()["busy"] is False
    # a second query inside the one-per-second floor waits for nothing: it says so
    second = client.get("/api/geo/places", params={"q": "second"}).json()
    assert second == {"places": [], "busy": True, "throttled": False, "attribution": None}


def test_places_answers_a_repeated_query_from_memory(client, monkeypatch):
    calls = []

    def counting(url, params=None, headers=None, timeout=None):
        calls.append(params["q"])
        return _FakeResponse([{"lat": "50.45", "lon": "30.52", "display_name": "Kyiv"}])

    monkeypatch.setattr(geo.httpx, "get", counting)

    first = client.get("/api/geo/places", params={"q": "kyiv"}).json()
    # inside the pace floor, and still answered — the cache spends no slot
    again = client.get("/api/geo/places", params={"q": " KYIV "}).json()
    assert again["places"] == first["places"] and again["busy"] is False
    assert calls == ["kyiv"]


def test_places_reports_a_throttled_geocoder_instead_of_an_empty_list(client, monkeypatch):
    class _Throttled(_FakeResponse):
        status_code = 429

        def raise_for_status(self):
            raise RuntimeError("429")

    monkeypatch.setattr(geo.httpx, "get", lambda *a, **k: _Throttled([]))
    assert client.get("/api/geo/places", params={"q": "paris"}).json()["busy"] is True

    # the 429 is remembered for a minute, so the next query is refused before it
    # is even sent — and says why, rather than looking like "no such place"
    body = client.get("/api/geo/places", params={"q": "lyon"}).json()
    assert body["busy"] is True and body["throttled"] is True


def test_places_empty_query_is_422(client):
    assert client.get("/api/geo/places", params={"q": "   "}).status_code == 422


def test_places_never_sends_a_typed_coordinate_to_the_geocoder(client, monkeypatch):
    """A search bar left alone past its debounce asked Nominatim for "50.4501, 30.5234"."""
    calls = []
    monkeypatch.setattr(geo.httpx, "get", lambda *a, **k: calls.append(k) or _FakeResponse([]))

    for typed in ("50.4501, 30.5234", "50°27'00.4\"N 30°31'24.2\"E", "36SYC8418406297"):
        body = client.get("/api/geo/places", params={"q": typed}).json()
        assert body == {"places": [], "busy": False, "throttled": False, "attribution": None}
    assert calls == []


# -- /api/geo/shadow -------------------------------------------------------------


def test_a_shadow_gives_the_hour_and_the_height_of_what_cast_it(client):
    from datetime import UTC, datetime

    from azimut.engine import sky

    when = datetime(2024, 6, 21, 8, 0, tzinfo=UTC)
    sun = sky.position_at(48.8584, 2.2945, when)
    shadow = (sun["sun_azimuth"] + 180.0) % 360.0
    answer = client.get("/api/geo/shadow", params={
        "lat": 48.8584, "lon": 2.2945, "date": "2024-06-21", "bearing": shadow, "length": 50,
    }).json()
    assert answer["zone"] == "Europe/Paris"
    [moment] = answer["moments"]
    assert moment["utc"].startswith("2024-06-21T08:00")
    assert moment["local"].startswith("2024-06-21T10:00")
    altitude = sun["sun_apparent_altitude"]
    assert moment["sun_altitude"] == pytest.approx(altitude, abs=0.01)
    assert moment["height_m"] == pytest.approx(50 * math.tan(math.radians(altitude)), abs=0.1)


def test_a_shadow_no_hour_could_throw_has_no_moment(client):
    answer = client.get("/api/geo/shadow", params={
        "lat": 48.8584, "lon": 2.2945, "date": "2024-06-21", "bearing": 180, "length": 50,
    }).json()
    assert answer["moments"] == []


@pytest.mark.parametrize("params", [
    {"date": "21/06/2024", "bearing": 10, "length": 5},
    {"date": "2024-06-21", "bearing": 400, "length": 5},
    {"date": "2024-06-21", "bearing": 10, "length": 0},
])
def test_a_shadow_refuses_what_it_cannot_read(client, params):
    assert client.get("/api/geo/shadow", params={"lat": 48.8, "lon": 2.3, **params}).status_code == 422