Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

35.3 KB
Raw Blame
import inspect
import json
import os

# Fix pathlib.Path compatibility issue for pytest
# In Python 3.11, pathlib.Path doesn't have _flavour but PosixPath does
# This is needed for pytest internal usage
import pathlib
import sys
from pathlib import Path
from tempfile import TemporaryDirectory
from typing import Iterator

import pytest
from dotenv import load_dotenv
from openai.types.chat import ChatCompletion
from openai.types.chat.chat_completion import Choice
from openai.types.chat.chat_completion_message import ChatCompletionMessage
from openai.types.chat.chat_completion_message_tool_call import (
    ChatCompletionMessageToolCall,
)
from openai.types.chat.chat_completion_message_tool_call import (
    Function as ToolCallFunction,
)

from xagent.core.execution_scope import (
    set_execution_scope_resolver,
    set_execution_scope_snapshot_loader,
)
from xagent.core.model import ChatModelConfig, EmbeddingModelConfig, RerankModelConfig
from xagent.core.tools.core.RAG_tools.storage import reset_rag_storage_for_tests
from xagent.core.tracing.langfuse import reset_langfuse_client

# YAML entrypoint has been removed, commenting out these imports
# from xagent.entrypoint.yaml.parser import MigrationManager
# from xagent.entrypoint.yaml.server import set_yaml_migration_manager

# The guard against rewriting a command's tenant key lives in a plugin so that a
# test can run it in an inner pytest session; pytester runs that session.
pytest_plugins = [
    "pytester",
    "tests.shared.fairness_key_guard_plugin",
    # `--shard=K/N`, which splits a CI leg across jobs.
    "tests.shared.ci_shard_plugin",
]

# ==========================================
# ENVIRONMENT AND PROJECT SETUP
# ==========================================


# On Windows this would shadow WindowsPath._flavour (Path precedes
# PureWindowsPath in WindowsPath's MRO) and break every Path() call with
# NotImplementedError, so it only applies on POSIX.
if (
    os.name != "nt"
    and not hasattr(pathlib.Path, "_flavour")
    and hasattr(pathlib.PosixPath, "_flavour")
):
    pathlib.Path._flavour = pathlib.PosixPath._flavour

# Load environment variables - try .env first, fallback to example.env
project_root = Path(__file__).parent.parent
env_file = project_root / ".env"
example_env_file = project_root / "example.env"

if env_file.exists():
    load_dotenv(env_file, override=True)  # Force override existing env vars
elif example_env_file.exists():
    # Don't override existing env vars (especially API keys from user's shell)
    load_dotenv(example_env_file, override=False)
else:
    print("Warning: Neither .env nor example.env file found")


@pytest.fixture(autouse=True)
def local_execution_unless_selected(monkeypatch):
    """Existing suites select local execution; shared suites opt in explicitly."""
    # A reachable CI Redis must not silently enable shared caches or rate limits.
    # Tests that exercise Redis opt in explicitly after this fixture.
    monkeypatch.delenv("XAGENT_REDIS_URL", raising=False)
    monkeypatch.setenv("XAGENT_SHARED_TASK_EXECUTION_ENABLED", "false")
    monkeypatch.setenv("XAGENT_TASK_EXECUTION_ROLE", "combined")
    monkeypatch.delenv("XAGENT_CHANNEL_INGRESS_ENABLED", raising=False)


_DATABASE_MODULE = "xagent.web.models.database"


@pytest.fixture(autouse=True)
def isolated_local_authentication_budgets():
    """Each test is an independent deployment, not one shared client IP."""

    def clear():
        module = sys.modules.get("xagent.web.api.auth")
        if module is not None:
            with module._login_failure_lock:
                module._login_failures.clear()
            with module._password_recovery_lock:
                module._password_recovery_attempts.clear()

    clear()
    yield
    clear()


_DATABASE_ACCESSORS = (
    "get_session_local",
    "get_optional_session_local",
    "get_engine",
    "get_db",
)
# A leaked binding stays leaked for the rest of the process; report it once,
# against the test that leaked it, instead of failing every later test too.
_reported_stale_database_accessors: set[str] = set()


def _is_real_database_accessor(value: object, name: str) -> bool:
    return (
        inspect.isfunction(value)
        and value.__module__ == _DATABASE_MODULE
        and value.__qualname__ == name
    )


def _stale_database_accessors() -> list[str]:
    """Loaded ``xagent`` modules holding a patched database accessor.

    A module first imported while a test patches
    ``xagent.web.models.database.get_session_local`` (or another accessor) binds
    the replacement by name through ``from ..models.database import ...`` and
    keeps it after monkeypatch restores the database module, so every later
    test in the process silently uses the wrong database. Tests should patch
    ``database._SessionLocal`` / ``database._engine`` instead.
    """
    return sorted(
        f"{module_name}.{name}"
        for module_name, module in list(sys.modules.items())
        if module_name.startswith("xagent.") and module is not None
        for name in _DATABASE_ACCESSORS
        if name in vars(module)
        and not _is_real_database_accessor(vars(module)[name], name)
    )


@pytest.hookimpl(wrapper=True)
def pytest_runtest_teardown(item, nextitem):
    # Runs after every fixture (monkeypatch included) has been finalized, so
    # anything still patched here outlives the test that patched it.
    result = yield
    stale = [
        binding
        for binding in _stale_database_accessors()
        if binding not in _reported_stale_database_accessors
    ]
    if stale:
        _reported_stale_database_accessors.update(stale)
        raise AssertionError(
            f"{item.nodeid} leaked patched database accessors into: "
            f"{', '.join(stale)}. Patch xagent.web.models.database._SessionLocal "
            "/ _engine instead of the accessors that read them."
        )
    return result


def pytest_addoption(parser):
    parser.addoption(
        "--run-special",
        action="store_true",
        default=False,
        help="Run tests that require special conditions",
    )


def pytest_configure(config):
    """Register custom markers."""
    config.addinivalue_line(
        "markers", "docker: tests that require Docker daemon (run with --run-special)"
    )
    config.addinivalue_line(
        "markers",
        "real_rag: tests that require DashScope embedding API config",
    )
    config.addinivalue_line(
        "markers",
        "requires_network: tests that require network access (run with --run-special or set XAGENT_TESTS_ALLOW_NETWORK=1)",
    )


def pytest_collection_modifyitems(config, items):
    """Skip Docker tests unless --run-special is specified.

    Also automatically skip tests that require unavailable external dependencies.
    Tests marked with `pytest.mark.real_rag` require DashScope embedding
    configuration. If this is not configured in the environment, the tests are
    automatically skipped rather than failing.

    Tests marked with `pytest.mark.requires_network` require network access.
    These tests are skipped unless --run-special is specified or
    XAGENT_TESTS_ALLOW_NETWORK=1 is set.
    """
    # Skip Docker tests unless --run-special is specified
    if not config.getoption("--run-special", default=False):
        skip_docker = pytest.mark.skip(
            reason="Requires --run-special flag (Docker needed)"
        )
        for item in items:
            if "docker" in item.keywords:
                item.add_marker(skip_docker)

    # Skip real_rag tests when DashScope embedding config is unavailable.
    # Check for actual values, not placeholder values from example.env.
    dashscope_key = os.getenv("DASHSCOPE_EMBEDDING_API_KEY") or os.getenv(
        "DASHSCOPE_API_KEY", ""
    )
    dashscope_model = os.getenv("DASHSCOPE_EMBEDDING_MODEL", "")

    # Common placeholder patterns that indicate the key is not set
    placeholder_patterns = [
        "your-dashscope-api-key",
        "your-dashscope-embedding-model",
        "your-api-key",
        "test-key",
    ]

    def is_valid_value(value: str) -> bool:
        """Check if the config value is not a placeholder value."""
        if not value:
            return False
        key_lower = value.lower().strip()
        for pattern in placeholder_patterns:
            if pattern in key_lower:
                return False
        return True

    has_dashscope_embedding_config = is_valid_value(dashscope_key) and is_valid_value(
        dashscope_model
    )
    if not has_dashscope_embedding_config:
        skip_real_rag = pytest.mark.skip(
            reason="Requires (DASHSCOPE_API_KEY or DASHSCOPE_EMBEDDING_API_KEY) + DASHSCOPE_EMBEDDING_MODEL environment variables"
        )
        for item in items:
            if "real_rag" in item.keywords:
                item.add_marker(skip_real_rag)

    if not os.getenv("MILVUS_URI"):
        if os.getenv("XAGENT_REQUIRE_MILVUS", "0").strip() == "1":
            raise pytest.UsageError(
                "XAGENT_REQUIRE_MILVUS is set but MILVUS_URI is empty; "
                "the Milvus tests would all be skipped"
            )
        skip_milvus = pytest.mark.skip(reason="Requires a Milvus server at MILVUS_URI")
        for item in items:
            if item.get_closest_marker("milvus"):
                item.add_marker(skip_milvus)

    # Skip requires_network tests unless --run-special or XAGENT_TESTS_ALLOW_NETWORK=1
    run_special = config.getoption("--run-special", default=False)
    allow_network = os.getenv("XAGENT_TESTS_ALLOW_NETWORK", "0").strip() == "1"
    has_network_access = run_special or allow_network

    if not has_network_access:
        skip_network = pytest.mark.skip(
            reason="Requires --run-special flag or XAGENT_TESTS_ALLOW_NETWORK=1 (network access needed)"
        )
        for item in items:
            if "requires_network" in item.keywords:
                item.add_marker(skip_network)


# ==========================================
# CORE FIXTURES
# ==========================================


def _security_test_subdir(tmp_path: Path, name: str) -> str:
    """Create ``tmp_path / name`` and return its path as a string."""
    subdir = tmp_path / name
    subdir.mkdir()
    return str(subdir)


@pytest.fixture
def temp_dir():
    """Provide a temporary directory for tests."""
    with TemporaryDirectory() as temp_dir:
        yield temp_dir


@pytest.fixture(autouse=True, scope="function")
def isolate_path_config_caches() -> Iterator[None]:
    """Reset cwd-pinned config paths so test order cannot change results."""
    from xagent.config import _reset_path_config_caches_for_tests

    _reset_path_config_caches_for_tests()
    yield
    _reset_path_config_caches_for_tests()


@pytest.fixture(autouse=True, scope="function")
def isolate_process_database_binding() -> Iterator[None]:
    """Keep temporary Web SQL configuration from leaking into later tests."""
    from sqlalchemy.engine import Engine

    from xagent.web.models import database

    previous = database._SessionLocal, database._engine
    try:
        yield
    finally:
        engine = database._engine
        database._SessionLocal, database._engine = previous
        if isinstance(engine, Engine) and engine is not previous[1]:
            engine.dispose()


@pytest.fixture
def monkeypatch(
    isolate_process_database_binding: None, monkeypatch: pytest.MonkeyPatch
) -> pytest.MonkeyPatch:
    """Undo test patches before restoring the original process SQL binding."""
    return monkeypatch


@pytest.fixture(autouse=True, scope="function")
def isolate_rag_storage(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    """Isolate per-test RAG/KB storage paths and reset global storage state.

    By default, ``LANCEDB_DIR`` is set to a fresh directory under ``tmp_path``
    (current default vector backend is LanceDB). This avoids stale on-disk
    state from a developer ``.env`` or a fixed path. Parallel workers
    (pytest-xdist) each use their own process-local ``tmp_path``.

    If the environment sets ``XAGENT_PYTEST_RESPECT_LANCEDB_DIR=1``, the
    existing ``LANCEDB_DIR`` from the environment is left unchanged (for CI or
    local workflows that intentionally pin a path).

    Calls :func:`xagent.core.tools.core.RAG_tools.storage.reset_rag_storage_for_tests`
    before and after each test (backend-specific caches + storage factory reset).
    """
    respect_env = os.environ.get("XAGENT_PYTEST_RESPECT_LANCEDB_DIR") == "1"
    if not respect_env:
        lancedb_dir = tmp_path / "lancedb"
        lancedb_dir.mkdir(parents=True, exist_ok=True)
        monkeypatch.setenv("LANCEDB_DIR", str(lancedb_dir))

    reset_rag_storage_for_tests()
    yield
    reset_rag_storage_for_tests()


@pytest.fixture
def test_workspace_dir(tmp_path: Path) -> str:
    """Directory used as workspace root in ``test_service_security``."""
    return _security_test_subdir(tmp_path, "test_workspace")


@pytest.fixture
def test_access_dir(tmp_path: Path) -> str:
    """Directory used for access-restriction scenarios in security tests."""
    return _security_test_subdir(tmp_path, "test_access_restriction")


@pytest.fixture
def test_security_dir(tmp_path: Path) -> str:
    """Directory used for outside-access rejection scenarios in security tests."""
    return _security_test_subdir(tmp_path, "test_security")


@pytest.fixture(autouse=True, scope="function")
def mock_workspace_db():
    """Mock database operations for workspace to avoid DB access in tests.

    This fixture is automatically applied to all tests to prevent database
    access during testing. Tests can override this by explicitly creating
    real database connections if needed.
    """

    from unittest.mock import patch

    from xagent.core.workspace import TaskWorkspace

    # Mock _create_file_record to do nothing (avoid DB access)
    def mock_create_record(self, file_id, file_path, db_session=None):
        # Store file_id in cache for retrieval
        path_str = str(file_path)
        resolved_str = str(file_path.resolve())
        self._recently_registered_files[path_str] = file_id
        self._recently_registered_files[resolved_str] = file_id
        self._file_id_to_path[file_id] = file_path

    with patch.object(TaskWorkspace, "_create_file_record", mock_create_record):
        yield


@pytest.fixture(autouse=True, scope="function")
def isolate_execution_scope_hooks() -> Iterator[None]:
    """Reset the execution-scope resolver and snapshot loader around every test.

    Both are process-global module state (``xagent.core.execution_scope``).
    A test (or a direct ``startup_event()`` call in
    ``tests/integration/test_auto_migration_startup.py``, which registers the
    real Task-table-backed snapshot loader with no patch/reset of its own)
    that registers either without resetting it leaks into every test that
    runs afterward in the same process/worker. Root-level and autouse so no
    test module can forget it; scoped narrowly to just these two globals so
    it composes with any test's own *function-scoped* registration (a
    session- or module-scoped registration would still be torn down mid-
    session by this fixture's teardown, since that always re-registers
    ``None`` regardless of what a wider-scoped fixture set up). That
    teardown call also never carries the acknowledgement keyword, so this
    safety net alone never exercises the acknowledged-registration path.
    """
    set_execution_scope_resolver(None)
    set_execution_scope_snapshot_loader(None)
    yield
    set_execution_scope_resolver(None)
    set_execution_scope_snapshot_loader(None)


def _reset_task_keyed_process_state() -> None:
    # Only modules a test already imported can hold state; importing the web
    # stack here would slow every core-only test.
    manager_module = sys.modules.get("xagent.core.agent.context.manager")
    if (
        manager_module is not None
        and manager_module.ContextManager._instance is not None
    ):
        manager = manager_module.ContextManager()
        for context in manager.list_active_contexts():
            manager.remove_context(context.execution_id)
        with manager._lock:
            manager._cold_starts.clear()
    task_execution = sys.modules.get("xagent.web.services.task_execution")
    if task_execution is not None:
        task_execution._pause_accepted_task_ids.clear()
    connector_runtime = sys.modules.get("xagent.web.services.connector_runtime")
    if connector_runtime is not None:
        # Keyed by turn id, which is the client message id when one is sent.
        with connector_runtime._EPHEMERAL_RUNTIME_VALUES_LOCK:
            connector_runtime._EPHEMERAL_RUNTIME_VALUES.clear()
            connector_runtime._EPHEMERAL_RUNTIME_MANIFESTS.clear()


@pytest.fixture(autouse=True, scope="function")
def isolate_task_keyed_process_state() -> Iterator[None]:
    """Clear process-wide state keyed by task, execution or turn id around every test.

    Each test's database numbers tasks from 1 again, so an entry a test leaves
    behind is picked up by the next test on the same worker as if it were its
    own task: a fenced or finished ``ContextManager`` context becomes the
    "cached" context of an unrelated injection, and a leaked pause-accepted id
    routes an unrelated message into the pause-drain branch. Which test pairs
    collide depends on how xdist distributes files, so these leaks surface as
    order-dependent failures far from the test that caused them.
    """
    _reset_task_keyed_process_state()
    yield
    _reset_task_keyed_process_state()


@pytest.fixture(autouse=True, scope="function")
def check_task_extension_registry_leaks() -> Iterator[None]:
    """Fail the test that leaves the task-extension registry changed.

    The registry in ``xagent.web.services.task_runtime`` is process-wide. A
    provider left registered (e.g. by running the web app's startup without
    its shutdown) makes every later test that consults
    ``registered_task_extensions()`` take the provider branch, which then
    fails far from the cause depending on xdist scheduling. The registry is
    restored before failing so the leak cannot cascade.
    """
    task_runtime = sys.modules.get("xagent.web.services.task_runtime")
    before = (
        dict(task_runtime._task_runtime_extensions) if task_runtime is not None else {}
    )
    yield
    task_runtime = sys.modules.get("xagent.web.services.task_runtime")
    if task_runtime is None:
        return
    with task_runtime._task_runtime_extensions_lock:
        after = dict(task_runtime._task_runtime_extensions)
        if after == before:
            return
        task_runtime._task_runtime_extensions.clear()
        task_runtime._task_runtime_extensions.update(before)
    leaked = sorted(set(after) - set(before))
    removed = sorted(set(before) - set(after))
    replaced = sorted(
        name for name in set(after) & set(before) if after[name] is not before[name]
    )
    pytest.fail(
        "Test changed the process-wide task extension registry without "
        f"restoring it (leaked={leaked}, removed={removed}, replaced={replaced}); "
        "unregister providers the test registers, or run the app shutdown.",
        pytrace=False,
    )


@pytest.fixture(autouse=True, scope="function")
def isolate_proxy_env(monkeypatch: pytest.MonkeyPatch) -> None:
    """Clear ambient proxy env vars so tests are deterministic across hosts.

    A developer machine or CI runner may have ``HTTP_PROXY``/``HTTPS_PROXY``
    (either casing) set in its real environment for its own outbound traffic.
    Since ``get_trusted_proxy_url()`` now raises unless
    ``XAGENT_TRUSTED_EGRESS_PROXY`` is also set, an inherited proxy var would
    make otherwise-unrelated tests (webpage fetch, SVG/image download, vision
    tool) fail at that trust gate before ever reaching their mocked request.
    Tests that specifically exercise proxy behavior should opt back in with
    ``monkeypatch.setenv(...)`` for the exact vars they need.
    """
    for name in (
        "HTTP_PROXY",
        "http_proxy",
        "HTTPS_PROXY",
        "https_proxy",
        "XAGENT_TRUSTED_EGRESS_PROXY",
        "XAGENT_MODEL_PRIVATE_ENDPOINTS",
        "XAGENT_MODEL_PRIVATE_CIDRS",
        "XAGENT_MCP_PRIVATE_ENDPOINTS",
        "XAGENT_MCP_PRIVATE_CIDRS",
    ):
        monkeypatch.delenv(name, raising=False)


@pytest.fixture(autouse=True, scope="function")
def isolate_meta_config_id_env(monkeypatch: pytest.MonkeyPatch) -> None:
    """Clear ambient Meta Login Configuration env vars for the same reason as
    isolate_proxy_env above: a developer's real .env can carry META_CONFIG_ID
    or one of the per-app overrides (META_FACEBOOK_CONFIG_ID /
    META_INSTAGRAM_CONFIG_ID / META_ADS_CONFIG_ID / META_WHATSAPP_CONFIG_ID --
    exactly what example.env now documents setting), and without this an
    otherwise unrelated test exercising the Meta OAuth authorize flow would
    silently pick up that ambient value instead of the one it explicitly
    sets/expects. Tests exercising config_id behavior already opt in with
    ``monkeypatch.setenv(...)`` for the exact var(s) they need.
    """
    for name in (
        "META_CONFIG_ID",
        "META_FACEBOOK_CONFIG_ID",
        "META_INSTAGRAM_CONFIG_ID",
        "META_ADS_CONFIG_ID",
        "META_WHATSAPP_CONFIG_ID",
    ):
        monkeypatch.delenv(name, raising=False)


@pytest.fixture
def temp_tool_dir():
    """Create a temporary directory with a single sample tool file.

    Generic fixture for tool directory testing across all test modules.
    """
    with TemporaryDirectory() as tmpdir:
        tool_file = Path(tmpdir) / "test_tool.py"
        tool_file.write_text("""
def get_test_tool():
    '''A test tool.'''
    return {'name': 'test_tool', 'description': 'A test tool'}
""")
        yield tmpdir


@pytest.fixture
def sample_tool_dir():
    """Create a temporary directory with sample tools for integration testing.

    Generic fixture for tool directory testing with multiple tool files.
    """
    with TemporaryDirectory() as tmpdir:
        # Create tool1.py
        tool1 = Path(tmpdir) / "tool1.py"
        tool1.write_text("""
'''Tool 1 module.'''

def get_tool1():
    '''First tool function.'''
    return {
        'name': 'tool1',
        'description': 'First test tool',
        'function': 'do_something',
        'parameters': {}
    }
""")

        # Create tool2.py
        tool2 = Path(tmpdir) / "tool2.py"
        tool2.write_text("""
'''Tool 2 module.'''

def get_tool2():
    '''Second tool function.'''
    return {
        'name': 'tool2',
        'description': 'Second test tool',
        'function': 'do_another_thing',
        'parameters': {}
    }
""")

        # Create __init__.py
        init_file = Path(tmpdir) / "__init__.py"
        init_file.write_text("")

        # Create a subdirectory with another tool
        subdir = Path(tmpdir) / "subdir"
        subdir.mkdir()
        (subdir / "__init__.py").write_text("")
        (subdir / "tool3.py").write_text("""
'''Tool 3 module.'''

def get_tool3():
    '''Third tool function.'''
    return {
        'name': 'tool3',
        'description': 'Third test tool',
        'function': 'do_third_thing',
    }
""")

        yield tmpdir


@pytest.fixture
def tool_dir_with_errors():
    """Create a directory with invalid tool files for error testing.

    Generic fixture for testing error handling in tool directories.
    """
    with TemporaryDirectory() as tmpdir:
        # Invalid tool file - syntax error
        invalid_tool = Path(tmpdir) / "invalid_tool.py"
        invalid_tool.write_text("""
def get_invalid_tool(
    # Missing closing parenthesis - syntax error
        return {'name': 'invalid'}
""")

        # Valid tool
        valid_tool = Path(tmpdir) / "valid_tool.py"
        valid_tool.write_text("""
def get_valid_tool():
    return {'name': 'valid_tool'}
""")

        yield tmpdir


@pytest.fixture
def initialized_tool_registry(temp_dir):
    """Fixture that provides a properly initialized tool registry."""
    # Initialize storage manager first
    import xagent.core.storage.manager as storage_manager
    from xagent.core.storage import initialize_storage_manager

    upload_dir = os.path.join(temp_dir, "uploads")
    os.makedirs(upload_dir, exist_ok=True)
    initialize_storage_manager(temp_dir, upload_dir)

    try:
        yield temp_dir
    finally:
        # Cleanup - reset global storage manager and remove temp directory
        storage_manager._storage_manager = None
        import shutil

        if os.path.exists(temp_dir):
            shutil.rmtree(temp_dir, ignore_errors=True)


# ==========================================
# MOCK RESPONSES AND COMPLETIONS
# ==========================================


@pytest.fixture
def mock_chat_completion():
    """Mock ChatCompletion response."""
    return ChatCompletion(
        id="test-completion-id",
        choices=[
            Choice(
                finish_reason="stop",
                index=0,
                message=ChatCompletionMessage(
                    content="Hello World",
                    role="assistant",
                    tool_calls=None,
                ),
            )
        ],
        created=1234567890,
        model="gpt-4o-mini",
        object="chat.completion",
        usage=None,
    )


@pytest.fixture
def mock_tool_call_completion():
    """Mock ChatCompletion response with tool call."""
    return ChatCompletion(
        id="test-tool-completion-id",
        choices=[
            Choice(
                finish_reason="tool_calls",
                index=0,
                message=ChatCompletionMessage(
                    content=None,
                    role="assistant",
                    tool_calls=[
                        ChatCompletionMessageToolCall(
                            id="call_test",
                            type="function",
                            function=ToolCallFunction(
                                name="get_weather",
                                arguments='{"location": "Boston"}',
                            ),
                        )
                    ],
                ),
            )
        ],
        created=1234567890,
        model="gpt-4o-mini",
        object="chat.completion",
        usage=None,
    )


@pytest.fixture
def mock_json_completion():
    """Mock ChatCompletion response with JSON content."""
    return ChatCompletion(
        id="test-json-completion",
        choices=[
            Choice(
                finish_reason="stop",
                index=0,
                message=ChatCompletionMessage(
                    content='{"name": "John", "age": 30}',
                    role="assistant",
                    tool_calls=None,
                ),
            )
        ],
        created=1234567890,
        model="gpt-4o-mini",
        object="chat.completion",
        usage=None,
    )


@pytest.fixture
def openai_llm_config():
    """Fixture providing OpenAI LLM configuration for testing."""
    return {
        "model_name": "gpt-4o-mini",
        "base_url": "https://api.openai.com/v1",
        "api_key": "test-api-key",
        "default_temperature": 0.7,
        "default_max_tokens": 1024,
        "timeout": 30.0,
    }


@pytest.fixture
def azure_openai_llm_config():
    """Fixture providing Azure OpenAI LLM configuration for testing."""
    return {
        "model_name": "gpt-4o",
        "azure_endpoint": "https://test.openai.azure.com/",
        "api_key": "test-api-key",
        "api_version": "2024-08-01-preview",
        "default_temperature": 0.7,
        "default_max_tokens": 1024,
        "timeout": 30.0,
    }


@pytest.fixture
def gemini_llm_config():
    """Fixture providing Gemini LLM configuration for testing."""
    return {
        "model_name": "gemini-2.0-flash-exp",
        "api_key": "test-gemini-api-key",
        "default_temperature": 0.7,
        "default_max_tokens": 1024,
        "timeout": 30.0,
    }


@pytest.fixture
def claude_llm_config():
    """Fixture providing Claude LLM configuration for testing."""
    return {
        "model_name": "claude-3-5-sonnet-20241022",
        "api_key": "test-claude-api-key",
        "default_temperature": 0.7,
        "default_max_tokens": 1024,
        "timeout": 30.0,
    }


@pytest.fixture
def sample_openai_model():
    """Provide a sample OpenAI model for testing."""
    return ChatModelConfig(
        id="test_model",
        model_provider="test",
        model="gpt-3.5-turbo",
        temperature=0.7,
        api_key="test_api_key",
        base_url="https://api.openai.com/v1",
    )


@pytest.fixture
def langfuse_client_reset():
    """Fixture to reset the shared Langfuse client before and after each test."""
    reset_langfuse_client()
    yield
    reset_langfuse_client()


@pytest.fixture
def google_api_setting(monkeypatch, mocker):
    """Mock Google API settings for search tests."""
    monkeypatch.setenv("GOOGLE_API_KEY", "test_key")
    monkeypatch.setenv("GOOGLE_CSE_ID", "test_cse_id")
    mock_data = {
        "items": [
            {
                "title": "Test Title",
                "link": "https://example.com",
                "snippet": "Test snippet",
            }
        ],
    }

    mock_response = mocker.Mock()
    mock_response.json.return_value = mock_data
    mock_response.raise_for_status.return_value = None

    mocker.patch("httpx.AsyncClient.get", return_value=mock_response)


# ==========================================
# LEGACY FIXTURES (used by existing tests)
# ==========================================


@pytest.fixture()
def team_dict():
    """Provide team configuration from JSON file for AutoGen tests."""
    json_path = (
        Path(__file__).parent / "core" / "frontend_adapter" / "autogen" / "team.json"
    )
    with open(json_path, "r", encoding="utf-8") as f:
        return json.load(f)


@pytest.fixture
def modelhub():
    """Legacy fixture - creates model hub with pre-populated models."""
    with TemporaryDirectory() as temp_dir:
        model_dir = Path(temp_dir) / "model"
        model_dir.mkdir()

        # Initialize storage manager first
        from sqlalchemy import create_engine
        from sqlalchemy.ext.declarative import declarative_base
        from sqlalchemy.orm import sessionmaker

        from xagent.core.model.storage.db.adapter import SQLAlchemyModelHub
        from xagent.core.model.storage.db.db_models import create_model_table
        from xagent.core.storage import initialize_storage_manager

        upload_dir = os.path.join(temp_dir, "uploads")
        os.makedirs(upload_dir, exist_ok=True)
        initialize_storage_manager(temp_dir, upload_dir)

        # Create in-memory database for model storage
        engine = create_engine("sqlite:///:memory:")
        SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
        Base = declarative_base()
        Model = create_model_table(Base)
        db = SessionLocal()
        Base.metadata.create_all(engine)

        hub = SQLAlchemyModelHub(db, Model)

        # Initialize tool registry
        from xagent.core.tools.adapters.langgraph import initialize_registry

        initialize_registry()

        openai_model = ChatModelConfig(
            id="openai-chat",
            model_provider="openai",
            model_name="openai-chat",
            api_key=os.getenv("OPENAI_API_KEY", "test_key"),
        )
        deepseek_model = ChatModelConfig(
            id="deepseek",
            model_provider="deepseek",
            model_name="deepseek-v4-flash",
            api_key=os.getenv("DEEPSEEK_API_KEY", "test_key"),
            base_url="https://api.deepseek.com",
        )
        # Add embedding model for embedding node tests
        embedding_model = EmbeddingModelConfig(
            id="embedding_model",
            model_provider="openai",
            model_name="text-embedding-ada-002",
            api_key=os.getenv("OPENAI_API_KEY", "test_key"),
        )
        # Add dashscope rerank model for rerank node tests
        dashscope_rerank_model = RerankModelConfig(
            id="dashscope-rerank",
            model_name="bge-reranker-v2-m3",
            api_key=os.getenv("DASHSCOPE_API_KEY", "test-dashscope-key"),
        )
        # Add Azure OpenAI model for Azure OpenAI tests
        azure_openai_model = ChatModelConfig(
            id="azure-openai-chat",
            model_provider="azure_openai",
            model_name="gpt-4o",
            base_url="https://test.openai.azure.com",
            api_key=os.getenv("AZURE_OPENAI_API_KEY", "test-azure-key"),
        )
        hub.store(openai_model)
        hub.store(deepseek_model)
        hub.store(embedding_model)
        hub.store(dashscope_rerank_model)
        hub.store(azure_openai_model)

        yield hub

        # Cleanup - reset global tool registry
        import xagent.core.storage.manager as storage_manager
        import xagent.core.tools.adapters.langgraph as tool_module

        tool_module._registry = None
        storage_manager._storage_manager = None


# ==========================================
# UTILITY FUNCTIONS (for integration tests)
# ==========================================


def check_langfuse_env():
    """Check required Langfuse environment variables - used by integration tests."""
    public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
    secret_key = os.getenv("LANGFUSE_SECRET_KEY")
    base_url = os.getenv("LANGFUSE_BASE_URL") or os.getenv("LANGFUSE_HOST")

    if not public_key:
        pytest.fail("LANGFUSE_PUBLIC_KEY environment variable is required")
    if not secret_key:
        pytest.fail("LANGFUSE_SECRET_KEY environment variable is required")
    if not base_url:
        pytest.fail(
            "LANGFUSE_BASE_URL or LANGFUSE_HOST environment variable is required"
        )

    return public_key, secret_key, base_url


@pytest.fixture
def clear_langfuse_traces(request):
    """Clear all traces from Langfuse before starting integration tests."""
    if not request.config.getoption("--run-special"):
        pytest.skip("Run only with --run-special")

    public_key, secret_key, host = check_langfuse_env()
    yield


# YAML entrypoint has been removed, commenting out this fixture
# @pytest.fixture
# def mock_migration_manager(tmp_path):
#    """Initialize a temporary MigrationManager."""
#     test_migrations_dir = tmp_path / "test_migrations"
#     test_migrations_dir.mkdir()
#
#     print("user mock")
#     manager = MigrationManager(migrations_dir=str(test_migrations_dir))
#
#     set_yaml_migration_manager(manager)
#
#     yield manager


@pytest.fixture(autouse=True)
def _isolate_retire_writers_state():
    """A direct ``shutdown_event()`` call retires the writers for good.

    Without a startup in between, the next test's retire would return early and
    skip the stop calls it asserts, so every test starts and ends with the
    process-local retirement state cleared.
    """
    import sys

    def reset() -> int:
        """Clear the retirement state; return the tracked workers left over."""
        app_module = sys.modules.get("xagent.web.app")
        if app_module is not None:
            app_module._writers_retired = False
            app_module._retire_writers_lock = None
            app_module._uploaded_file_reconcile_task = None
            app_module.release_hold.reset_writers_retired()
        writers = sys.modules.get("xagent.web.services.writer_workers")
        if writers is None:
            return 0
        leaked = writers._active
        # A test that leaked a tracked worker must not skew the next one.
        writers._active = 0
        writers.install_blocking_tracker()
        return int(leaked)

    reset()
    yield
    leaked = reset()
    assert leaked == 0, (
        f"{leaked} tracked writer worker(s) were still counted when the test "
        "ended: a run_tracked/run_blocking thread was never released"
    )