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:

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

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