gps-denied-desktop/docs/03_tests/05_satellite_data_manager_integration_spec.md

Integration Test: Satellite Data Manager

Summary

Validate the Satellite Data Manager component responsible for downloading, caching, and providing georeferenced satellite tiles from Google Maps for the operational area.

Component Under Test

Component: Satellite Data Manager Location: gps_denied_04_satellite_data_manager Dependencies:

• Google Maps Static API
• Coordinate Transformer (for tile bounds calculation)
• File system / cache storage
• Database Layer (for tile metadata)

Detailed Description

This test validates that the Satellite Data Manager can:

1. Download satellite tiles from Google Maps Static API for specified GPS coordinates
2. Calculate correct tile bounding boxes using Web Mercator projection
3. Cache tiles efficiently to avoid redundant downloads
4. Provide georeferenced tiles with accurate meters-per-pixel (GSD)
5. Handle zoom level 19 for operational area (Eastern/Southern Ukraine)
6. Manage tile expiration and refresh
7. Handle API errors and rate limiting gracefully

The component provides the reference satellite imagery that all absolute localization (L2, L3) depends on.

Input Data

Test Case 1: Single Tile Download

• Center GPS: 48.275292, 37.385220 (AD000001 location)
• Zoom Level: 19
• Tile Size: 640x640 pixels
• Expected: Download and cache tile with correct georeferencing

Test Case 2: Area Coverage

• Bounding Box:
  • North: 48.28°, South: 48.25°
  • East: 37.39°, West: 37.34°
• Zoom Level: 19
• Expected: Download grid of overlapping tiles covering entire area

Test Case 3: Cache Hit

• Request: Same tile as Test Case 1
• Expected: Return cached tile without API call, verify integrity

Test Case 4: Georeferencing Accuracy

• Center GPS: 48.260117, 37.353469 (AD000029 location)
• Zoom Level: 19
• Expected: Calculate meters_per_pixel accurately (~0.30 m/px at 48°N)

Test Case 5: Tile Bounds Calculation

• Center GPS: 48.256246, 37.357485 (AD000060 location)
• Expected: Northwest and Southeast corners calculated correctly

Test Case 6: Multiple Zoom Levels

• Center GPS: 48.270334, 37.374442 (AD000011 location)
• Zoom Levels: 17, 18, 19
• Expected: Download and correctly georeference tiles at all zoom levels

Expected Output

For each test case:

{
  "success": true/false,
  "tile_id": "unique_tile_identifier",
  "center_gps": {"lat": <float>, "lon": <float>},
  "zoom_level": <integer>,
  "tile_size_px": {"width": <int>, "height": <int>},
  "bounds": {
    "nw": {"lat": <float>, "lon": <float>},
    "se": {"lat": <float>, "lon": <float>}
  },
  "meters_per_pixel": <float>,
  "file_path": "path/to/cached/tile.png",
  "file_size_kb": <float>,
  "cached": true/false,
  "download_time_ms": <float>,
  "api_calls_made": <integer>
}

Success Criteria

Test Case 1 (Single Tile):

• success = true
• tile downloaded and saved to cache
• file_size_kb > 10 (valid PNG image)
• download_time_ms < 5000
• meters_per_pixel ≈ 0.30 (±0.05) at zoom 19

Test Case 2 (Area Coverage):

• success = true for all tiles
• Coverage complete (no gaps)
• Total download time < 120 seconds
• All tiles have valid georeferencing

Test Case 3 (Cache Hit):

• cached = true
• download_time_ms < 100 (cache read)
• api_calls_made = 0
• File integrity verified (hash match)

Test Case 4 (Georeferencing):

• meters_per_pixel calculation error < 1%
• Bounding box corners consistent with center point

Test Case 5 (Bounds Calculation):

• NW corner is actually northwest of center
• SE corner is actually southeast of center
• Distance from NW to SE matches tile_size_px * meters_per_pixel

Test Case 6 (Multi-Zoom):

• All zoom levels download successfully
• meters_per_pixel doubles with each zoom level decrease
• Higher zoom (19) has better resolution than lower zoom (17)

Maximum Expected Time

• Single tile download: < 5 seconds
• Cache read: < 100ms
• Area coverage (20 tiles): < 120 seconds
• Total test suite: < 180 seconds

Test Execution Steps

1. Setup Phase: a. Configure Google Maps API key b. Initialize cache directory c. Clear any existing cached tiles for clean test d. Initialize database for tile metadata

2. Test Case 1 - Single Tile: a. Request tile for AD000001 location b. Verify API call made c. Check file downloaded and cached d. Validate georeferencing metadata e. Verify image is valid PNG

3. Test Case 2 - Area Coverage: a. Define bounding box for test area b. Calculate required tile grid c. Request all tiles d. Verify complete coverage e. Check for overlaps

4. Test Case 3 - Cache Hit: a. Request same tile as Test Case 1 b. Verify no API call made c. Verify fast retrieval d. Check file integrity

5. Test Case 4 - Georeferencing: a. Request tile b. Calculate expected meters_per_pixel using formula: meters_per_pixel = 156543.03392 * cos(lat * π/180) / 2^zoom c. Compare with reported value d. Validate bounds calculation

6. Test Case 5 - Bounds: a. Request tile b. Verify NW corner < center < SE corner c. Calculate distances using haversine d. Verify consistency

7. Test Case 6 - Multi-Zoom: a. Request same location at zoom 17, 18, 19 b. Verify resolution differences c. Check file sizes increase with zoom

Pass/Fail Criteria

Overall Test Passes If:

• All 6 test cases meet their success criteria
• No API errors (except acceptable rate limiting with retry)
• All tiles are valid images
• Georeferencing accuracy within 1%
• Cache mechanism works correctly
• No file system errors

Test Fails If:

• Any tile download fails permanently
• Georeferencing error > 5%
• Cache hits return wrong tiles
• API key invalid or quota exceeded
• File system permissions prevent caching
• Memory usage exceeds 2GB

Additional Validation

API Resilience:

• Test with invalid API key - should fail gracefully with clear error
• Test with rate limiting simulation - should retry with exponential backoff
• Test with network timeout - should handle timeout and retry

Cache Management:

• Verify cache size limits are enforced
• Test cache eviction (LRU or similar)
• Verify stale tile detection and refresh

Coordinate Edge Cases:

• Test at extreme latitudes (if applicable)
• Test at dateline crossing (lon ≈ 180°)
• Test tile alignment at zoom level boundaries

Quality Metrics:

• Image quality inspection (not completely black/white/corrupted)
• Verify actual zoom level matches requested
• Check for Google watermarks/logos presence (expected)

Error Scenarios to Test

1. No Internet Connection: Should fail gracefully, use cached tiles if available
2. Invalid GPS Coordinates: Should reject or clamp to valid range
3. Unsupported Zoom Level: Should reject or default to nearest valid zoom
4. Disk Space Full: Should fail with clear error message
5. Corrupted Cache File: Should detect and re-download

Performance Metrics to Report

• Average download time per tile
• Cache hit ratio
• API calls per test run
• Peak memory usage
• Disk space used by cache
• Tile download success rate