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

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)

# Runs all tests EXCEPT integration tests
pytest

# Explicit: run only unit tests
pytest -m "not integration"

Run Integration Tests

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

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

  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

cd roa2web/backend
source venv/bin/activate
uvicorn app.main:app --reload --port 8001

2. Set Credentials (for test_helpers_real_simple.py)

# 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

cd roa2web/backend/modules/telegram
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:

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:

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

# Make sure you're in the right directory
cd /mnt/e/proiecte/roa2web/roa2web/backend/modules/telegram

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Example Output

Unit Tests (Default)

$ 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)

$ 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