cm_whatsapp_bot_v1/docs/superpowers/specs/manual-test-pairing.md

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:

   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: ____________