From d61f0fe7b4d9464e42c074a10df761d94cb67577 Mon Sep 17 00:00:00 2001 From: Emre K <110906681+kocaemre@users.noreply.github.com> Date: Fri, 31 Jul 2026 18:17:33 +0200 Subject: [PATCH] docs: clarify UI verification for agents Signed-off-by: Emre K <110906681+kocaemre@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 1 + AGENTS.md | 41 +++++++++++++++++++++++++++++--- 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 88af6d46..5ffeaff5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,4 +12,5 @@ - [ ] I have updated the documentation / docstrings where appropriate. - [ ] If my change touches the schema (`tuttle/model.py`), I generated and reviewed an Alembic migration (`just migrate ""`). - [ ] If my change affects the graphical user interface, I have provided screenshots. +- [ ] UI verification evidence is included for product UI changes, or this PR has no product UI surface. - [ ] I understand and can explain all submitted changes; if AI assistance was significant, I have disclosed it in the summary above. diff --git a/AGENTS.md b/AGENTS.md index 6f4cf620..c41f022b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,41 @@ generated revision for rename-as-drop+add traps. See For big new features, add a new contract and project to the Harry tuttle user for demonstration purposes. -### UI -- Test UI changes using playwright electron. https://playwright.dev/docs/api/class-electron -- launch the electron app and provide screenshots as artefacts in PR comments to be reviewed. +### UI verification playbook + +UI verification is useful when a change affects the Electron shell, navigation, forms, +rendered invoice/timesheet flows, or any visible product copy. It should complement, +not replace, unit tests and human UX review. + +#### When to run UI verification + +- Run an Electron UI smoke when the PR changes a user-visible screen, route, + modal, keyboard shortcut, import/export interaction, or platform packaging. +- Prefer a narrow path that exercises the changed surface instead of clicking the + whole app. Example: launch the app, open the affected screen, perform the one + edited action, and capture the before/after state. +- For non-UI changes, state that no UI surface changed rather than spending tokens + on screenshots that do not prove the patch. + +#### How to run it + +- Use Playwright Electron where practical: . +- If Playwright setup is heavier than the change justifies, use the existing app + start command plus manual/agent-driven clicks and document the exact path. +- Keep fixtures local and synthetic. Do not use real customer names, invoices, + email addresses, API keys, or private business data in screenshots. + +#### Evidence to include + +- Screenshots or a short recording for every PR that changes product UI. +- The command used to start the app and the exact navigation path tested. +- Any known limitation, such as a screen that still needs final human review or a + platform-specific path that was not exercised locally. + +#### When not to over-test + +- Documentation-only, schema-only, and backend-only PRs do not need Electron + screenshots unless they also affect visible UI behavior. +- Do not attempt broad exploratory clicking for small patches. Prefer one focused + UI smoke that proves the changed behavior and leaves final UX judgment to a + human reviewer.