take-and-update-screenshots

name	take-and-update-screenshots
description	Capture the four RakuRaku showcase screenshots on a connected device and refresh the fastlane metadata. Use when the user asks to take, update, or regenerate screenshots.

Take and Update Screenshots

You are refreshing the showcase screenshots for RakuRaku IME (輕鬆輸入法):

1. 01_settings.png — MainActivity (settings screen)
2. 02_ez_keyboard.png — EZ Chinese keyboard
3. 03_english_keyboard.png — English keyboard
4. 04_emoji_keyboard.png — Emoji picker

All four are produced by a single Gradle task, which runs once per locale (en-US, then zh-Hant-TW):

• sets the per-app locale override via cmd locale set-app-locales <pkg> --locales <tag> (API 33+), then am force-stop so the next launch comes up under the new Configuration,
• runs the instrumented KeyboardScreenshotTest,
• writes PNGs to app/build/reports/screenshots/screenshots/,
• copies them into the matching fastlane/metadata/android/<locale>/images/phoneScreenshots/ folder under the existing 01_…–04_… filenames.

After both locales are captured, the task clears the override (--locales "") so the app falls back to the device locale on the developer's emulator.

The task uses adb shell am instrument rather than connectedAndroidTest so the app is not uninstalled after the run — otherwise the app's external-files dir (where screenshots land) gets wiped before we can pull them.

Per-app locale switching avoids a zygote restart, so the whole per-locale cycle completes in well under a minute (a recent clean run took 44 s end-to-end).

Preconditions

• A single device (physical or emulator) is connected (adb devices shows exactly one entry in device state).
• The device screen is unlocked. The test's @Before wakes the device and dismisses the keyguard, but a lockscreen password cannot be bypassed — ask the user to unlock first if needed.
• Locale: the Gradle task drives the per-app locale itself (en-US and zh-Hant-TW, in that order) via adb shell cmd locale set-app-locales, so the caller doesn't need to pre-configure anything. The device needs to be API 33+ for cmd locale to exist — the current project emulator runs API 36, so this is non-issue in practice.

Workflow

1. Check the device. Run adb devices and confirm exactly one is connected and authorised. If not, stop and ask the user.
2. Run the Gradle task.

   ./gradlew :app:screenshotKeyboard
   

   For each locale (en-US, then zh-Hant-TW) this: installs the app + test APK (idempotent), pushes persist.sys.locale, restarts zygote, waits for boot, runs the test, pulls the PNGs, and copies them into the matching fastlane/metadata/android/<locale>/… folder. Takes ~2–3 minutes total.
3. Spot-check the results. After the task finishes, read at least one shot from each locale (e.g. fastlane/metadata/android/en-US/images/phoneScreenshots/01_settings.png and fastlane/metadata/android/zh-TW/images/phoneScreenshots/01_settings.png) to confirm they aren't blank/black (sleeping screen), caught mid-animation ("Preparing dictionary…" splash), or stuck with the previous locale's strings. If they look wrong, ask the user to wake/unlock the device and re-run — don't blindly commit.
4. Review the diff.

   git status
   git diff --stat fastlane/metadata/
   

   Expect four modified PNGs per locale directory, with distinct file sizes between the two folders (identical sizes = the locale switch silently no-op'd).
5. Stop there unless the user asks to commit. Do not run commit-and-push yourself — the user usually reviews the new screenshots visually in Android Studio's Git tool before committing.

Failure modes to watch for

• Black screenshots → screen was asleep. Wake the device and re-run.
• "Preparing dictionary…" shown in settings.png → MainActivity's first-launch dictionary seed is still running; the test's 6-second sleep is supposed to cover this. Re-run once; if it still repros, increase the sleep in KeyboardScreenshotTest.captureShowcaseScreenshots.
• IllegalStateException "Mode key … not found in IME window" → UiAutomation didn't see the IME window's accessibility tree. Most common cause is the IME hasn't actually been selected: confirm with adb shell settings get secure default_input_method and re-run.
• adb pull fails with "No such file or directory" → the app was uninstalled before the pull. That means someone ran connectedAndroidTest instead of screenshotKeyboard; use the task.
• Fastlane locale mismatch → device locale determines screenshot content. If the user wants a true en-US set, have them run adb shell settings put system system_locales en-US (requires a process/device restart to take effect on system chrome), re-run the task, and copy only to en-US/.