fix: address PR review feedback

- Remove .gitlab-ci.yml (duplicative with Gitea Actions workflow)
- Add lookup_geo() unit tests with mocked MaxMind reader (4 tests)
- Expand README.md Testing section with backend/frontend/CI docs
- Add CLAUDE.md with test framework documentation

backend/tests/test_log_parser.py

@@ -3,8 +3,14 @@
 import os
 import tempfile
 import pytest
+from unittest.mock import patch, MagicMock
 
-from app.log_parser import parse_log_line, resolve_client_ip, _COUNTRY_CENTROIDS
+from app.log_parser import (
+    parse_log_line,
+    resolve_client_ip,
+    _COUNTRY_CENTROIDS,
+    lookup_geo,
+)
 
 
 class TestParseLogLine:
@@ -138,3 +144,84 @@ class TestParseLogFile:
         result = parse_log_file(str(log_file))
         assert "203.0.113.1" in result["unique_ips"]
         assert "10.0.0.1" not in result["unique_ips"]
+
+
+class TestLookupGeo:
+    """Tests for lookup_geo() — verify IPs map to countries via our APIs."""
+
+    def _reset_geo_reader(self):
+        """Clear the cached reader so mocks take effect."""
+        import app.log_parser as lp
+
+        lp._geo_reader = None
+
+    @patch("app.log_parser.settings")
+    def test_ip_maps_to_country(self, mock_settings):
+        """Verify a known IP resolves to a country code via the GeoLite2 reader."""
+        self._reset_geo_reader()
+        mock_settings.GEOLITE2_DB_PATH = "/tmp/fake-geo.mmdb"
+
+        # Create a fake reader that returns US data
+        fake_reader = MagicMock()
+        fake_reader.get.return_value = {
+            "country": {"iso_code": "US", "names": {"en": "United States"}},
+            "city": {"names": {"en": "New York"}},
+            "location": {"latitude": 40.7128, "longitude": -74.006},
+        }
+
+        with patch("maxminddb.open_database", return_value=fake_reader):
+            result = lookup_geo("8.8.8.8")
+
+        assert result["country_code"] == "US"
+        assert result["country"] == "United States"
+        assert result["city"] == "New York"
+        assert result["latitude"] == 40.7128
+        assert result["longitude"] == -74.006
+
+    @patch("app.log_parser.settings")
+    def test_ip_without_coordinates_uses_centroid_fallback(self, mock_settings):
+        """When the free GeoLite2 DB lacks coordinates, centroid fallback kicks in."""
+        self._reset_geo_reader()
+        mock_settings.GEOLITE2_DB_PATH = "/tmp/fake-geo.mmdb"
+
+        # Simulate free GeoLite2 response — has country but no coordinates
+        fake_reader = MagicMock()
+        fake_reader.get.return_value = {
+            "country": {"iso_code": "DE", "names": {"en": "Germany"}},
+            "city": {"names": {"en": ""}},
+            "location": {},  # No lat/lon
+        }
+
+        with patch("maxminddb.open_database", return_value=fake_reader):
+            result = lookup_geo("1.1.1.1")
+
+        assert result["country_code"] == "DE"
+        assert result["country"] == "Germany"
+        # Falls back to _COUNTRY_CENTROIDS["DE"]
+        assert result["latitude"] == _COUNTRY_CENTROIDS["DE"][0]
+        assert result["longitude"] == _COUNTRY_CENTROIDS["DE"][1]
+
+    @patch("app.log_parser.settings")
+    def test_unknown_ip_returns_empty_dict(self, mock_settings):
+        """An IP not in the database returns an empty dict."""
+        self._reset_geo_reader()
+        mock_settings.GEOLITE2_DB_PATH = "/tmp/fake-geo.mmdb"
+
+        fake_reader = MagicMock()
+        fake_reader.get.return_value = None
+
+        with patch("maxminddb.open_database", return_value=fake_reader):
+            result = lookup_geo("255.255.255.255")
+
+        assert result == {}
+
+    @patch("app.log_parser.settings")
+    def test_reader_error_returns_empty_dict(self, mock_settings):
+        """When the reader raises an exception, lookup_geo() returns safely."""
+        self._reset_geo_reader()
+        mock_settings.GEOLITE2_DB_PATH = "/tmp/fake-geo.mmdb"
+
+        with patch("maxminddb.open_database", side_effect=Exception("reader failed")):
+            result = lookup_geo("1.2.3.4")
+
+        assert result == {}