# Manual test: WhatsApp pairing end-to-end

Run this checklist on every release that touches the pairing flow. It can't be
automated — pairing requires a real phone scanning a QR.

## Prerequisites
- `.env.development` filled in with real values.
- `scripts/db.sh migrate && scripts/db.sh seed` ran clean.
- `scripts/dev.sh up` is running; `scripts/dev.sh logs bot` is tailing.
- Dev WhatsApp mock account installed on a test phone (NOT brother's prod accounts).
- Dev Telegram bot opened in Telegram.

## Steps

1. Send `/start` to the dev bot. Expected: welcome message.
2. Send `/help`. Expected: command list including `/pair`.
3. Send `/pair "Test Account 1"`. Expected:
   - Reply: "📡 Starting pairing for 'Test Account 1'..."
   - Within ~5 seconds, a QR PNG arrives.
4. On the test phone: WhatsApp → Settings → Linked Devices → Link a Device → scan the QR.
5. Within ~5 seconds expect Telegram replies:
   - "✅ 'Test Account 1' connected as +60xxxxxxx" (your test phone number).
   - "Synced N groups. Ready to send reminders." (N = number of WA groups).
6. Send `/accounts`. Expected: "• Test Account 1 (+60xxx) — db:connected live:connected".
7. Send `/groups "Test Account 1"`. Expected: bulleted list of groups.
8. Verify in Postgres:
   ```bash
   NO_SUDO=1 scripts/dev.sh exec sh -c 'cd packages/db && pnpm exec tsx -e "
   (async () => {
     const { Pool } = await import(\"pg\");
     const p = new Pool({ connectionString: process.env.DATABASE_URL });
     console.log(\"accounts:\", (await p.query(\"SELECT label, status, phone_number FROM whatsapp_accounts\")).rows);
     console.log(\"groups:\", (await p.query(\"SELECT count(*) FROM whatsapp_groups\")).rows);
     console.log(\"audit:\", (await p.query(\"SELECT action FROM audit_log ORDER BY created_at DESC LIMIT 5\")).rows);
     await p.end();
   })();
   "'
   ```
   Expected: account connected, groups present, audit shows `account.paired`.
9. Restart the bot: `NO_SUDO=1 scripts/dev.sh restart-bot`. Expected: in logs, "session-manager: state change connecting → connected" for the test account, no QR re-prompt.
10. Send `/unpair "Test Account 1"`. Expected:
    - Reply: "🗑 'Test Account 1' unpaired. Session files deleted."
    - `whatsapp_accounts.status` is `logged_out`.
    - Directory `dev-data/sessions/<account-id>/` is gone.

## Failure modes to verify

- **QR expiry:** ignore the QR for 30s. Bot edits the same Telegram message with a new QR (no second photo). Repeat 3-5 times to verify edits keep working.
- **Wrong-account `/pair`:** as a non-whitelisted Telegram user, send `/pair "X"`. Expected: "Sorry, this bot is private."
- **Re-pair while connected:** send `/pair "Test Account 1"` again immediately after step 5. Expected: "already connected. Use /unpair first."

## Sign-off
- [ ] All steps passed
- [ ] Postgres rows match expectations
- [ ] No errors in `scripts/dev.sh logs bot`
- [ ] Tester: ____________   Date: ____________