honeyDueKMP/docs/parity-gallery.md

# Parity gallery — iOS ↔ Android snapshot regression

Every primary screen on both platforms is captured as a PNG golden and
committed to the repo. A PR that drifts from a golden fails CI. The
committed `docs/parity-gallery.html` pairs iOS and Android side-by-side in
a scrollable HTML grid you can open locally or from gitea's raw-file view.

## Quick reference

```
make verify-snapshots     # PR gate; fast. Both platforms diff against goldens.
make record-snapshots     # Regenerate everything + optimize. Slow (~5 min).
make optimize-goldens     # Rerun zopflipng over existing PNGs. Idempotent.
python3 scripts/build_parity_gallery.py   # Rebuild docs/parity-gallery.html
```

## How it works

### Shared fixtures
`composeApp/src/commonMain/kotlin/com/tt/honeyDue/testing/FixtureDataManager.kt`
exposes `.empty()` and `.populated()` factories. Both platforms render the
same screens against the same fixture graph — the only cross-platform
differences left are actual UI code differences (by design). Fixtures use
a fixed clock (`Fixtures.FIXED_DATE = LocalDate(2026, 4, 15)`) so dates
never drift.

### Android capture (Roborazzi)
- `composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/screenshot/ScreenshotTests.kt`
  declares one `@Test` per surface in `GallerySurfaces.kt`.
- Each test captures 4 variants: `empty × light`, `empty × dark`,
  `populated × light`, `populated × dark`.
- Runs in Robolectric — no emulator needed, no flake from animations.
- Goldens: `composeApp/src/androidUnitTest/roborazzi/<screen>_<state>_<mode>.png`
- Typical size: 30–80 KB per image.

### iOS capture (swift-snapshot-testing)
- `iosApp/HoneyDueTests/SnapshotGalleryTests.swift` has 4 tests per screen.
- Rendered at `displayScale: 2.0` (not the native 3.0) to cap per-image size.
- Uses `FixtureDataManager.shared.empty()` / `.populated()` via SKIE.
- Goldens: `iosApp/HoneyDueTests/__Snapshots__/SnapshotGalleryTests/test_<name>.<variant>.png`
- Typical size: 150–300 KB per image after `zopflipng` post-processing.

### Record-mode trigger
Both platforms record only when explicitly requested:
- Android: `./gradlew :composeApp:recordRoborazziDebug`
- iOS: `SNAPSHOT_TESTING_RECORD=1 xcodebuild test …`

`make record-snapshots` does both, plus runs `scripts/optimize_goldens.sh`
to shrink the output PNGs. No code edits required to switch between record
and verify — the env var / gradle task controls everything.

## When to record vs verify

**Verify** is what CI runs on every PR. It is the gate. If verify fails,
ask: *was this drift intentional?*

**Record** is what you run locally when a UI change is deliberate and you
want to publish the new look as the new baseline. Commit the regenerated
goldens alongside your code change so reviewers see both the code and the
visual result in one PR.

Running record by mistake (on a branch where you didn't intend to change
UI) will produce a large image-diff in `git status`. That diff is the
signal — revert the goldens, investigate what unintentionally changed.

## Adding a screen to the gallery

### Android
Add one entry to
`composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/screenshot/GallerySurfaces.kt`:

```kotlin
GallerySurface("my_new_screen") { MyNewScreen(onNavigateBack = {}, /* required params from fixtures */) },
```

If the screen needs a specific model (`task`, `residence`, etc.) pass one
from `Fixtures.*` — e.g. `Fixtures.tasks.first()`. If the screen renders
differently in empty vs populated, the `LocalDataManager` provider wiring
in `ScreenshotTests.kt` handles it automatically.

### iOS
Add 4 test functions to `iosApp/HoneyDueTests/SnapshotGalleryTests.swift`:

```swift
func test_myNewScreen_empty_light()     { snap("my_new_screen_empty_light",     empty: true,  dark: false) { MyNewView() } }
func test_myNewScreen_empty_dark()      { snap("my_new_screen_empty_dark",      empty: true,  dark: true)  { MyNewView() } }
func test_myNewScreen_populated_light() { snap("my_new_screen_populated_light", empty: false, dark: false) { MyNewView() } }
func test_myNewScreen_populated_dark()  { snap("my_new_screen_populated_dark",  empty: false, dark: true)  { MyNewView() } }
```

Then `make record-snapshots` to generate goldens, `git add` the PNGs
alongside your test changes.

## Approving intentional UI drift

```bash
# 1. Regenerate goldens against your new UI.
make record-snapshots

# 2. Review the PNG diff — did only the intended screens change?
git status composeApp/src/androidUnitTest/roborazzi/ iosApp/HoneyDueTests/__Snapshots__/
git diff --stat composeApp/src/androidUnitTest/roborazzi/ iosApp/HoneyDueTests/__Snapshots__/

# 3. Stage and commit alongside the UI code change.
git add <screen-file.kt> <SnapshotGalleryTests.swift changes> \
        composeApp/src/androidUnitTest/roborazzi/ \
        iosApp/HoneyDueTests/__Snapshots__/
git commit -m "feat: <what changed>"
```

Reviewers see the code diff AND the golden diff in one PR — makes intent
obvious.

## Image size budget

Per-file soft budget: **400 KB**. Enforced by CI.

Android images are rarely this large. iOS images can exceed 400 KB for
gradient-heavy screens (Onboarding welcome, organic blob backgrounds).
If a new screen exceeds budget:
1. Check whether the screen really needs a full-viewport gradient.
2. If yes, consider rendering at `displayScale: 1.0` for just that test
   (the `snap` helper accepts an override).

## Tool installation

The optimizer script needs one of:
```bash
brew install zopfli          # preferred — better compression
brew install pngcrush        # fallback
```

Neither installed? `make record-snapshots` warns and skips optimization —
goldens are still usable, just larger.

## HTML gallery

`docs/parity-gallery.html` is regenerated by
`scripts/build_parity_gallery.py` whenever goldens change. It's a
self-contained HTML file with relative `<img>` paths that resolve within
the repo — so gitea's raw-file view renders it without any server.

To view locally:
```bash
python3 scripts/build_parity_gallery.py
open docs/parity-gallery.html
```

The gallery groups by screen name. Each row shows Android vs iOS for one
{state, mode} combination, with sticky headers for quick navigation.

## Current coverage

Written to the output on each regeneration — check the top of
`docs/parity-gallery.html` for the current count.

## Known limitations

- **iOS populated-state coverage is partial**. Swift Views today instantiate
  their ViewModels via `@StateObject viewModel = FooViewModel()`; the
  ViewModels read `DataManagerObservable.shared` directly rather than
  accepting an injected `IDataManager`. Until ViewModels gain a DI seam,
  populated-state snapshots require per-screen ad-hoc workarounds.
  Tracked as a follow-up.

- **Android detail-screen coverage is partial**. Screens that require a
  pre-selected model (`ResidenceDetailScreen(residence = ...)`,
  `ContractorDetailScreen(contractor = ...)`) silently skip rendering
  unless `GallerySurfaces.kt` passes a fixture item. Expanding these to
  full coverage is a follow-up PR — low-risk additions to
  `GallerySurfaces.kt`.

- **Cross-platform diff is visual, not pixel-exact**. SF Pro (iOS) vs
  SansSerif (Android) render different glyph shapes by design. Pixel-diff
  is only used within a platform — the HTML gallery is for side-by-side
  human review.

- **Roborazzi path mismatch**. The historical goldens lived at
  `composeApp/src/androidUnitTest/roborazzi/`. The Roborazzi Gradle block
  sets `outputDir` to match. If `verifyRoborazziDebug` ever reports
  "original file not found", confirm the `outputDir` hasn't drifted.