learningcircuit--local-deep-research/tests/api_tests/test_api_contracts.py

#!/usr/bin/env python3
"""
Test API response contracts.

These tests verify that API responses have the expected structure.
Breaking these contracts will break client integrations.
"""

import pytest


class TestResearchStatusValues:
    """
    Verify that research status values are consistent.

    Clients depend on these exact string values.
    """

    def test_research_status_enum_values(self):
        """
        Verify ResearchStatus enum has expected values.

        Clients check for these exact string values in responses.
        Changing them will break client code.
        """
        from local_deep_research.database.models.research import (
            ResearchStatus,
        )

        # These are the status values clients depend on
        expected_values = {
            "pending",
            "in_progress",
            "completed",
            "failed",
            "cancelled",
            "suspended",
        }

        actual_values = {status.value for status in ResearchStatus}

        # Check no expected values were removed
        missing = expected_values - actual_values
        assert not missing, (
            f"ResearchStatus is missing expected values: {missing}\n"
            "Clients depend on these status values.\n"
            "Removing them will break client integrations."
        )

    def test_research_mode_enum_values(self):
        """
        Verify ResearchMode enum has expected values.

        Clients use these values when starting research.
        """
        from local_deep_research.database.models.research import (
            ResearchMode,
        )

        # These are the mode values clients depend on
        expected_values = {
            "quick",
            "detailed",
        }

        actual_values = {mode.value for mode in ResearchMode}

        missing = expected_values - actual_values
        assert not missing, (
            f"ResearchMode is missing expected values: {missing}\n"
            "Clients depend on these mode values."
        )


class TestResponseStructures:
    """
    Verify that models have expected columns for API responses.

    These are the fields that clients depend on.
    """

    def test_research_has_required_columns(self):
        """
        Verify Research model has required columns for API responses.

        These columns are serialized in API responses.
        """
        from local_deep_research.database.models.research import Research

        required_columns = {
            "id",
            "query",
            "status",
            "mode",
            "created_at",
        }

        actual_columns = set(Research.__table__.columns.keys())

        missing = required_columns - actual_columns
        assert not missing, (
            f"Research model is missing required columns: {missing}\n"
            "These columns are expected in API responses."
        )

    def test_user_settings_has_required_columns(self):
        """
        Verify UserSettings model has required columns for API responses.
        """
        from local_deep_research.database.models import UserSettings

        required_columns = {"id", "key", "value", "category"}

        actual_columns = set(UserSettings.__table__.columns.keys())

        missing = required_columns - actual_columns
        assert not missing, (
            f"UserSettings model is missing required columns: {missing}\n"
            "These columns are expected in settings API responses."
        )


if __name__ == "__main__":
    pytest.main([__file__, "-v"])