echo-core/tests/test_voice_adapter_contract.py

# -*- coding: utf-8 -*-
"""Contract test for `src/voice/_discord_voice_adapter.py`.

Purpose: catch drift when the vendored `discord-ext-voice-recv` is upgraded.
If upstream renames/removes a method we depend on, this test fails LOUDLY
before any downstream code breaks at runtime in a Discord voice call.

Per VENDOR_INFO.md: this test MUST PASS after every vendor upgrade.

Plain `import` + `hasattr` / `callable` checks — no mocks. We're verifying
the SHAPE of the API surface, not behavior.
"""

from __future__ import annotations

import inspect

import pytest


# --- Adapter re-exports import cleanly --------------------------------------


def test_adapter_exports_voice_receive_client():
    from src.voice._discord_voice_adapter import VoiceReceiveClient

    assert VoiceReceiveClient is not None
    assert inspect.isclass(VoiceReceiveClient)


def test_adapter_exports_audio_sink():
    from src.voice._discord_voice_adapter import AudioSink

    assert AudioSink is not None
    assert inspect.isclass(AudioSink)


def test_adapter_exports_voice_data():
    from src.voice._discord_voice_adapter import VoiceData

    assert VoiceData is not None
    assert inspect.isclass(VoiceData)


def test_adapter_exports_connect_helper():
    from src.voice._discord_voice_adapter import connect_voice

    assert callable(connect_voice)
    assert inspect.iscoroutinefunction(connect_voice)


# --- Re-exports point at the real vendored classes (no accidental shadowing) -


def test_voice_receive_client_is_voice_recv_client():
    from discord.ext import voice_recv

    from src.voice._discord_voice_adapter import VoiceReceiveClient

    assert VoiceReceiveClient is voice_recv.VoiceRecvClient


def test_audio_sink_is_voice_recv_audio_sink():
    from discord.ext import voice_recv

    from src.voice._discord_voice_adapter import AudioSink

    assert AudioSink is voice_recv.AudioSink


def test_voice_data_is_voice_recv_voice_data():
    from discord.ext import voice_recv

    from src.voice._discord_voice_adapter import VoiceData

    assert VoiceData is voice_recv.VoiceData


# --- VoiceReceiveClient API surface used by the pipeline --------------------


@pytest.mark.parametrize(
    "method_name",
    [
        "connect",          # inherited from discord.VoiceClient
        "disconnect",       # inherited from discord.VoiceClient
        "listen",           # voice_recv extension
        "stop_listening",   # voice_recv extension
        "is_listening",     # voice_recv extension
        "stop",             # voice_recv extension (stops play+listen)
        "cleanup",          # voice_recv extension
    ],
)
def test_voice_receive_client_has_method(method_name):
    from src.voice._discord_voice_adapter import VoiceReceiveClient

    attr = getattr(VoiceReceiveClient, method_name, None)
    assert attr is not None, f"VoiceReceiveClient is missing `.{method_name}()`"
    assert callable(attr), f"VoiceReceiveClient.{method_name} is not callable"


def test_voice_receive_client_listen_accepts_sink_and_after():
    """`.listen(sink, *, after=None)` is the canonical call shape."""
    from src.voice._discord_voice_adapter import VoiceReceiveClient

    sig = inspect.signature(VoiceReceiveClient.listen)
    params = sig.parameters
    assert "sink" in params, f"VoiceReceiveClient.listen missing `sink` param; got {list(params)}"
    assert "after" in params, f"VoiceReceiveClient.listen missing `after` kwarg; got {list(params)}"


def test_voice_receive_client_has_sink_property():
    """`.sink` is read/write so we can swap sinks in place."""
    from src.voice._discord_voice_adapter import VoiceReceiveClient

    sink_attr = inspect.getattr_static(VoiceReceiveClient, "sink", None)
    assert isinstance(sink_attr, property), "VoiceReceiveClient.sink must be a property"
    assert sink_attr.fget is not None, "VoiceReceiveClient.sink property missing getter"
    assert sink_attr.fset is not None, "VoiceReceiveClient.sink property missing setter"


# --- AudioSink API surface --------------------------------------------------


@pytest.mark.parametrize(
    "method_name",
    [
        "write",         # write(user, voice_data) — the hot path
        "cleanup",
        "wants_opus",    # bool: opus bytes vs decoded PCM
    ],
)
def test_audio_sink_has_method(method_name):
    from src.voice._discord_voice_adapter import AudioSink

    attr = getattr(AudioSink, method_name, None)
    assert attr is not None, f"AudioSink is missing `.{method_name}()`"
    assert callable(attr), f"AudioSink.{method_name} is not callable"


def test_audio_sink_write_signature():
    """`.write(self, user, data)` — user is the speaker (Optional), data is VoiceData."""
    from src.voice._discord_voice_adapter import AudioSink

    sig = inspect.signature(AudioSink.write)
    params = list(sig.parameters)
    # self, user, data
    assert len(params) >= 3, f"AudioSink.write expected (self, user, data), got {params}"


# --- VoiceData attributes ---------------------------------------------------


def test_voice_data_slots():
    """VoiceData uses __slots__ for per-packet allocation. Pipeline reads these."""
    from src.voice._discord_voice_adapter import VoiceData

    assert hasattr(VoiceData, "__slots__"), "VoiceData lost __slots__ — perf regression risk"
    slots = set(VoiceData.__slots__)
    # Documented attributes the pipeline depends on.
    assert "packet" in slots, f"VoiceData missing `packet` slot; got {slots}"
    assert "source" in slots, f"VoiceData missing `source` slot (speaker user); got {slots}"
    assert "pcm" in slots, f"VoiceData missing `pcm` slot (decoded audio); got {slots}"


def test_voice_data_has_opus_property():
    """`.opus` exposes the raw opus bytes from the underlying RTP packet."""
    from src.voice._discord_voice_adapter import VoiceData

    opus_attr = inspect.getattr_static(VoiceData, "opus", None)
    assert isinstance(opus_attr, property), "VoiceData.opus must be a property"