# Testing Documentation

Test suite for the Veris AI Python SDK with comprehensive coverage of mocking, tracing, and utility functions.

## Quick Reference

**Purpose**: Automated testing with pytest, fixtures, and async support  
**Coverage Target**: Core functionality, edge cases, type conversion  
**Test Runner**: `pytest --cov=veris_ai --cov-report=term-missing`

## Test Structure

**Semantic Tag**: `test-organization`

| Test File | Coverage | Key Areas | Lines |
|-----------|----------|-----------|-------|
| [`test_tool_mock.py`](test_tool_mock.py) | VerisSDK, decorators | Mock/spy modes, FastAPI MCP | 530 |
| [`test_utils.py`](test_utils.py) | Type conversion utilities | JSON schema extraction | 438 |
| [`test_mcp_protocol_server_mocked.py`](test_mcp_protocol_server_mocked.py) | MCP integration | Protocol server mocking | 215 |
| [`conftest.py`](conftest.py) | Test configuration | Pytest fixtures, setup | 60 |

## Test Fixtures

**Semantic Tag**: `test-fixtures`

### Core Fixtures (conftest.py)
- **Environment setup**: Mock `VERIS_ENDPOINT_URL` and `ENV` variables
- **Async client**: HTTP client for testing API interactions
- **Session management**: Isolation between test runs

### Application Fixtures
Located in [`fixtures/`](fixtures/):

| Fixture | Purpose | Implementation |
|---------|---------|----------------|
| [`simple_app.py`](fixtures/simple_app.py) | Basic FastAPI app | Minimal endpoints for MCP testing |
| [`sse_server.py`](fixtures/sse_server.py) | Server-Sent Events mock | Streaming response testing |

**Usage Pattern**: Import fixtures to simulate real FastAPI applications during testing.

## Running Tests

**Semantic Tag**: `test-execution`

### Basic Test Runs
```bash
# Full test suite with coverage
pytest --cov=veris_ai --cov-report=term-missing

# Specific test file
pytest tests/test_tool_mock.py -v

# Async tests only
pytest -k "async" -v
```

### Coverage Analysis
```bash
# Generate HTML coverage report
pytest --cov=veris_ai --cov-report=html

# Focus on specific modules
pytest --cov=veris_ai.tool_mock --cov-report=term-missing
```

## Test Categories

**Semantic Tag**: `test-categories`

### Unit Tests
- **Function mocking**: Decorator behavior, environment handling
- **Type conversion**: JSON schema extraction from Python types
- **Configuration**: Environment variable processing

### Integration Tests  
- **FastAPI MCP**: End-to-end MCP server functionality
- **HTTP clients**: Mock endpoint communication
- **Session management**: Bearer token handling

### Mock Tests
- **API responses**: Simulated server responses  
- **Error conditions**: Timeout, connection failures
- **Edge cases**: Invalid schemas, malformed responses

## Development Workflow

**Semantic Tag**: `testing-workflow`

1. **Write failing test**: Define expected behavior
2. **Implement feature**: Add functionality to pass test
3. **Verify coverage**: Ensure new code is tested
4. **Run full suite**: Confirm no regressions

**Quality Gates**: All tests must pass before merge, minimum 90% coverage target.

## Dependencies

**Test-specific dependencies** (included in `[dev]` extra):
- `pytest`: Test framework
- `pytest-asyncio`: Async test support  
- `pytest-cov`: Coverage reporting
- `httpx`: HTTP client for testing

**Configuration**: Test settings in [`../pyproject.toml`](../pyproject.toml) under `[tool.pytest.ini_options]`.

---

**Parent Documentation**: See [main README](../README.md) for development setup and quality tools.