diff --git a/docs/gui-test-plan.md b/docs/gui-test-plan.md new file mode 100644 index 0000000..e60341f --- /dev/null +++ b/docs/gui-test-plan.md @@ -0,0 +1,207 @@ +# 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: + +```md +## Android +- Screen: +- Action: +- Expected: +- Actual: +- Severity: + +## Desktop +- Screen: +- Action: +- Expected: +- Actual: +- Severity: +```