Add maintainer onboarding documentation

2026-07-03 12:44:15 +02:00
parent 5d80af375e
commit d80486b25e
15 changed files with 1273 additions and 28 deletions
@@ -0,0 +1,117 @@
+# Testing And Debugging
+
+## Baseline Commands
+
+```bash
+flutter analyze
+flutter test
+dart run build_runner build --delete-conflicting-outputs
+```
+
+Focused suites:
+
+```bash
+flutter test test/features/share_intake
+flutter test test/features/ai_digest
+flutter test test/features/local
+flutter test test/features/sync
+flutter test test/core/llm
+flutter test test/integrations/backend
+```
+
+## Manual Smoke Tests
+
+Fake backend:
+
+1. Launch with `USE_FAKE_BACKEND=true`.
+2. Sign in with fake credentials.
+3. Add a person.
+4. Add a moment.
+5. Add an idea.
+6. Add a reminder.
+7. Open Settings and verify flags.
+
+Share intake:
+
+1. Settings -> `Simulate Share Capture`.
+2. Paste a sender-prefixed text share.
+3. Confirm review sheet behavior.
+4. Verify profile attachment or Share Inbox routing.
+5. Open profile and check facts/messages/signals.
+
+AI digest:
+
+1. Configure provider in Settings.
+2. Run LLM Debug if needed.
+3. Enable weekly digest.
+4. Run Private Digest Now.
+5. Open AI Review.
+6. Accept and dismiss drafts.
+
+Notifications:
+
+1. Request notification access from Settings.
+2. Create or update reminders.
+3. Verify scheduler tests still pass.
+4. Test real delivery on device where possible.
+
+## Debug Surfaces
+
+Settings includes:
+
+- LLM Debug
+- LLM diagnostics export
+- Run Private Digest Now
+- Open AI Review
+- Request Notification Access
+- Simulate Share Capture
+- Open Share Inbox
+- Share Diagnostics
+
+Sync view includes:
+
+- pending changes
+- rejected changes
+- repair actions
+- retry/requeue tools
+
+## Common Failures
+
+### Share intent delivered nothing
+
+Check:
+
+- `ENABLE_WHATSAPP_SHARE_INTAKE`
+- iOS extension target build
+- App Group ID matches Runner and extension targets
+- `ReceiveSharingIntent.instance.getInitialMedia()`
+- Share Diagnostics in Settings
+
+### LLM digest creates bad suggestions
+
+Check:
+
+- `AnonymizedLlmContextBuilder` payload
+- sensitive/unreviewed facts filtering
+- prior suggestions included
+- source age and `shared_message_datetime`
+- parser response tests
+
+### Background digest does not run
+
+This can be normal. iOS background execution is best effort. Verify manual run
+first, then check Workmanager setup, background modes, charging/network policy,
+and run-state backoff.
+
+### Full widget tests fail due layout hit targets
+
+Some app-flow tests are sensitive to viewport/layout. Prefer focused tests for
+feature work, then investigate full-suite failures separately with screenshots
+or widget tree dumps.
+
+## Test Data Rules
+
+- Avoid real names, messages, phone numbers, or URLs in fixtures.
+- Use synthetic names and pseudonymous tokens.
+- Add regression tests for parser edge cases.
+- Add privacy assertions when prompt payloads change.