Initial commit: ROA2WEB - FastAPI + Vue.js + Telegram Bot
Modern ERP Reports Application with microservices architecture Tech Stack: - Backend: FastAPI + python-oracledb (Oracle DB integration) - Frontend: Vue.js 3 + PrimeVue + Vite - Telegram Bot: python-telegram-bot + SQLite - Infrastructure: Shared database pool, JWT authentication, SSH tunnel Features: - FastAPI backend with async Oracle connection pool - Vue.js 3 responsive frontend with PrimeVue components - Telegram bot alternative interface - Microservices architecture with shared components - Complete deployment support (Linux Docker + Windows IIS) - Comprehensive testing (Playwright E2E + pytest) Repository Structure: - reports-app/ - Main application (backend, frontend, telegram-bot) - shared/ - Shared components (database pool, auth, utils) - deployment/ - Deployment scripts (Linux & Windows) - docs/ - Project documentation - security/ - Security scanning and git hooks
This commit is contained in:
496
reports-app/telegram-bot/tests/DOCKER_TESTING_GUIDE.md
Normal file
496
reports-app/telegram-bot/tests/DOCKER_TESTING_GUIDE.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# 🐳 Docker Testing Guide - ROA2WEB Telegram Bot
|
||||
|
||||
This guide provides instructions for testing the Telegram bot Docker deployment.
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before testing Docker deployment:
|
||||
|
||||
- [ ] Docker Engine installed (version 20.10+)
|
||||
- [ ] Docker Compose installed (version 2.0+)
|
||||
- [ ] At least 2GB RAM available for containers
|
||||
- [ ] At least 10GB disk space available
|
||||
|
||||
## 🔍 Pre-Build Verification
|
||||
|
||||
### 1. Check Dockerfile Syntax
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/reports-app/telegram-bot
|
||||
|
||||
# Verify Dockerfile exists and is valid
|
||||
cat Dockerfile
|
||||
|
||||
# Check for common issues
|
||||
grep -n "COPY\|RUN\|ENV" Dockerfile
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Multi-stage build with `builder` and `production` stages
|
||||
- Non-root user `telegrambot` created
|
||||
- All required dependencies installed
|
||||
- Tini init system configured
|
||||
- Health check defined
|
||||
|
||||
### 2. Verify Required Files
|
||||
|
||||
```bash
|
||||
# Check all required files exist
|
||||
ls -la app/
|
||||
ls -la requirements.txt
|
||||
ls -la .env.example
|
||||
ls -la Dockerfile
|
||||
```
|
||||
|
||||
**Required files**:
|
||||
- ✅ `Dockerfile`
|
||||
- ✅ `requirements.txt`
|
||||
- ✅ `.env.example`
|
||||
- ✅ `app/` directory with all modules
|
||||
- ✅ `.dockerignore` (optional but recommended)
|
||||
|
||||
### 3. Check .dockerignore
|
||||
|
||||
```bash
|
||||
cat .dockerignore
|
||||
```
|
||||
|
||||
**Should exclude**:
|
||||
- `venv/`
|
||||
- `__pycache__/`
|
||||
- `*.pyc`
|
||||
- `.env`
|
||||
- `data/*.db`
|
||||
- `.git/`
|
||||
- `tests/`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Build Tests
|
||||
|
||||
### Test 1: Build Telegram Bot Image
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/reports-app/telegram-bot
|
||||
|
||||
# Build the image
|
||||
docker build -t roa2web/telegram-bot:test --target production .
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Build completes without errors
|
||||
- ✅ Both stages (builder + production) execute
|
||||
- ✅ Final image size < 500MB (typically ~300-400MB)
|
||||
- ✅ No security warnings in output
|
||||
|
||||
**Troubleshooting**:
|
||||
- If build fails at requirements install → check `requirements.txt` syntax
|
||||
- If permission errors → ensure Dockerfile uses correct user
|
||||
- If large image size → verify multi-stage build is working
|
||||
|
||||
### Test 2: Inspect Built Image
|
||||
|
||||
```bash
|
||||
# Check image size
|
||||
docker images roa2web/telegram-bot:test
|
||||
|
||||
# Inspect image details
|
||||
docker inspect roa2web/telegram-bot:test
|
||||
|
||||
# Check layers
|
||||
docker history roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Image size: 300-450 MB
|
||||
- Base: `python:3.11-slim`
|
||||
- User: `telegrambot` (not root)
|
||||
- Working dir: `/app`
|
||||
- Health check configured
|
||||
|
||||
### Test 3: Build with Docker Compose
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Build telegram-bot service
|
||||
docker-compose build roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Service builds successfully
|
||||
- ✅ Image tagged as `roa2web/telegram-bot:latest`
|
||||
- ✅ No errors or warnings
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Runtime Tests
|
||||
|
||||
### Test 4: Run Standalone Container (Without Backend)
|
||||
|
||||
```bash
|
||||
# Create test .env file
|
||||
cat > .env.test <<EOF
|
||||
TELEGRAM_BOT_TOKEN=test_token_here
|
||||
CLAUDE_API_KEY=test_api_key_here
|
||||
BACKEND_URL=http://localhost:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
LOG_LEVEL=DEBUG
|
||||
EOF
|
||||
|
||||
# Run container in test mode
|
||||
docker run --rm \
|
||||
--name telegram-bot-test \
|
||||
--env-file .env.test \
|
||||
-p 8002:8002 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Container starts without errors
|
||||
- ✅ Logs show "Telegram bot starting..."
|
||||
- ✅ Database initialized at `/app/data/telegram_bot.db`
|
||||
- ✅ Internal API listening on port 8002
|
||||
- ⚠️ May fail to connect to Telegram API (expected without valid token)
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
# In another terminal:
|
||||
# Check container is running
|
||||
docker ps | grep telegram-bot-test
|
||||
|
||||
# Check logs
|
||||
docker logs telegram-bot-test
|
||||
|
||||
# Test internal API health endpoint
|
||||
curl http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
### Test 5: Run with Docker Compose (Full Stack)
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Ensure .env file exists with all required variables
|
||||
cp .env.example .env
|
||||
# Edit .env and add:
|
||||
# - TELEGRAM_BOT_TOKEN
|
||||
# - CLAUDE_API_KEY
|
||||
# - ORACLE credentials
|
||||
# - JWT secret
|
||||
|
||||
# Start just the telegram-bot service (depends on backend)
|
||||
docker-compose up roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Dependencies start first: `roa-redis`, `roa-ssh-tunnel`, `roa-backend`
|
||||
- ✅ Backend health check passes
|
||||
- ✅ Telegram bot starts and connects to backend
|
||||
- ✅ SQLite database persists in `telegram-bot-data` volume
|
||||
|
||||
**Troubleshooting**:
|
||||
```bash
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# View logs
|
||||
docker-compose logs roa-telegram-bot
|
||||
docker-compose logs roa-backend
|
||||
|
||||
# Check networks
|
||||
docker network ls | grep roa-network
|
||||
docker network inspect roa-network
|
||||
```
|
||||
|
||||
### Test 6: Health Check
|
||||
|
||||
```bash
|
||||
# Wait for service to be healthy
|
||||
docker-compose ps roa-telegram-bot
|
||||
|
||||
# Should show: (healthy)
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Health check passes after ~40 seconds (start_period)
|
||||
- ✅ Health check endpoint returns 200 OK
|
||||
- ✅ Service status shows `(healthy)`
|
||||
|
||||
**Manual health check**:
|
||||
```bash
|
||||
# Access container
|
||||
docker exec -it roa-telegram-bot /bin/bash
|
||||
|
||||
# Inside container:
|
||||
python -c "import httpx; import asyncio; asyncio.run(httpx.AsyncClient().get('http://localhost:8002/internal/health'))"
|
||||
|
||||
# Should output: 200 OK
|
||||
```
|
||||
|
||||
### Test 7: Database Persistence
|
||||
|
||||
```bash
|
||||
# Start service
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Check database file exists
|
||||
docker exec roa-telegram-bot ls -la /app/data/
|
||||
|
||||
# Expected: telegram_bot.db file
|
||||
|
||||
# Stop and remove container
|
||||
docker-compose down
|
||||
|
||||
# Start again
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Verify data persisted
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db "SELECT COUNT(*) FROM telegram_users;"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Database file persists across container restarts
|
||||
- ✅ Data remains intact in `telegram-bot-data` volume
|
||||
- ✅ No data loss
|
||||
|
||||
### Test 8: Environment Variables
|
||||
|
||||
```bash
|
||||
# Check environment variables are set
|
||||
docker exec roa-telegram-bot env | grep -E "TELEGRAM|CLAUDE|BACKEND|SQLITE"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```
|
||||
TELEGRAM_BOT_TOKEN=<your_token>
|
||||
CLAUDE_API_KEY=<your_key>
|
||||
BACKEND_URL=http://roa-backend:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
```
|
||||
|
||||
### Test 9: Network Connectivity
|
||||
|
||||
```bash
|
||||
# Test bot can reach backend
|
||||
docker exec roa-telegram-bot curl -v http://roa-backend:8000/health
|
||||
|
||||
# Test backend can reach bot internal API
|
||||
docker exec roa-backend curl -v http://roa-telegram-bot:8002/internal/health
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Both services can communicate via `roa-network`
|
||||
- ✅ DNS resolution works (service names resolve)
|
||||
- ✅ Health endpoints return 200 OK
|
||||
|
||||
### Test 10: Logs and Monitoring
|
||||
|
||||
```bash
|
||||
# View real-time logs
|
||||
docker-compose logs -f roa-telegram-bot
|
||||
|
||||
# View last 100 lines
|
||||
docker-compose logs --tail=100 roa-telegram-bot
|
||||
|
||||
# Search for errors
|
||||
docker-compose logs roa-telegram-bot | grep -i error
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Logs are readable and structured
|
||||
- ✅ No critical errors
|
||||
- ✅ Log level respects `LOG_LEVEL` env var
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Tests
|
||||
|
||||
### Test 11: User Permissions
|
||||
|
||||
```bash
|
||||
# Check container is not running as root
|
||||
docker exec roa-telegram-bot whoami
|
||||
# Expected: telegrambot
|
||||
|
||||
# Check file permissions
|
||||
docker exec roa-telegram-bot ls -la /app/
|
||||
# Expected: All files owned by telegrambot:telegrambot
|
||||
```
|
||||
|
||||
### Test 12: Port Exposure
|
||||
|
||||
```bash
|
||||
# Check exposed ports
|
||||
docker port roa-telegram-bot
|
||||
|
||||
# Should only show:
|
||||
# 8002/tcp -> 0.0.0.0:8002
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only internal API port (8002) exposed
|
||||
- ✅ No unnecessary ports open
|
||||
|
||||
### Test 13: Volume Mounts
|
||||
|
||||
```bash
|
||||
# Check volumes
|
||||
docker volume inspect roa2web_telegram-bot-data
|
||||
|
||||
# Check mount point
|
||||
docker inspect roa-telegram-bot | grep -A 10 Mounts
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only `/app/data` is mounted
|
||||
- ✅ Volume is named `telegram-bot-data`
|
||||
- ✅ No sensitive files mounted
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Integration Tests
|
||||
|
||||
### Test 14: Full Stack Integration
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
cd /path/to/roa2web
|
||||
docker-compose up -d
|
||||
|
||||
# Wait for all services to be healthy
|
||||
docker-compose ps
|
||||
|
||||
# Test complete flow:
|
||||
# 1. Backend generates auth code
|
||||
# 2. Bot verifies code
|
||||
# 3. User links account
|
||||
# 4. Bot queries backend API
|
||||
```
|
||||
|
||||
**Test Steps**:
|
||||
|
||||
1. **Generate Auth Code via Backend**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/telegram/auth/generate-code \
|
||||
-H "Authorization: Bearer <jwt_token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"telegram_user_id": 123456}'
|
||||
```
|
||||
|
||||
2. **Verify Code in Bot Database**:
|
||||
```bash
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db \
|
||||
"SELECT * FROM telegram_auth_codes WHERE telegram_user_id = 123456;"
|
||||
```
|
||||
|
||||
3. **Link via Telegram Bot**:
|
||||
- Send code to bot via Telegram app
|
||||
- Verify linking succeeds
|
||||
|
||||
4. **Query Dashboard**:
|
||||
- Ask bot: "Show dashboard for company 1"
|
||||
- Verify data is retrieved from backend
|
||||
|
||||
---
|
||||
|
||||
## 🛑 Cleanup
|
||||
|
||||
### Remove Test Containers
|
||||
|
||||
```bash
|
||||
# Stop and remove containers
|
||||
docker-compose down
|
||||
|
||||
# Remove volumes (WARNING: deletes data)
|
||||
docker-compose down -v
|
||||
|
||||
# Remove images
|
||||
docker rmi roa2web/telegram-bot:test
|
||||
docker rmi roa2web/telegram-bot:latest
|
||||
```
|
||||
|
||||
### Clean Build Cache
|
||||
|
||||
```bash
|
||||
# Remove build cache
|
||||
docker builder prune -a
|
||||
|
||||
# Remove unused images
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Results Checklist
|
||||
|
||||
| Test ID | Description | Status | Notes |
|
||||
|---------|-------------|--------|-------|
|
||||
| 1 | Build telegram-bot image | ⬜ | |
|
||||
| 2 | Inspect image | ⬜ | |
|
||||
| 3 | Build with docker-compose | ⬜ | |
|
||||
| 4 | Run standalone container | ⬜ | |
|
||||
| 5 | Run with docker-compose | ⬜ | |
|
||||
| 6 | Health check | ⬜ | |
|
||||
| 7 | Database persistence | ⬜ | |
|
||||
| 8 | Environment variables | ⬜ | |
|
||||
| 9 | Network connectivity | ⬜ | |
|
||||
| 10 | Logs and monitoring | ⬜ | |
|
||||
| 11 | User permissions | ⬜ | |
|
||||
| 12 | Port exposure | ⬜ | |
|
||||
| 13 | Volume mounts | ⬜ | |
|
||||
| 14 | Full stack integration | ⬜ | |
|
||||
|
||||
**Overall Result**: ⬜ PASS ⬜ FAIL
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### Issue 1: Build Fails - "requirements.txt not found"
|
||||
**Solution**: Ensure you're in the correct directory (`telegram-bot/`) when building
|
||||
|
||||
### Issue 2: Permission Denied Errors
|
||||
**Solution**: Check Dockerfile uses correct user and permissions are set with `chown`
|
||||
|
||||
### Issue 3: Health Check Fails
|
||||
**Solution**:
|
||||
- Check internal API is starting on port 8002
|
||||
- Verify httpx is installed in requirements.txt
|
||||
- Check logs: `docker logs roa-telegram-bot`
|
||||
|
||||
### Issue 4: Can't Connect to Backend
|
||||
**Solution**:
|
||||
- Ensure both containers are on `roa-network`
|
||||
- Check backend is healthy before starting bot
|
||||
- Use service name `roa-backend` not `localhost`
|
||||
|
||||
### Issue 5: Database Not Persisting
|
||||
**Solution**:
|
||||
- Verify volume is mounted: `docker inspect roa-telegram-bot`
|
||||
- Check volume exists: `docker volume ls | grep telegram-bot-data`
|
||||
- Ensure `/app/data` has write permissions
|
||||
|
||||
---
|
||||
|
||||
## ✅ Success Criteria
|
||||
|
||||
For Docker deployment to be considered successful:
|
||||
|
||||
- ✅ Image builds without errors
|
||||
- ✅ Container starts and runs stably
|
||||
- ✅ Health checks pass
|
||||
- ✅ Bot connects to Telegram API
|
||||
- ✅ Bot connects to backend API
|
||||
- ✅ Database persists across restarts
|
||||
- ✅ No security warnings or vulnerabilities
|
||||
- ✅ Logs are clean (no critical errors)
|
||||
- ✅ All network connectivity works
|
||||
- ✅ Full stack integration succeeds
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-21
|
||||
365
reports-app/telegram-bot/tests/MANUAL_TESTING_CHECKLIST.md
Normal file
365
reports-app/telegram-bot/tests/MANUAL_TESTING_CHECKLIST.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# 📋 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:8001`)
|
||||
- [ ] SSH tunnel to Oracle DB is active
|
||||
- [ ] Telegram bot is running (`python -m app.main`)
|
||||
- [ ] TELEGRAM_BOT_TOKEN is configured in `.env`
|
||||
- [ ] CLAUDE_API_KEY is configured in `.env` (if using real Claude SDK)
|
||||
- [ ] SQLite database is initialized (`data/telegram_bot.db` exists)
|
||||
|
||||
## 📱 Test Environment Setup
|
||||
|
||||
### Start Services
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start backend API (from roa2web/)
|
||||
cd reports-app/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
|
||||
# Terminal 2: Start Telegram bot
|
||||
cd reports-app/telegram-bot
|
||||
source venv/bin/activate
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
### 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
|
||||
213
reports-app/telegram-bot/tests/README_INTEGRATION_TESTS.md
Normal file
213
reports-app/telegram-bot/tests/README_INTEGRATION_TESTS.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Integration Tests Guide
|
||||
|
||||
This directory contains both **unit tests** (with mocks) and **integration tests** (with real data).
|
||||
|
||||
## Test Categories
|
||||
|
||||
### Unit Tests (Default)
|
||||
- **Files**: `test_*.py` (except `*_real*.py`)
|
||||
- **Dependencies**: None (all mocked)
|
||||
- **Speed**: Fast (~2-3 seconds)
|
||||
- **Run by**: CI/CD, developers
|
||||
- **Command**: `pytest` (runs by default)
|
||||
|
||||
**Examples**:
|
||||
- `test_auth.py` - Authentication flow tests
|
||||
- `test_tools.py` - Claude Agent tools tests
|
||||
- `test_helpers.py` - Bot helper functions tests
|
||||
- `test_formatters.py` - Response formatters tests
|
||||
- `test_session_company.py` - Session management tests
|
||||
|
||||
### Integration Tests (Manual)
|
||||
- **Files**: `test_helpers_real*.py`
|
||||
- **Dependencies**: Backend API + Database/Environment
|
||||
- **Speed**: Slower (~10-30 seconds)
|
||||
- **Run by**: Developers manually
|
||||
- **Command**: `pytest -m integration`
|
||||
- **Marked with**: `@pytest.mark.integration`
|
||||
|
||||
**Examples**:
|
||||
- `test_helpers_real.py` - Integration tests with SQLite DB
|
||||
- `test_helpers_real_simple.py` - Integration tests with direct API auth
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Run All Unit Tests (Default)
|
||||
```bash
|
||||
# Runs all tests EXCEPT integration tests
|
||||
pytest
|
||||
|
||||
# Explicit: run only unit tests
|
||||
pytest -m "not integration"
|
||||
```
|
||||
|
||||
### Run Integration Tests
|
||||
```bash
|
||||
# Run only integration tests
|
||||
pytest -m integration
|
||||
|
||||
# Run specific integration test file
|
||||
pytest tests/test_helpers_real.py -m integration
|
||||
|
||||
# Run as standalone script (alternative)
|
||||
python tests/test_helpers_real_simple.py
|
||||
```
|
||||
|
||||
### Run ALL Tests (Unit + Integration)
|
||||
```bash
|
||||
# Override default filter
|
||||
pytest -m ""
|
||||
```
|
||||
|
||||
## Integration Test Requirements
|
||||
|
||||
### For `test_helpers_real.py`:
|
||||
- ✅ Backend API running on `localhost:8001`
|
||||
- ✅ SQLite database (`data/telegram_bot.db`) with at least one linked user
|
||||
- ⚠️ Requires existing user session in database
|
||||
|
||||
### For `test_helpers_real_simple.py`:
|
||||
- ✅ Backend API running on `localhost:8001`
|
||||
- ✅ Environment variables set:
|
||||
```bash
|
||||
export TEST_USERNAME="your_oracle_username"
|
||||
export TEST_PASSWORD="your_oracle_password"
|
||||
```
|
||||
- ✅ Valid Oracle credentials for backend authentication
|
||||
|
||||
## Setting Up Integration Tests
|
||||
|
||||
### 1. Start Backend API
|
||||
```bash
|
||||
cd roa2web/reports-app/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
```
|
||||
|
||||
### 2. Set Credentials (for `test_helpers_real_simple.py`)
|
||||
```bash
|
||||
# In your shell or .env file
|
||||
export TEST_USERNAME="MARIUS M" # Your Oracle username
|
||||
export TEST_PASSWORD="your_password" # Your Oracle password
|
||||
```
|
||||
|
||||
### 3. Run Integration Tests
|
||||
```bash
|
||||
cd roa2web/reports-app/telegram-bot
|
||||
source venv/bin/activate
|
||||
pytest -m integration -v
|
||||
```
|
||||
|
||||
## CI/CD Configuration
|
||||
|
||||
Integration tests are **automatically skipped** in CI/CD pipelines because:
|
||||
- They require external services (backend API, database)
|
||||
- They need real credentials
|
||||
- Default pytest configuration excludes them: `-m "not integration"`
|
||||
|
||||
To run them in CI/CD, you would need to:
|
||||
1. Set up backend API service
|
||||
2. Provide TEST_USERNAME and TEST_PASSWORD as secrets
|
||||
3. Override pytest command: `pytest -m ""`
|
||||
|
||||
## Markers Reference
|
||||
|
||||
Defined in `pytest.ini`:
|
||||
|
||||
```ini
|
||||
markers =
|
||||
unit: Unit tests with mocks (fast, no external dependencies)
|
||||
integration: Integration tests with real backend/database (slow, requires setup)
|
||||
slow: Slow tests that take more than 1 second
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pytest -m unit # Run only unit tests
|
||||
pytest -m integration # Run only integration tests
|
||||
pytest -m slow # Run only slow tests
|
||||
pytest -m "not slow" # Skip slow tests
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Writing Tests
|
||||
|
||||
**Unit Tests (Preferred for most cases)**:
|
||||
- ✅ Fast and reliable
|
||||
- ✅ No external dependencies
|
||||
- ✅ Use mocks (`unittest.mock`, `AsyncMock`)
|
||||
- ✅ Test one component at a time
|
||||
- ✅ Run in CI/CD
|
||||
|
||||
**Integration Tests (Use sparingly)**:
|
||||
- ⚠️ Slower and can be flaky
|
||||
- ⚠️ Require full environment setup
|
||||
- ⚠️ Test multiple components together
|
||||
- ⚠️ Manual execution only
|
||||
- ✅ Useful for validation before releases
|
||||
- ✅ Document real usage patterns
|
||||
|
||||
### Coverage Goals
|
||||
|
||||
- **Unit tests**: Aim for 80%+ code coverage
|
||||
- **Integration tests**: Focus on critical paths and end-to-end flows
|
||||
- Don't duplicate: If unit tests cover it well, integration tests may be redundant
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Integration Tests Fail
|
||||
1. **Check backend is running**: `curl http://localhost:8001/health`
|
||||
2. **Verify credentials**: Ensure `TEST_USERNAME` and `TEST_PASSWORD` are set
|
||||
3. **Check database**: Ensure `data/telegram_bot.db` exists and has users
|
||||
4. **Review logs**: Check backend logs for API errors
|
||||
|
||||
### Integration Tests Skipped
|
||||
- This is normal! They're skipped by default.
|
||||
- Use `pytest -m integration` to run them explicitly.
|
||||
|
||||
### Import Errors
|
||||
```bash
|
||||
# Make sure you're in the right directory
|
||||
cd /mnt/e/proiecte/roa2web/roa2web/reports-app/telegram-bot
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
### Unit Tests (Default)
|
||||
```bash
|
||||
$ pytest
|
||||
============================= test session starts ==============================
|
||||
collected 93 items / 5 deselected / 88 selected
|
||||
|
||||
tests/test_auth.py ............ [ 13%]
|
||||
tests/test_formatters.py ................ [ 31%]
|
||||
tests/test_helpers.py .................. [ 51%]
|
||||
tests/test_session_company.py .................. [ 72%]
|
||||
tests/test_tools.py .................. [100%]
|
||||
|
||||
======================== 88 passed, 5 deselected in 3.42s ======================
|
||||
```
|
||||
|
||||
### Integration Tests (Explicit)
|
||||
```bash
|
||||
$ pytest -m integration
|
||||
============================= test session starts ==============================
|
||||
collected 93 items / 88 deselected / 5 selected
|
||||
|
||||
tests/test_helpers_real.py .... [ 80%]
|
||||
tests/test_helpers_real_simple.py . [100%]
|
||||
|
||||
======================== 5 passed, 88 deselected in 12.37s =====================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-22
|
||||
**Author**: Claude Code Session
|
||||
3
reports-app/telegram-bot/tests/__init__.py
Normal file
3
reports-app/telegram-bot/tests/__init__.py
Normal file
@@ -0,0 +1,3 @@
|
||||
"""
|
||||
ROA2WEB Telegram Bot - Test Suite
|
||||
"""
|
||||
Reference in New Issue
Block a user