# CI Test Setup Documentation

This document describes how the authentication tests and other backend tests are configured to run in CI.

## CI Workflow Configuration

The CI workflow (`.gitea/workflows/ci.yml`) has been updated to include:

### Test Database Setup

1. **PostgreSQL Service**: The CI uses a PostgreSQL 15 service container
   - Database: `punimtag_test` (main database)
   - Auth Database: `punimtag_auth_test` (auth database)
   - User: `postgres`
   - Password: `postgres`

2. **Database Creation**: Explicit database creation step ensures databases exist
   ```yaml
   - name: Create test databases
     run: |
       export PGPASSWORD=postgres
       psql -h postgres -U postgres -c "CREATE DATABASE punimtag_test;" || true
       psql -h postgres -U postgres -c "CREATE DATABASE punimtag_auth_test;" || true
   ```

3. **Schema Initialization**: Database schemas are initialized before tests run
   - Main database: All tables created via SQLAlchemy Base.metadata
   - Auth database: Tables created via SQL scripts

### Test Dependencies

The following testing dependencies are installed:
- `pytest>=7.4.0` - Test framework
- `httpx>=0.24.0` - HTTP client for FastAPI TestClient
- `pytest-cov>=4.1.0` - Coverage reporting

These are installed via:
1. `requirements.txt` (for local development)
2. Explicit pip install in CI (for redundancy)

### Test Execution

The CI runs tests in two steps:

1. **All Backend Tests**:
   ```bash
   pytest tests/ -v --tb=short --cov=backend --cov-report=term-missing --cov-report=xml
   ```
   - Runs all tests in the `tests/` directory
   - Generates coverage report
   - Uses short traceback format

2. **Authentication Tests** (specific step):
   ```bash
   pytest tests/test_api_auth.py -v --tb=short --junit-xml=test-results-auth.xml
   ```
   - Runs only authentication tests
   - Generates JUnit XML for test reporting
   - Provides focused output for authentication tests

### Environment Variables

The following environment variables are set in CI:
- `DATABASE_URL`: `postgresql+psycopg2://postgres:postgres@postgres:5432/punimtag_test`
- `DATABASE_URL_AUTH`: `postgresql+psycopg2://postgres:postgres@postgres:5432/punimtag_auth_test`
- `REDIS_URL`: `redis://redis:6379/0`
- `PYTHONPATH`: Set to project root

### Test Results

- Tests use `continue-on-error: true` to allow CI to complete even if tests fail
- Test results are logged to console
- JUnit XML output is generated for test reporting tools
- Coverage reports are generated (terminal and XML formats)

## Running Tests Locally

To run the same tests locally:

1. **Set up test database**:
   ```bash
   # Create test database
   createdb punimtag_test
   createdb punimtag_auth_test
   ```

2. **Set environment variables**:
   ```bash
   export DATABASE_URL="postgresql+psycopg2://postgres:postgres@localhost:5432/punimtag_test"
   export DATABASE_URL_AUTH="postgresql+psycopg2://postgres:postgres@localhost:5432/punimtag_auth_test"
   export PYTHONPATH=$(pwd)
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Run tests**:
   ```bash
   # Run all tests
   pytest tests/ -v

   # Run only authentication tests
   pytest tests/test_api_auth.py -v

   # Run with coverage
   pytest tests/ --cov=backend --cov-report=html
   ```

## Test Structure

### Test Files
- `tests/conftest.py` - Test fixtures and configuration
- `tests/test_api_auth.py` - Authentication API tests
- `tests/API_TEST_PLAN.md` - Comprehensive test plan

### Test Fixtures

The `conftest.py` provides:
- `test_db_engine` - Database engine (session scope)
- `test_db_session` - Database session with rollback (function scope)
- `test_client` - FastAPI test client (function scope)
- `admin_user` - Admin user fixture
- `regular_user` - Regular user fixture
- `inactive_user` - Inactive user fixture
- `auth_token` - Authentication token for admin
- `regular_auth_token` - Authentication token for regular user
- `auth_headers` - Authorization headers for admin
- `regular_auth_headers` - Authorization headers for regular user

## Troubleshooting

### Tests Fail in CI

1. **Check database connection**:
   - Verify PostgreSQL service is running
   - Check database URLs are correct
   - Ensure databases exist

2. **Check dependencies**:
   - Verify pytest, httpx, and pytest-cov are installed
   - Check requirements.txt is up to date

3. **Check test database state**:
   - Tests use transaction rollback, so database should be clean
   - If issues persist, check for schema mismatches

### Database Connection Issues

If tests fail with database connection errors:
- Verify `DATABASE_URL` environment variable is set
- Check PostgreSQL service is accessible
- Ensure database exists and user has permissions

### Import Errors

If tests fail with import errors:
- Verify `PYTHONPATH` is set to project root
- Check all dependencies are installed
- Ensure test files are in `tests/` directory

## Next Steps

1. Add more high-priority test files:
   - `test_api_photos.py` - Photo search tests
   - `test_api_faces.py` - Face identification tests
   - `test_api_users.py` - User management tests

2. Improve test coverage:
   - Add integration tests
   - Add error handling tests
   - Add performance tests

3. Enhance CI reporting:
   - Add test result artifacts
   - Add coverage badge
   - Add test summary to PR comments

