|
| 1 | +--- |
| 2 | +name: verify-indicators |
| 3 | +description: Run the full regression suite for the Compose dots indicators (logic + behaviour + golden screenshots) and relay any screenshot diffs to the agent for a visual verdict. Use after any change to the library's Compose indicators (Shift, Balloon, Spring, Worm), their positioning math, or RTL handling. |
| 4 | +--- |
| 5 | + |
| 6 | +# Verify the Compose dots indicators |
| 7 | + |
| 8 | +This is the automated replacement for the manual regression pass (swipe every page and |
| 9 | +eyeball each of the 4 indicator types, add/remove pages in edge situations, tap dots to |
| 10 | +navigate). It runs three deterministic test tiers on the JVM (Robolectric, no emulator) |
| 11 | +and, when screenshots change, **looks at the diff images itself** and gives a verdict. |
| 12 | + |
| 13 | +The tests live in `viewpagerdotsindicator/src/test/kotlin/com/tbuonomo/viewpagerdotsindicator/compose/`: |
| 14 | +- `ComputationsTest` — pure positioning/sizing math. |
| 15 | +- `DotsIndicatorBehaviorTest` — dot-tap navigation, dot counts, add/remove page edge cases, LTR+RTL no-crash. |
| 16 | +- `DotsIndicatorScreenshotTest` — golden screenshots, 4 types × {LTR, RTL} × 4 states, committed under `src/test/screenshots/`. |
| 17 | + |
| 18 | +## Steps |
| 19 | + |
| 20 | +### 1. Run logic + behaviour tests |
| 21 | +``` |
| 22 | +./gradlew :viewpagerdotsindicator:testDebugUnitTest --tests "com.tbuonomo.viewpagerdotsindicator.compose.ComputationsTest" --tests "com.tbuonomo.viewpagerdotsindicator.compose.DotsIndicatorBehaviorTest" |
| 23 | +``` |
| 24 | +If anything fails, read the report at |
| 25 | +`viewpagerdotsindicator/build/reports/tests/testDebugUnitTest/index.html` and the stack |
| 26 | +trace, then report the failing test and likely cause. Do not continue to step 2 until the |
| 27 | +user decides. |
| 28 | + |
| 29 | +### 2. Verify the golden screenshots |
| 30 | +``` |
| 31 | +./gradlew :viewpagerdotsindicator:verifyRoborazziDebug |
| 32 | +``` |
| 33 | +- **Passes** → all dots are pixel-identical to the committed goldens. Report success. |
| 34 | +- **Fails** → one or more renders drifted. Go to step 3. |
| 35 | + |
| 36 | +> ⚠️ **Platform note:** the committed goldens are recorded on **Linux** (to match CI). |
| 37 | +> Native-graphics rendering is OS-specific, so `verifyRoborazziDebug` run on macOS/Windows |
| 38 | +> will report pixel diffs that are **not** real regressions. On a non-Linux machine, skip the |
| 39 | +> exact verify and instead do step 3 against freshly **recorded** images: run |
| 40 | +> `./gradlew :viewpagerdotsindicator:recordRoborazziDebug` and visually judge the regenerated |
| 41 | +> `src/test/screenshots/*.png` with the checklist below (do **not** commit those — they would |
| 42 | +> break CI). The authoritative exact check happens in CI on Linux. |
| 43 | +
|
| 44 | +### 3. AI relay — judge the diffs |
| 45 | +On failure, Roborazzi writes comparison images to |
| 46 | +`viewpagerdotsindicator/build/outputs/roborazzi/`. The relevant files end in `_compare.png` |
| 47 | +(side-by-side: expected | actual | diff). List them: |
| 48 | +``` |
| 49 | +ls viewpagerdotsindicator/build/outputs/roborazzi/*_compare.png |
| 50 | +``` |
| 51 | +**Open each failing `_compare.png` with the Read tool** (it renders the image) and judge the |
| 52 | +*actual* (middle/right) panel against this checklist: |
| 53 | + |
| 54 | +- **Page 0**: selected dot at the **left** edge in LTR, at the **right** edge in RTL. |
| 55 | +- **Last page**: selected dot at the **right** edge in LTR, at the **left** edge in RTL. |
| 56 | +- **Mid page**: selected dot on the **center** dot. |
| 57 | +- **Selected dot advances one step per page**, in the reading direction (left→right LTR, |
| 58 | + right→left RTL). |
| 59 | +- **Worm** mid-transition (the `*_o05` frames): the worm is **elongated**, spanning the two |
| 60 | + dots it is moving between — toward the right in LTR, toward the left in RTL. |
| 61 | +- **Shift / Balloon**: the selected dot is the **largest**; others are base size. |
| 62 | +- No dot is clipped, off-screen, or missing; there are always 5 dots. |
| 63 | + |
| 64 | +Then classify each diff: |
| 65 | +- **Intended improvement** (the new render is correct and better): tell the user to |
| 66 | + re-record and review, then commit the updated goldens: |
| 67 | + ``` |
| 68 | + ./gradlew :viewpagerdotsindicator:recordRoborazziDebug |
| 69 | + ``` |
| 70 | +- **Regression** (the new render violates the checklist): report exactly which |
| 71 | + type / direction / state broke (the golden name, e.g. `worm_rtl_p0_o05`) and what is |
| 72 | + visually wrong, so it can be fixed before merging. |
| 73 | + |
| 74 | +### 4. Summary |
| 75 | +Print a concise per-type PASS/FAIL table (Shift, Balloon, Spring, Worm), note any goldens |
| 76 | +that need re-recording, and state the overall verdict. |
| 77 | + |
| 78 | +## (Re)recording the committed goldens |
| 79 | + |
| 80 | +The committed goldens **must be recorded on Linux** so they match CI. Don't commit goldens |
| 81 | +recorded on macOS/Windows — they will fail CI's exact verify. To regenerate the trusted set: |
| 82 | + |
| 83 | +1. Let CI record them: push a branch with the CI test step temporarily set to |
| 84 | + `recordRoborazziDebug` and an artifact upload of |
| 85 | + `viewpagerdotsindicator/src/test/screenshots/**`, download the artifact, commit those PNGs, |
| 86 | + then revert the CI step to `verifyRoborazziDebug`. (Or record inside a Linux container.) |
| 87 | +2. Before committing, open a representative sample (at minimum the LTR + RTL `*_p0_o0` and |
| 88 | + `worm_*_p0_o05` frames) with the Read tool and confirm against the checklist above — |
| 89 | + goldens are trusted only after a human/AI has eyeballed them once. |
| 90 | + |
| 91 | +## Notes |
| 92 | +- Everything runs on the JVM via Robolectric — no emulator or device is required. |
| 93 | +- Requires JDK 17+ (the module toolchain is 21). |
| 94 | +- Goldens are recorded at `@Config(sdk = [34])`; they will not match if the SDK level in |
| 95 | + `DotsIndicatorScreenshotTest` changes. |
| 96 | +- To add a new scenario, add a row to the `states`/`types` matrix in |
| 97 | + `DotsIndicatorScreenshotTest`, then `recordRoborazziDebug` and review the new golden. |
0 commit comments