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:
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
|
||||
Reference in New Issue
Block a user