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)
```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/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/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`:

```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/backend/modules/telegram

# 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