tests/
├── unit/           # Fast, isolated component tests
├── integration/    # Multi-component interaction tests
├── e2e/           # Full system end-to-end tests
├── fixtures/      # Reusable test data generators
└── conftest.py    # Shared pytest fixtures

tests/
├── unit/                              # Unit tests
│   ├── __init__.py
│   ├── test_models.py                 # Model validation tests
│   ├── test_services.py               # Service logic tests
│   └── test_utils.py                  # Utility function tests
│
├── integration/                       # Integration tests
│   ├── __init__.py
│   ├── test_workflow_scenarios.py     # Complete workflows
│   └── test_component_integration.py  # Multi-component tests
│
├── e2e/                               # End-to-end tests
│   ├── __init__.py
│   ├── test_api_flows.py              # Complete API scenarios
│   └── test_user_journeys.py          # User-facing workflows
│
├── fixtures/                          # Reusable test data
│   ├── __init__.py
│   ├── models.py                      # Model fixtures
│   ├── api_responses.py               # API response fixtures
│   └── database_records.py            # Database fixture data
│
├── conftest.py                        # Shared pytest fixtures
└── README.md                          # Test documentation

mkdir -p tests/{unit,integration,e2e,fixtures}
touch tests/{unit,integration,e2e,fixtures}/__init__.py
touch tests/conftest.py

"""Shared pytest fixtures available to all tests."""

import pytest
from myapp.models import User, Document

@pytest.fixture
def simple_user():
    """Quick User fixture for unit tests."""
    return User(
        id="user-123",
        email="test@example.com",
        role="user"
    )

@pytest.fixture
def admin_user():
    """Admin User fixture for permission tests."""
    return User(
        id="admin-456",
        email="admin@example.com",
        role="admin"
    )

@pytest.fixture
def test_database(tmp_path):
    """Temporary database for integration tests."""
    db_path = tmp_path / "test.db"
    # Setup database
    yield db_path
    # Cleanup happens automatically with tmp_path

# fixtures/users.py
"""Reusable user test data generators."""

def basic_user_data():
    """Simple user for basic tests."""
    return {
        "id": "user-001",
        "email": "user@example.com",
        "name": "Test User",
        "role": "user"
    }

def admin_user_data():
    """Admin user with full permissions."""
    return {
        "id": "admin-001",
        "email": "admin@example.com",
        "name": "Admin User",
        "role": "admin",
        "permissions": ["read", "write", "delete"]
    }

def user_with_profile():
    """User with complete profile data."""
    return {
        **basic_user_data(),
        "profile": {
            "bio": "Test bio",
            "avatar_url": "https://example.com/avatar.jpg",
            "preferences": {"theme": "dark"}
        }
    }

# unit/test_user_model.py
"""Unit tests for User model."""

import pytest
from myapp.models import User

class TestUserModel:
    """Tests for User model validation."""

    def test_create_user(self, simple_user):
        """Test creating a basic user."""
        assert simple_user.id == "user-123"
        assert simple_user.email == "test@example.com"

    def test_user_validation(self):
        """Test user validation rules."""
        with pytest.raises(ValueError, match="Invalid email"):
            User(id="u1", email="invalid")

class TestUserMethods:
    """Tests for User model methods."""

    def test_has_permission(self, admin_user):
        """Test permission checking."""
        assert admin_user.has_permission("write") is True

    def test_to_dict(self, simple_user):
        """Test serialization to dictionary."""
        data = simple_user.to_dict()
        assert data["id"] == "user-123"
        assert "email" in data

# integration/test_user_workflows.py
"""Integration tests for user workflows."""

import pytest
from myapp.models import User
from myapp.services import UserService
from tests.fixtures import users

class TestUserRegistration:
    """Integration tests for user registration workflow."""

    def test_complete_registration_flow(self, test_database):
        """Test complete user registration from start to finish."""
        # Given: User data
        user_data = users.basic_user_data()

        # When: User registers
        service = UserService(database=test_database)
        user = service.register_user(user_data)

        # Then: User is created and can be retrieved
        assert user.id is not None
        retrieved = service.get_user(user.id)
        assert retrieved.email == user_data["email"]

    def test_duplicate_email_handling(self, test_database):
        """Test that duplicate emails are rejected."""
        service = UserService(database=test_database)
        user_data = users.basic_user_data()

        # First registration succeeds
        service.register_user(user_data)

        # Second registration fails
        with pytest.raises(ValueError, match="Email already exists"):
            service.register_user(user_data)

# e2e/test_api_user_flows.py
"""End-to-end tests for user API flows."""

import pytest
import requests
from tests.fixtures import users

@pytest.fixture
def api_client(test_server):
    """API client connected to test server."""
    return requests.Session()

class TestUserAPIFlow:
    """E2E tests for user API endpoints."""

    def test_full_user_lifecycle(self, api_client, test_server):
        """Test complete user lifecycle via API."""
        base_url = test_server.url

        # 1. Register user
        user_data = users.basic_user_data()
        response = api_client.post(f"{base_url}/users", json=user_data)
        assert response.status_code == 201
        user_id = response.json()["id"]

        # 2. Login
        response = api_client.post(f"{base_url}/auth/login", json={
            "email": user_data["email"],
            "password": "password123"
        })
        assert response.status_code == 200
        token = response.json()["token"]

        # 3. Get user profile
        headers = {"Authorization": f"Bearer {token}"}
        response = api_client.get(f"{base_url}/users/{user_id}", headers=headers)
        assert response.status_code == 200
        assert response.json()["email"] == user_data["email"]

        # 4. Update profile
        response = api_client.patch(
            f"{base_url}/users/{user_id}",
            headers=headers,
            json={"name": "Updated Name"}
        )
        assert response.status_code == 200

        # 5. Delete user
        response = api_client.delete(f"{base_url}/users/{user_id}", headers=headers)
        assert response.status_code == 204

        # 6. Verify deletion
        response = api_client.get(f"{base_url}/users/{user_id}", headers=headers)
        assert response.status_code == 404

# Tests

## Structure

- `unit/` - Fast isolated tests (25 tests, <1s)
- `integration/` - Multi-component tests (12 tests, ~5s)
- `e2e/` - Full system tests (8 tests, ~30s)
- `fixtures/` - Reusable test data

## Running Tests

```bash
# All tests
pytest

# Only unit tests (fast)
pytest tests/unit

# Only integration tests
pytest tests/integration

# Only E2E tests (slow)
pytest tests/e2e

# Specific test file
pytest tests/unit/test_user_model.py

# Specific test
pytest tests/unit/test_user_model.py::TestUserModel::test_create_user

## Applies Principles

- **Separation of Concerns**: Different test types in different directories
- **DRY (Don't Repeat Yourself)**: Shared fixtures eliminate duplication
- **Single Responsibility**: Each test tests one specific behavior
- **Clear Structure**: Tests mirror application structure
- **Fast Feedback**: Can run fast unit tests independently

## Consequences

### Benefits

✅ **Clear organization**: Easy to find tests for specific components
✅ **Fast test runs**: Can run only unit tests for quick feedback
✅ **Reduced duplication**: Shared fixtures used across tests
✅ **Better scalability**: Structure supports growing test suite
✅ **Improved maintainability**: Clear conventions for adding tests
✅ **Parallel execution**: Different test types can run in parallel in CI

### Trade-offs

⚠️ **More structure**: Requires more files and directories
⚠️ **Learning curve**: Team needs to understand test type distinctions
⚠️ **Initial setup**: Takes time to set up structure and fixtures
⚠️ **Fixture management**: Need to keep fixtures organized and documented

### When It's Worth It

Worth the investment when:
- Test suite has >15 test files
- Team has >2 developers
- Project will be maintained >6 months
- Multiple test types exist

Not worth it when:
- Small project with <10 tests
- Solo developer project
- Prototype or POC

## Examples

### Real Implementation: ontopix/schemas

**Outcome**: 32 tests organized clearly, easy to navigate, fast to run.

## Variations

### Variation 1: By Component (Alternative)

**When to use**: When components are very independent and large

### Variation 2: With Performance Tests

**When to use**: When performance testing is critical

### Variation 3: Contract Tests

**When to use**: Microservices with API contracts

## Related Patterns

- [Repository Structure](../organizational/repository-structure.md) - Overall project layout
- [Taskfile Contract](../organizational/taskfile-contract.md) - Standardized `task test` command
- [Python Module Naming](./python-module-naming.md) - Module organization patterns

## References

### Internal
- ADR: Test Organization Strategy (schemas repository)
- Implementation: `ontopix/schemas/libs/python/tests/`

### External
- [Pytest Documentation](https://docs.pytest.org/)
- [Test Pyramid Pattern](https://martinfowler.com/articles/practical-test-pyramid.html)
- [Arrange-Act-Assert Pattern](https://automationpanda.com/2020/07/07/arrange-act-assert-a-pattern-for-writing-good-tests/)

---

**Status**: ✅ Active
**Created**: 2026-01-27
**Last Updated**: 2026-01-27
**Applies to**: All Python projects with pytest