keepassgo/docs/gui-test-plan.md

GUI Test Plan

This document splits GUI validation into human-owned and agent-owned coverage. The intent is that, together, both passes exercise every reachable GUI area without relying on one side to judge both functional correctness and real usability.

Scope

• Desktop GUI
• Android GUI
• Shared workflow surfaces: lifecycle, unlock, list/detail/editor, settings, sync, API tokens, API audit, templates, recycle bin, About, and platform-specific integrations

Ownership Model

• Human testing covers visual correctness, ergonomics, discoverability, focus, scrolling, tap targets, keyboard feel, and platform integration behavior.
• Agent testing covers deterministic automation: build, install, launch, focus, test suite, lint, and release-path validation.

Android Plan

Coverage Matrix

Area	Human	Agent
App launch and first render	Verify real rendering, layout, readability, no black screen	Verify emulator online, app installed, app focused
Lifecycle screen	Exercise create/open/open-remote forms visually	Cover lifecycle logic through Go tests and release APK build
Unlock flow	Verify password/key-file affordances, focus, error messaging	Covered by automated tests
Vault list and navigation	Verify scrolling, selection, section switching, phone layout reachability	Covered by automated tests for list state/search/section behavior
Entry detail	Verify readability, action placement, tap targets	Covered by automated tests for state transitions and copy/generate actions
Entry editor	Verify field editing usability and save affordance	Covered by automated tests for save/update behavior
Template views	Verify template list/editor reachability and copy	Covered by automated tests
Recycle bin	Verify deleted-entry browsing/search UX	Covered by automated tests
Attachments UI	Verify list/add/remove affordances visually	Covered by automated tests for attachment summaries and save paths
Search	Verify placeholder, live filtering feel, clear behavior	Covered by automated tests for search semantics
Settings	Verify toggles and summaries are understandable	Covered by automated tests for persistence
Remote sync setup/dialog	Verify sheet/dialog layout, field order, source/direction controls	Covered by automated tests and release build
Saved remote binding UI	Verify summaries are understandable and discoverable	Covered by automated tests
API tokens / API audit	Verify navigation and dense-detail readability	Covered by automated tests
About / informational screens	Verify copy, scroll, layout	Covered by automated tests for search disable state and section state
Android-only share/import/file picker	Verify system integration actually works	Agent only verifies package/build/focus, not picker UX
Android autofill entry point	Verify Android mechanism appears and is usable	Agent only verifies app/package/focus

Human Steps

1. Start from the currently installed org.julianfamily.keepassgo app on the running emulator or device.
2. Verify launch lands on a rendered screen, not a black frame, blank frame, or frozen frame.
3. On the lifecycle screen, inspect every visible action: Create vault, Open vault, Open remote vault, unlock-related controls, recent vaults, and any sync summaries.
4. Create a throwaway vault or open a demo vault and verify the full unlock path is visually clear.
5. After unlock, visit each top-level section you can reach in the Android UI: vault/group list, entry detail, entry editor, templates, recycle bin, settings, API tokens, API audit, About.
6. In the main vault UI, verify: group navigation, entry selection, search, back behavior, scrolling, and any phone-only toggles or drawers.
7. Open an entry and exercise every visible entry action: copy username, copy password, copy URL, reveal/hide password, generate password, save.
8. Exercise one template flow: open template list, inspect template detail/editor, save or cancel.
9. Exercise recycle-bin browsing and search.
10. Open settings and inspect every visible toggle or summary card. Change at least one benign toggle and verify it sticks after leaving and returning.
11. Open the sync UI and inspect: remote setup, saved-binding summary, direction/source choices, confirm/cancel behavior, and text summaries.
12. Exercise one Android-native integration: shared-vault import, file picker open, or current-vault share.
13. If Android autofill is in scope for current testing, open a target app/site and confirm the Android autofill entry point is offered and usable.
14. Record failures with: exact screen, exact control, expected behavior, actual behavior, and whether it is Android-only or likely shared with desktop.

Agent Steps Executed

1. Verified emulator availability with adb devices -l.
2. Verified emulator Android version with adb shell getprop ro.build.version.release.
3. Verified app package installed with adb shell pm list packages org.julianfamily.keepassgo.
4. Verified app focus with adb shell dumpsys window | rg 'mCurrentFocus|mFocusedApp'.
5. Ran go test ./....
6. Ran go tool golangci-lint run ./....
7. Verified release APK path through release workflow v0.6.0: PR run 60 succeeded, post-merge main run 61 succeeded, tag run 62 succeeded.

Agent Results

• Emulator present: yes
• Android version: 15
• App installed: yes
• App focused: org.julianfamily.keepassgo/org.gioui.GioActivity
• APK release build path: passed in release CI
• Remaining Android risk: real visual usability and system-integration behavior

Desktop Plan

Coverage Matrix

Area	Human	Agent
App launch and window presentation	Verify startup polish, focus, resize behavior, DPI/readability	Verify desktop binaries built in release CI
Lifecycle screen	Verify desktop layout density, affordance clarity, recent vault usability	Covered by automated tests
Unlock flow	Verify keyboard-first behavior, focus order, errors, lock/unlock loop	Covered by automated tests plus human keyboard feel
Group browser and list pane	Verify density, selection clarity, scrolling, split behavior	Covered by automated tests for state/search
Entry detail pane	Verify copy actions, reveal/hide, path context, readability	Covered by automated tests
Entry editor	Verify field order, keyboard flow, save/cancel usability	Covered by automated tests
Templates	Verify templates section is reachable and understandable	Covered by automated tests
Recycle bin	Verify browsing, searching, deletion or recovery UX	Covered by automated tests
Search	Verify keyboard search flow, placeholder correctness, result context	Covered by automated tests
Vault save/save-as/lock	Verify menus, buttons, and shortcuts feel correct	Covered by automated tests and release builds
Settings	Verify desktop layout, summaries, toggles, persistence feel	Covered by automated tests
Remote sync UI	Verify dialog layout, wording, discoverability, advanced options	Covered by automated tests
API tokens	Verify dense-detail presentation and policy editor usability	Covered by automated tests
API audit	Verify search/filter/readability	Covered by automated tests
Browser-extension-adjacent desktop UX	Verify visible status/help text and extension workflow discoverability	Agent validated release/build path; human should judge usability
About and docs entry points	Verify copy and layout	Covered partly by tests; human judges presentation

Human Steps

1. Launch KeePassGO on desktop from the shipped binary or normal desktop entry.
2. Inspect the lifecycle/open screen at normal window size and at a narrower width.
3. Exercise create, open, save-as, lock, unlock, and reopen on a throwaway vault or demo vault.
4. Use keyboard-first operation for at least one complete pass: tab order, enter or escape expectations, search focus, unlock focus, and editor save flow.
5. After unlocking, visit every reachable primary section: vault list, entry detail, editor, templates, recycle bin, settings, API tokens, API audit, About.
6. In the vault browser, verify: nested groups, path context, scrolling, selection state, and search results with path context.
7. Open an entry and exercise all visible actions: copy username, password, URL, reveal/hide password, password generation, and save.
8. Exercise at least one mutation flow: create entry, edit entry, move/delete entry, view recycle bin, and recover if available.
9. Open settings and inspect all visible summaries and toggles.
10. Open remote sync UI and inspect every visible mode: setup, saved binding, advanced sync, source or direction choices.
11. Open API Tokens and API Audit even if you do not issue a real token, just to assess navigation and readability.
12. If you use browser integration, verify the desktop-side flow is still understandable from the product UI and extension behavior.
13. Record failures with: screen, control, expected behavior, actual behavior, and whether it is presentation-only or functional.

Agent Steps Executed

1. Verified clean repo state on main.
2. Ran go test ./....
3. Ran go tool golangci-lint run ./....
4. Verified post-merge main CI run 61 succeeded.
5. Verified release tag run 62 succeeded.
6. Verified release v0.6.0 published.
7. Verified release artifacts include: keepassgo-linux-amd64, keepassgo-windows-amd64.exe, keepassgo-windows-arm64.exe, and keepassgo.apk.

Agent Results

• Automated logic/state coverage: pass
• Desktop build coverage: pass
• Release publication: pass
• Remaining desktop risk: interaction quality, keyboard feel, dense-layout readability, and workflow discovery

Reporting Template

Use this format when reporting findings from the human pass:

## Android
- Screen:
- Action:
- Expected:
- Actual:
- Severity:

## Desktop
- Screen:
- Action:
- Expected:
- Actual:
- Severity: