samplez/rippr-src/docs/TESTING.md

Testing

What is covered, what is not, and — most importantly — what the emulator structurally cannot verify. Read the last section before trusting any green build.

84 unit tests (JVM, no device)        46 instrumented tests (device required)

---

Unit tests — app/src/test/

Pure logic is kept free of Android imports specifically so it can be tested here. This is the pattern Telemetry.kt established in v1 and every later module follows.

Suite	Covers
TelemetryTest	Speed conversion, noise floor, accuracy gate, duration formatting, upload payload shape
TelemetryUploaderTest	Upload success, failure, retry, disabled endpoint — against MockWebServer and an in-memory fake DAO
GeoTest	Haversine against known references, Douglas–Peucker, bounds, degenerate cases
RideStatisticsTest	Distance, moving time, elevation hysteresis, histogram, profile
AccumulatorTest	Live accumulation, the cross-batch anchor, restore, segment boundaries
RideExportTest	GPX/GeoJSON structure parsed with real parsers, escaping, exact point counts

The tests that matter most

A few exist because something specific went wrong and must not return:

• stationary noisy altitude yields near-zero elevation gain — a naive implementation reported 1498 m of climbing over a parked bike. The bound is a regression guard, not an accuracy claim.
• distance across many small batches matches one big batch — guards the cross-batch anchor, whose absence under-reports distance by a few percent, invisibly.
• every raw point is exported with no decimation — catches render-side simplification leaking into exports.
• geojson coordinates are longitude first — the classic silent error; wrong order plots in the wrong hemisphere.
• a hostile trip name still produces valid xml — uses Sam & Dave's <ride> "fast".

---

Instrumented tests — app/src/androidTest/

Suite	Covers
SchemaTest	CASCADE deletes, active-trip flow, ordering, COALESCE guards, upload backlog
TripRepositoryTest	All lifecycle transitions, idempotency, process-death simulation
TrackingServiceLifecycleTest	The real service driven through all five actions
MergeTest	Re-parenting, recomputed aggregates, rejections, atomicity

These tests must use in-memory databases

TrackingServiceLifecycleTest originally ran against the production AppDatabase singleton and called deleteAll() in setUp/tearDown. Harmless on a throwaway emulator, but it would have destroyed every recorded ride had the suite ever been run against a personal phone. It now substitutes an in-memory database through AppDatabase.overrideForTest() and TripRepository.overrideForTest(), restoring the singletons afterwards.

Any new test that touches the service must do the same.

Timeouts

Service tests poll with a 25 s timeout. This was raised from 10 s when the suite grew — but note the flakiness that prompted it turned out to have a real bug behind it (stopSelf() racing a queued START). Raise timeouts only after ruling out a defect.

---

What the emulator cannot verify

This is the most important section in this document.

It reports zero velocity, always

adb emu geo fix teleports the device. Location.speed is therefore always 0, and every recorded speedKmh is 0.0.

Unverifiable on the emulator:

• Max speed, average moving speed
• Moving time (everything falls below the 1.5 km/h noise floor, so it stays 00:00:00)
• Speed colouring on the map — the path renders uniformly in the low-speed colour

A green suite says nothing about any of these.

It hides UI consequences of that limitation

This is subtler and it bit us. v2.0 shipped with max speed as the headline figure on the recording screen. On the emulator every value is zero, so a number that never moves looks perfectly normal. On a real ride it read as a frozen, broken screen.

When a value cannot change under test, question whether the UI around it can be judged at all.

Synthetic fixtures hide scale-dependent bugs

The emulator ride fixtures were ~900 m. A real 50 m ride zoomed the map past OSM's maximum tile zoom and rendered an empty grid. The bug was entirely deterministic and entirely invisible to a fixture of the wrong size.

Test short and long rides.

Correlated noise is not uniform noise

The elevation fixture uses uniform ±8 m random noise. Real GPS altitude error is correlated — it wanders rather than jitters. The ~30 m residual drift measured against synthetic noise may behave quite differently in practice.

---

Not covered at all

1. No Compose UI tests for any of the six screens. Verification was manual screenshots. This is the largest single gap.
2. No battery measurement over a multi-hour ride.
3. No map memory-leak measurement across repeated navigation, despite the osmdroid lifecycle being a known hazard.
4. No rotation/state-retention testing.
5. No test that a GPX imports cleanly into Strava or Garmin — structure is validated against an XML parser, but schema validity does not guarantee a consumer accepts it.

---

The real-ride checklist

The only way to validate the emulator's blind spots. Run it after any change to recording, statistics, or the map.

1. Start, pocket the phone, ride, stop — matching actual usage
2. Max speed plausible against the speedometer
3. Distance plausible against the odometer
4. Moving time excludes stops
5. Elevation gain near zero on flat ground — the most likely silent bug
6. Path renders with no straight line across a pause
7. Speed colouring visibly varies along the path
8. A short ride (under 100 m) still shows streets — the v2.0 zoom bug
9. GPX opens correctly in Google Earth or Strava
10. Battery drain over a multi-hour ride is acceptable
11. Pause/resume survives a screen-off stretch