claude-telegram-bot/docs/test-plan.md

Master Test Plan — Claude Telegram Bot

Compiled from per-block test plans produced during implementation.

---

Block 1: Project Scaffolding

• 1.1: git log --oneline shows initial commit
• 1.2: bun run src/index.ts starts without errors (with valid .env)
• 1.3: .env is NOT tracked by git
• 1.4: git show --stat HEAD~8 shows exactly: .gitignore, bun.lock, package.json, src/index.ts, tsconfig.json
• 1.5: node_modules/ exists with dependencies installed

Block 2: State Store (src/state/store.ts)

• 2.1: new Store() returns default state { projects: {}, sessions: {}, activeSession: null } when no state file exists
• 2.2: store.save() creates ~/.claude-telegram-bot/state.json with valid JSON
• 2.3: Save then load round-trips correctly — write state, create new Store, verify data matches
• 2.4: save() auto-creates ~/.claude-telegram-bot/ directory if missing
• 2.5: TypeScript rejects invalid SessionInfo.status values (only "idle" | "busy")

Block 3: Session Manager (src/services/session-manager.ts)

• 3.1: activeSession returns null when no session started
• 3.2: createSession sets session data, marks as active, and persists
• 3.3: stopSession removes session, reassigns active to remaining (or null)
• 3.4: stopSession returns false for unknown session name
• 3.5: stopAll clears all sessions, sets activeSession to null, returns count
• 3.6: switchSession updates activeSession and returns true for valid name
• 3.7: switchSession returns false for unknown name
• 3.8: setStatus updates only status field, no-ops for unknown session
• 3.9: resolveProjectPath returns bookmarked path when name matches a project
• 3.10: resolveProjectPath extracts basename from path for non-bookmarked input
• 3.11: generateName appends -2, -3 on name conflicts
• 3.12: saveProject / removeProject CRUD works correctly
• 3.13: Every mutating method calls store.save() exactly once

Block 4: Claude Service (src/services/claude.ts)

• 4.1: createSession returns non-empty sessionId with valid prompt and cwd
• 4.2: createSession returns non-empty result string
• 4.3: sendMessage with valid sessionId resumes context and returns result
• 4.4: Session context is preserved — sendMessage result reflects prior conversation
• 4.5: Invalid sessionId in sendMessage throws or returns empty string gracefully
• 4.6: cwd is respected — Claude tools resolve paths relative to it
• 4.7: Multi-message stream handled — only final result captured

Block 5: Telegram Utilities (src/utils/telegram.ts)

• 5.1: Short message (<=4096 chars) returns single-element array
• 5.2: Exactly 4096 chars returns single-element array (boundary)
• 5.3: Long message with \n\n splits at paragraph boundary
• 5.4: Long message with only \n splits at line boundary
• 5.5: Long message with no whitespace hard-splits at 4096
• 5.6: All chunks are <= 4096 characters
• 5.7: No data loss — concatenated chunks reconstruct original content
• 5.8: escapeMarkdown returns input unchanged

Block 6: Command Handlers (src/handlers/commands.ts)

• 6.1: /start without argument shows usage
• 6.2: /start <path> with existing session name suggests /switch
• 6.3: /start <path> creates Claude session, registers in manager, replies with result
• 6.4: /stop with no active session replies "Nothing to stop"
• 6.5: /stop <name> removes session, shows next active if any
• 6.6: /stop <name> for unknown session replies "not found"
• 6.7: /stopall stops all, reports count
• 6.8: /switch without argument shows usage
• 6.9: /switch <name> switches and confirms
• 6.10: /switch <name> for unknown session shows error + hint
• 6.11: /sessions with no sessions replies "No active sessions"
• 6.12: /sessions lists sessions with ► marker and inline keyboard
• 6.13: /status with no session replies "No active session"
• 6.14: /status shows name, path, status
• 6.15: /save with <2 args shows usage
• 6.16: /save <name> <path> saves and confirms
• 6.17: /remove <name> removes or says "not found"
• 6.18: /projects shows list with inline "Start" buttons
• 6.19: /help shows full command reference

Block 7: Message Handler (src/handlers/message.ts)

• 7.1: Non-text message ignored silently
• 7.2: Text with no active session shows "No active session" message
• 7.3: Text when session busy shows "Session is busy" message
• 7.4: Status set to "busy" before Claude call, "idle" after (including on error)
• 7.5: Typing indicator sent before Claude call
• 7.6: Response split into chunks and sent sequentially
• 7.7: Empty Claude response sends "(empty response)"
• 7.8: Claude error caught, error message sent, status reset to idle

Block 8: Bot Setup (src/bot.ts)

• 8.1: createBot returns Bot instance without errors
• 8.2: Non-owner messages silently dropped by middleware
• 8.3: Owner messages reach handlers
• 8.4: switch: callback switches session and confirms
• 8.5: start: callback for unknown project answers "not found"
• 8.6: start: callback for existing session switches instead of creating
• 8.7: start: callback for new project creates session via Claude
• 8.8: Claude error in start: callback sends error message
• 8.9: All imports are static, createBot is synchronous

Block 9: Entry Point (src/index.ts)

• 9.1: Missing TELEGRAM_BOT_TOKEN throws with clear message
• 9.2: Missing TELEGRAM_OWNER_ID throws with clear message
• 9.3: Missing ANTHROPIC_API_KEY throws with clear message
• 9.4: All vars present — bot starts, logs "Bot started successfully"
• 9.5: TELEGRAM_OWNER_ID converted to number
• 9.6: SIGINT triggers graceful shutdown with "Shutting down..." log
• 9.7: .env file loaded by dotenv/config

---

Integration / Smoke Test

• E2E-1: /help — shows command list
• E2E-2: /start /d/claude_telegram_bot — creates session, Claude responds
• E2E-3: What files are in this directory? — Claude lists project files
• E2E-4: /status — shows session name, path, idle status
• E2E-5: /sessions — shows list with inline button
• E2E-6: Click inline button — switches session
• E2E-7: /save mybot /d/claude_telegram_bot — saves bookmark
• E2E-8: /projects — shows bookmark with "Start" button
• E2E-9: /stop — stops session
• E2E-10: /sessions — shows "No active sessions"
• E2E-11: Send text without session — shows "No active session" error
• E2E-12: Message from non-owner — silently ignored