---
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` for debug validation, or `make apk-release` when validating production signing behavior.
3. If the build 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
```

Typical local release build:

```sh
JAVA_HOME=/usr/lib/jvm/java-25-openjdk make apk-release
```

## 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 the intended target: `make apk` for debug validation or `make apk-release` for release-signing validation.
- 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