# 📋 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

```bash
# 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**
```bash
# 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**
```sql
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**
```bash
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**:
   ```bash
   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