nigig-org/REVIEWS/VALHALLA_TEST_COVERAGE_ANALYSIS_AND_PLAN.md

Valhalla Pure Rust Rewrite (valhalla-rs)

Test Coverage Improvement Analysis & Comprehensive Action Plan

Date: July 28, 2026
Target Repository: https://gitdab.com/andodeki/nigig-org.git (crates/apps/valhalla/*)
Baseline Test Count: 56 Unit & Parity Tests
Target Test Count: 80+ Comprehensive Unit, Property, Edge Case, & Integration Tests

---

1. Executive Summary & Audit Baseline

A comprehensive test coverage audit of the 11 Pure Rust Valhalla subcrates (crates/apps/valhalla/*) was performed to evaluate test density, edge case resilience, and boundary condition validation.

Baseline Coverage Metrics:

Crate	Baseline Test Count	Target Test Count	High-Priority Test Expansion Areas
valhalla-core	26 tests	35+ tests	Anti-meridian wrapping, zero-copy struct bit-field deserialization, EdgeInfo polyline parsing.
valhalla-cost	4 tests	12+ tests	Motorcycle & Scooter speed curves, mode access bitmasks, HierarchyLimits edge cases.
valhalla-path	4 tests	10+ tests	DoubleBucketQueue overflow refills, A^* unreachable destinations, Isochrone hull edge cases.
valhalla-search	1 test	4+ tests	Multi-tile candidate locator boundary queries, search radius culling.
valhalla-match	2 tests	5+ tests	Viterbi trajectory gaps, multi-candidate probability transition matrices.
valhalla-narrative	3 tests	8+ tests	Locale template formatting for all 4 languages (en-US, sw-KE, fr-FR, es-ES), TTS abbreviations.
valhalla-elevation	2 tests	5+ tests	SRTM1 (3601 \times 3601) parsing, bilinear interpolation tile boundary corners, NO_DATA values.
valhalla-service	1 test	4+ tests	ValhallaActor status 400/404 error responses, /height and /isochrone endpoints.
valhalla-makepad	3 tests	6+ tests	DriverGuidanceController off-route (>25\text{m}) auto-reroute event dispatch & HUD progress.
valhalla-builder	9 tests	12+ tests	OsmHighwayType classification speed limits, PbfReader dense node delta offsets.
valhalla-diff	1 test	3+ tests	Golden route fixture tolerance assertions (distance, time, maneuvers).
Total Suite	56 tests	104+ tests	Comprehensive test coverage across the entire routing suite.

---

2. Action Plan for Test Suite Expansion

To achieve comprehensive test coverage, new tests will be implemented across all 11 subcrates:

2.1 valhalla-core

• Test PointLL anti-meridian coordinate wrapping (180^\circ \to -180^\circ) and polar limits (\pm 90^\circ).
• Test AABB2 bounding box unions and zero-area point boxes.
• Test Polyline2 single-point and empty polyline length queries.
• Test zero-copy deserialization for all Raw* bit-packed structs (RawComplexRestriction, RawAccessRestriction, RawTimeDomain, RawNodeTransition, RawTrafficSpeed, RawTransitStop, RawTransitDeparture, RawTransitRoute, RawTransitSchedule, RawTurnLanes, RawLaneConnectivity).

2.2 valhalla-cost

• Test MotorcycleCost and MotorScooterCost access bitmasks and speed limits.
• Test AutoCost toll penalty and border crossing penalty additions.
• Test PedestrianCost and BicycleCost mode access filtering.
• Test HierarchyLimits up-transition recording and expansion radius culling.

2.3 valhalla-path

• Test DoubleBucketQueue out-of-order pushes and equal sortcost pop ordering.
• Test AStar path search on unreachable destination nodes (returns None).
• Test TimeDistanceMatrix with asymmetric origin/destination lists.
• Test IsochroneGenerator convex hull with collinear and duplicate points.
• Test AlternateRouteFinder path sharing percentage calculation.

2.4 valhalla-search

• Test EdgeLocator multi-tile candidate snapping.
• Test EdgeLocator max search radius filtering.

2.5 valhalla-match

• Test MapMatcher Viterbi trajectory with noisy GPS points and heading alignment penalties.
• Test MapMatcher transition probability matrix calculations.

2.6 valhalla-narrative

• Test NarrativeDictionary formatting for French (fr-FR) and Spanish (es-ES).
• Test VerbalTextFormatter multi-abbreviation street name replacements ("Moi Ave" \to "Moi Avenue", "Mama Ngina St" \to "Mama Ngina Street").
• Test ManeuverBuilder multi-step turn sequence instruction generation.

2.7 valhalla-elevation

• Test HgtTile SRTM1 (3601 \times 3601) grid parsing.
• Test HgtTile bilinear interpolation at tile boundary corners.
• Test ElevationSampler polyline height profile sampling.

2.8 valhalla-service

• Test ValhallaActor status 404 for disconnected graph nodes.
• Test ValhallaActor::height() elevation profile response.
• Test ValhallaActor::isochrone() reachability response.

2.9 valhalla-makepad

• Test DriverGuidanceController off-route threshold (>25\text{m}) triggering GuidanceEvent::Rerouted.
• Test NavigationHudData step index progression and remaining time/distance calculations.

2.10 valhalla-builder

• Test OsmHighwayType speed limits for all 10 road classifications.
• Test PbfReader dense node coordinate delta decoding with custom granularity and offsets.

2.11 valhalla-diff

• Test ParityChecker error reporting for out-of-bounds distance and duration fixtures.

---

3. Execution & Verification

Run the expanded test suite using the isolated test runner:

TEST_TARGET=valhalla ./tools/test-rust-clean.sh

Ensure all tests pass cleanly with zero errors and zero warnings.