Document Android APK test workflow
This commit is contained in:
Joe Julian
@@ -0,0 +1,116 @@
|
||||
---
|
||||
name: keepassgo-apk-test
|
||||
description: Build and run the KeePassGO Android APK for emulator testing. Use when work requires `make apk`, APK install/launch, emulator validation, or checking known KeePassGO Android regressions such as black screens, clipboard, open flow, or local sync behavior.
|
||||
---
|
||||
|
||||
# KeePassGO APK Test
|
||||
|
||||
Use this skill together with the installed `android-emulator-debug` skill. That skill covers generic emulator and `adb` mechanics. This skill adds the KeePassGO-specific build, install, and validation requirements that have already been established in this repo.
|
||||
|
||||
## Use This Skill When
|
||||
|
||||
- Building `build/keepassgo.apk`.
|
||||
- Installing or launching KeePassGO in the Android emulator.
|
||||
- Verifying Android regressions such as black screen, clipboard, open flow, file picker, or Advanced Sync behavior.
|
||||
- Checking whether a Gio or Android toolchain change broke runtime behavior.
|
||||
|
||||
## Known Working Environment
|
||||
|
||||
- Preferred emulator AVD: `KeepassGoAPI35`
|
||||
- Package: `org.julianfamily.keepassgo`
|
||||
- Activity: `org.gioui.GioActivity`
|
||||
- Local APK build defaults:
|
||||
`ANDROID_SDK_ROOT=/opt/android-sdk`
|
||||
`ANDROID_NDK_ROOT=/opt/android-ndk`
|
||||
`JAVA_HOME=/usr/lib/jvm/java-25-openjdk`
|
||||
- CI APK build uses:
|
||||
`ANDROID_SDK_ROOT=/opt/android-sdk`
|
||||
`ANDROID_NDK_ROOT=/opt/android-sdk/ndk`
|
||||
`JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64`
|
||||
|
||||
## Known Regression
|
||||
|
||||
- `gioui.org v0.9.0` caused a black screen in the `KeepassGoAPI35` emulator.
|
||||
- `gioui.org v0.8.0` rendered correctly in the same environment.
|
||||
- If Android rendering regresses after a Gio change, treat Gio as a primary suspect and verify against this known-bad versus known-good history before guessing about app logic.
|
||||
|
||||
## Safety Rules
|
||||
|
||||
- Do not clobber the user’s real KeePassGO state while testing.
|
||||
- For host-side validation, use isolated state such as:
|
||||
`KEEPASSGO_STATE_DIR="$(mktemp -d)" go test ./...`
|
||||
- Prefer sanitized demo or test vaults when seeding emulator tests.
|
||||
- If a real vault is absolutely required to reproduce a problem, do not modify it and do not overwrite the user’s existing recent-vault state.
|
||||
|
||||
## Build Workflow
|
||||
|
||||
1. Verify the JDK/SDK paths match the known working environment.
|
||||
2. Build with `make apk`.
|
||||
3. If `make apk` fails, inspect the effective `JAVA_HOME`, `ANDROID_SDK_ROOT`, and `ANDROID_NDK_ROOT` before changing code.
|
||||
4. If the problem is Android-only, avoid desktop-only conclusions from `go test ./...`.
|
||||
|
||||
Typical local build:
|
||||
|
||||
```sh
|
||||
JAVA_HOME=/usr/lib/jvm/java-25-openjdk make apk
|
||||
```
|
||||
|
||||
## Emulator Workflow
|
||||
|
||||
1. Reuse an existing emulator session if one is already running.
|
||||
2. Prefer the `KeepassGoAPI35` AVD.
|
||||
3. Install with `adb install -r build/keepassgo.apk`.
|
||||
4. Launch with:
|
||||
|
||||
```sh
|
||||
adb shell monkey -p org.julianfamily.keepassgo -c android.intent.category.LAUNCHER 1
|
||||
```
|
||||
|
||||
5. Confirm focus before drawing conclusions:
|
||||
|
||||
```sh
|
||||
adb shell dumpsys window | rg 'mCurrentFocus|mFocusedApp'
|
||||
```
|
||||
|
||||
6. Capture evidence before editing code:
|
||||
screenshot
|
||||
focused window
|
||||
relevant `logcat`
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- APK builds successfully with `make apk`.
|
||||
- App launches to `org.julianfamily.keepassgo/org.gioui.GioActivity`.
|
||||
- Screenshot shows the expected screen, not just a black frame.
|
||||
- `logcat` shows no app crash or Android runtime fatal error.
|
||||
- If the change is about user interaction, perform the tap-through in the emulator instead of stopping at install success.
|
||||
|
||||
## Issue-Specific Checks
|
||||
|
||||
### Black Screen
|
||||
|
||||
- Confirm the app is focused.
|
||||
- Capture a screenshot and `logcat` before changing anything.
|
||||
- Compare the current Gio version against the known `v0.9.0` regression history.
|
||||
- If needed, test whether a minimal Gio example renders in the same emulator before blaming KeePassGO layout code.
|
||||
|
||||
### Clipboard
|
||||
|
||||
- Verify behavior in the emulator, not just unit tests.
|
||||
- Android clipboard writes must use the Gio-native command path, not desktop clipboard backends.
|
||||
|
||||
### File Picker Or Local Sync
|
||||
|
||||
- Verify the picker flow on Android itself.
|
||||
- Prefer document-stream or content-URI based behavior over raw filesystem paths when Android permissions are involved.
|
||||
|
||||
## Report Back
|
||||
|
||||
When closing out work, state:
|
||||
|
||||
- the exact build command used
|
||||
- whether the emulator session was reused or newly started
|
||||
- whether install succeeded
|
||||
- whether the app actually rendered
|
||||
- what was verified manually in the emulator
|
||||
- what remains unverified
|
||||
@@ -14,6 +14,8 @@ These instructions apply to all future work in this repository.
|
||||
## Skills
|
||||
|
||||
- Use the installed Go skills whenever they materially apply to the current slice of work.
|
||||
- Use the installed `android-emulator-debug` skill for Android emulator lifecycle, `adb`, screenshots, and log capture work.
|
||||
- Use the repo-local `keepassgo-apk-test` skill for KeePassGO-specific APK build and emulator test runs.
|
||||
- The available Go skills for this repository are:
|
||||
`go-code-review`,
|
||||
`go-concurrency`,
|
||||
@@ -126,6 +128,20 @@ These features are product requirements, not “nice to have” ideas.
|
||||
- Keep `golangci-lint` passing.
|
||||
- Keep `go test ./...` passing.
|
||||
- Track `gogio` as a Go tool and keep a reproducible `make apk` path for Android packaging.
|
||||
- Keep the Android build requirements aligned with the known working setup:
|
||||
`ANDROID_SDK_ROOT=/opt/android-sdk`,
|
||||
local `ANDROID_NDK_ROOT=/opt/android-ndk`,
|
||||
CI `ANDROID_NDK_ROOT=/opt/android-sdk/ndk`,
|
||||
local `JAVA_HOME=/usr/lib/jvm/java-25-openjdk`,
|
||||
CI `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64`.
|
||||
- Remember the known Android runtime regression:
|
||||
`gioui.org v0.9.0` produced a black screen on the `KeepassGoAPI35` emulator, while `gioui.org v0.8.0` rendered correctly. Treat Gio upgrades on Android as regression-sensitive and verify them on-device or in the emulator.
|
||||
- When validating an APK in the emulator, prefer the known KeePassGO setup:
|
||||
AVD `KeepassGoAPI35`,
|
||||
package `org.julianfamily.keepassgo`,
|
||||
activity `org.gioui.GioActivity`.
|
||||
- Do not run emulator/manual APK tests against the user’s real persisted app state.
|
||||
Use an isolated `KEEPASSGO_STATE_DIR` for host-side validation, and when emulator testing requires seeded vault data, use sanitized test/demo vaults rather than the user’s real vault files whenever possible.
|
||||
- When running tests or other automated validation that may touch persisted UI state, set `KEEPASSGO_STATE_DIR` to an isolated temporary directory so recent-vault history and other local state do not pollute the user’s real config.
|
||||
- Prefer commands shaped like `KEEPASSGO_STATE_DIR=\"$(mktemp -d)\" go test ./...` for ad hoc local validation unless a test already manages its own isolated state directory.
|
||||
- Do not assume the agent can decrypt SOPS-encrypted secrets in this repository.
|
||||
|
||||
Reference in New Issue
Block a user