roa2web-service-auto/docs/telegram/testing/MANUAL_TESTING_CHECKLIST.md

📋 Manual Testing Checklist - ROA2WEB Telegram Bot

This checklist guides you through manual testing of the Telegram bot functionality.

🔧 Prerequisites

Before starting manual tests:

• Backend API is running (http://localhost:8000 or 8001)
• SSH tunnel to Oracle DB is active (Linux dev only)
• MODULE_TELEGRAM_ENABLED=true in .env
• TELEGRAM_BOT_TOKEN is configured in .env
• SQLite database is initialized (auto-created on first run)

Note: In the ultrathin monolith architecture, the Telegram bot runs as a background task within the unified backend. There's no separate bot process to start.

📱 Test Environment Setup

Start Services

# From project root - starts everything (SSH tunnel + backend + frontend)
./start.sh prod

# Or for testing mode:
./start.sh test

# Check status
./status.sh

The bot starts automatically with the backend when MODULE_TELEGRAM_ENABLED=true.

Test User Setup

• Create test Oracle user account in Oracle database (if needed)
• Have test Telegram account ready (@testuser or similar)
• Know the Telegram user ID (can be found via bot command /start)

---

✅ Test Cases

1. Bot Discovery & Initial Contact

Test 1.1: Start Bot

• Open Telegram and search for @ROA2WEBBot
• Click "Start" or send /start command
• Expected: Bot responds with welcome message explaining linking process
• Expected: Bot asks for authentication code

Test 1.2: Help Command

• Send /help command
• Expected: Bot shows list of available commands with descriptions
• Expected: Includes /start, /help, /clear, /companies, /unlink

---

2. Authentication Flow

Test 2.1: Generate Linking Code (via Web)

• Open web frontend (Vue.js app)
• Login with Oracle credentials
• Navigate to Telegram linking page (if available)
• Click "Generate Telegram Linking Code"
• Expected: 8-character code is displayed (e.g., ABC23456)
• Expected: Code expires in 5 minutes message shown

Test 2.2: Link Account with Valid Code

• In Telegram bot, send the 8-character code from Step 2.1
• Expected: Bot responds with "Successfully linked to Oracle account [username]"
• Expected: Bot shows list of companies you have access to
• Expected: User is now authenticated and can use bot features

Test 2.3: Try to Link with Invalid Code

• Send an invalid code like INVALID1
• Expected: Bot responds with "Invalid or expired code" message
• Expected: Bot prompts to generate new code via web

Test 2.4: Try to Link with Expired Code

• Generate a code via web
• Wait 6+ minutes (past expiration)
• Send expired code to bot
• Expected: Bot responds with "Code has expired" message
• Expected: Bot suggests generating new code

Test 2.5: Try to Reuse Code

• Generate new code and link successfully
• Unlink account (/unlink)
• Try to use the same code again
• Expected: Bot rejects code with "Code already used" message

---

3. User Commands (When Linked)

Test 3.1: Companies Command

• Send /companies command
• Expected: Bot lists all companies user has access to
• Expected: Shows company ID, name, and CUI
• Expected: Format is clear and readable

Test 3.2: Clear History Command

• Have some conversation history with bot
• Send /clear command
• Expected: Bot confirms conversation history cleared
• Expected: Bot resets context for new conversation

Test 3.3: Unlink Command

• Send /unlink command
• Expected: Bot shows confirmation warning
• Expected: Shows inline keyboard with "Yes" / "No" buttons
• Press "No" button
• Expected: Unlinking cancelled, account still linked
• Send /unlink again and press "Yes"
• Expected: Account unlinked successfully
• Expected: Bot requires new authentication code to continue

---

4. Conversational Queries (Claude Agent)

Note: These tests require Claude Agent SDK integration to be complete.

Test 4.1: Simple Dashboard Query

• Send message: "Show me the dashboard for company 1"
• Expected: Bot retrieves dashboard data
• Expected: Shows total balance, invoices count, payments, etc.
• Expected: Data is formatted in Romanian language

Test 4.2: Invoice Search Query

• Send: "Find unpaid invoices from October 2025"
• Expected: Bot searches invoices with filters
• Expected: Returns list of matching invoices
• Expected: Shows invoice number, date, client, amount, status

Test 4.3: Treasury Query

• Send: "What's the current treasury status for company 1?"
• Expected: Bot retrieves treasury data
• Expected: Shows cash balance, bank accounts, payments

Test 4.4: Export Request

• Send: "Export unpaid invoices to Excel"
• Expected: Bot generates Excel file
• Expected: Sends file via Telegram
• Expected: File name includes report type and timestamp
• Expected: File can be downloaded and opened

Test 4.5: Complex Multi-Step Query

• Send: "Show me the dashboard, then find invoices over 5000 RON, and export them to PDF"
• Expected: Bot handles multi-step request correctly
• Expected: Executes each tool in sequence
• Expected: Provides updates on progress
• Expected: Final PDF file is sent

Test 4.6: Romanian Language Support

• Send messages in Romanian
• Expected: Bot understands and responds in Romanian
• Expected: Romanian characters displayed correctly (ă, â, î, ș, ț)

---

5. Error Handling

Test 5.1: Query Before Authentication

• Start new bot conversation (or use fresh account)
• Send query without linking: "Show dashboard"
• Expected: Bot responds with "Please authenticate first"
• Expected: Bot provides instructions to link account

Test 5.2: Invalid Company ID

• Send: "Show dashboard for company 9999"
• Expected: Bot responds with "Company not found" or "No access" message
• Expected: Suggests using /companies to see available companies

Test 5.3: Backend API Offline

• Stop backend API server
• Try to send query to bot
• Expected: Bot responds with "Service temporarily unavailable" message
• Expected: Suggests trying again later

Test 5.4: Token Expiration

• Link account and wait for JWT token to expire (30 minutes)
• Send query after expiration
• Expected: Bot automatically refreshes token
• Expected: Query succeeds without re-authentication

Test 5.5: Invalid Export Format

• Send: "Export dashboard to invalidformat"
• Expected: Bot responds with supported formats (xlsx, csv, pdf)
• Expected: Asks user to specify valid format

---

6. Session Management

Test 6.1: Conversation Context

• Send: "Show dashboard for company 1"
• Bot responds with data
• Send follow-up: "Now show invoices"
• Expected: Bot remembers company 1 from context
• Expected: Shows invoices for company 1

Test 6.2: Session Persistence

• Have conversation with bot
• Stop and restart Telegram bot application
• Resume conversation
• Expected: User is still linked (SQLite data persists)
• Expected: Can immediately send queries without re-authentication

Test 6.3: Multiple Users

• Use two different Telegram accounts
• Link both to different Oracle users
• Send queries from both accounts simultaneously
• Expected: Each user gets their own data
• Expected: No data mixing between users
• Expected: Sessions isolated correctly

---

7. Database Operations

Test 7.1: Check User Record

# In terminal
sqlite3 data/telegram_bot.db
SELECT * FROM telegram_users;

• Expected: User record exists with telegram_user_id
• Expected: oracle_username is populated after linking
• Expected: jwt_token and token_expires_at are set

Test 7.2: Check Auth Codes

SELECT * FROM telegram_auth_codes WHERE oracle_username = 'testuser';

• Expected: Used codes have used_at timestamp
• Expected: Expired codes have expires_at in the past

Test 7.3: Database Cleanup

• Generate expired auth code (wait 6 minutes or manually update DB)
• Wait for cleanup task to run (runs hourly)
• Expected: Expired codes are removed from database
• Expected: Database size doesn't grow indefinitely

---

8. Performance & Reliability

Test 8.1: Response Time

• Send simple query: "Show dashboard"
• Measure time from send to receive response
• Expected: Response within 3-5 seconds
• Expected: No timeouts

Test 8.2: Large Data Export

• Request export of large dataset (100+ invoices)
• Expected: Bot handles large exports gracefully
• Expected: File generates successfully
• Expected: File size is reasonable (<10MB for typical data)

Test 8.3: Concurrent Requests

• Send multiple queries rapidly (3-4 in quick succession)
• Expected: All queries are processed
• Expected: Responses arrive in correct order
• Expected: No crashes or errors

---

9. Security Tests

Test 9.1: Unauthorized Access

• Without linking, try to call backend API directly with fake token
• Expected: Backend rejects request with 401 Unauthorized

Test 9.2: Token in Database

sqlite3 data/telegram_bot.db
SELECT jwt_token FROM telegram_users LIMIT 1;

• Expected: Token exists in database
• Note: Ensure database file is properly secured in production
• Note: Database should not be committed to git

Test 9.3: Code Security

• Generate linking code
• Try to guess codes by brute force
• Expected: Codes are random and hard to guess (8 chars, no ambiguous chars)
• Expected: Codes expire after 5 minutes

---

📊 Test Results

Summary

Test Category	Total Tests	Passed	Failed	Skipped
Bot Discovery	2	-	-	-
Authentication Flow	5	-	-	-
User Commands	3	-	-	-
Conversational Queries	6	-	-	-
Error Handling	5	-	-	-
Session Management	3	-	-	-
Database Operations	3	-	-	-
Performance	3	-	-	-
Security	3	-	-	-
TOTAL	33	0	0	0

Failed Tests

List any failed tests here with details:

Test ID	Description	Error	Notes
-	-	-	-

Notes & Issues

Document any issues discovered during testing:

---

🐛 Reporting Issues

If you find bugs during manual testing:

1. Document:

   • Test case ID
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • Error messages (if any)
   • Screenshots (if applicable)

2. Check Database State:

   sqlite3 data/telegram_bot.db
   # Inspect relevant tables
   

3. Check Logs:

   • Telegram bot logs (console output)
   • Backend API logs
   • SQLite database queries

4. Create Issue:

   • File bug in project issue tracker
   • Include all documentation from step 1

---

✅ Test Completion

Tester Name: _______________

Date: _______________

Overall Result: [ ] PASS [ ] FAIL

Sign-off: _______________

---

Last Updated: 2025-10-21