Skip to content

Build and run agents you can see, understand and trust.

13.1 KB
Raw Blame
# -*- coding: utf-8 -*-
# pylint: disable=protected-access
"""Unit tests for the OpenAI TTS model.

Covers:
  * ``OpenAITTSModel`` non-streaming aggregation.
  * ``OpenAITTSModel`` streaming: incremental chunks and ``is_last``
    placement at the final chunk only.
  * Edge cases: empty/None input short-circuits without calling the API.
"""
import base64
from typing import Any
from unittest import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, MagicMock

from agentscope.credential import OpenAICredential
from agentscope.tts import OpenAITTSModel, TTSResponse


_MEDIA_TYPE_MP3 = "audio/mpeg"
_MEDIA_TYPE_WAV = "audio/wav"


def _make_mock_client(audio_bytes: bytes, chunks: list[bytes]) -> MagicMock:
    """Build a mock ``openai.AsyncClient`` shaped like what
    ``audio.speech.create`` / ``with_streaming_response.create`` return."""
    client = MagicMock()

    # Non-streaming: client.audio.speech.create(...) -> response with
    # .content bytes.
    create_response = MagicMock()
    create_response.content = audio_bytes
    client.audio.speech.create = AsyncMock(return_value=create_response)

    # Streaming: client.audio.speech.with_streaming_response.create(...)
    # is an async context manager whose value exposes .iter_bytes().
    stream_response = MagicMock()

    async def _iter_bytes() -> Any:
        for chunk in chunks:
            yield chunk

    stream_response.iter_bytes = _iter_bytes

    stream_ctx = MagicMock()
    stream_ctx.__aenter__ = AsyncMock(return_value=stream_response)
    stream_ctx.__aexit__ = AsyncMock(return_value=None)

    client.audio.speech.with_streaming_response.create = MagicMock(
        return_value=stream_ctx,
    )

    return client


class TestOpenAITTSModel(IsolatedAsyncioTestCase):
    """The unittests for the OpenAI TTS model (non-realtime)."""

    def _make_model(self, stream: bool = False, **kwargs: Any) -> Any:
        """Create an OpenAITTSModel with test credentials."""
        return OpenAITTSModel(
            credential=OpenAICredential(api_key="test"),
            model="tts-1",
            stream=stream,
            **kwargs,
        )

    async def test_aggregates_response(self) -> None:
        """Non-streaming returns a single TTSResponse with the full audio."""
        client = _make_mock_client(b"AAAABBBBCCCC", [])
        model = self._make_model(stream=False)
        # Client is built eagerly in __init__; inject the mock onto the
        # instance so synthesize() hits it instead of the network.
        model.client = client
        result = await model.synthesize("Hello world")

        self.assertIsInstance(result, TTSResponse)
        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE_MP3)
        self.assertEqual(
            base64.b64decode(result.content.source.data),
            b"AAAABBBBCCCC",
        )
        self.assertTrue(result.is_last)

    async def test_none_short_circuits(self) -> None:
        """``synthesize(None)`` returns an empty response without touching
        the API."""
        model = self._make_model(stream=False)
        mock_client = _make_mock_client(b"", [])
        model.client = mock_client
        result = await model.synthesize(None)

        self.assertIsNone(result.content)
        mock_client.audio.speech.create.assert_not_called()

    async def test_preset_and_custom_voice_payloads(self) -> None:
        """Both output modes preserve named and custom voice API shapes."""
        for stream in (False, True):
            for voice in ("alloy", {"id": "voice_123"}):
                with self.subTest(stream=stream, voice=voice):
                    model = OpenAITTSModel(
                        credential=OpenAICredential(api_key="test"),
                        model="gpt-4o-mini-tts",
                        stream=stream,
                        parameters=OpenAITTSModel.Parameters(voice=voice),
                    )
                    client = _make_mock_client(b"AAAA", [b"AAAA"])
                    model.client = client
                    result = await model.synthesize("Hello")
                    if stream:
                        async for _ in result:
                            pass
                    create = (
                        client.audio.speech.with_streaming_response.create
                        if stream
                        else client.audio.speech.create
                    )
                    self.assertEqual(
                        create.call_args.kwargs,
                        {
                            "model": "gpt-4o-mini-tts",
                            "voice": voice,
                            "input": "Hello",
                            "response_format": "mp3",
                        },
                    )

    def test_custom_voice_model_cards(self) -> None:
        """Only the supported synthesis model advertises custom voices."""
        self.assertEqual(
            {c.name: c.voice_cloning for c in OpenAITTSModel.list_models()},
            {
                "tts-1": False,
                "tts-1-hd": False,
                "gpt-4o-mini-tts": True,
            },
        )

    def test_model_specific_preset_voices(self) -> None:
        """Legacy models expose fewer presets than GPT-4o mini TTS."""
        legacy_voices = [
            "alloy",
            "ash",
            "coral",
            "echo",
            "fable",
            "onyx",
            "nova",
            "sage",
            "shimmer",
        ]
        self.assertEqual(
            {
                card.name: card.parameter_schema["properties"]["voice"]["enum"]
                for card in OpenAITTSModel.list_models()
            },
            {
                "tts-1": legacy_voices,
                "tts-1-hd": legacy_voices,
                "gpt-4o-mini-tts": [
                    "alloy",
                    "ash",
                    "ballad",
                    "coral",
                    "echo",
                    "fable",
                    "onyx",
                    "nova",
                    "sage",
                    "shimmer",
                    "verse",
                    "marin",
                    "cedar",
                ],
            },
        )

    async def test_empty_string_short_circuits(self) -> None:
        """``synthesize("")`` returns an empty response without touching
        the API."""
        model = self._make_model(stream=False)
        mock_client = _make_mock_client(b"", [])
        model.client = mock_client
        result = await model.synthesize("")

        self.assertIsNone(result.content)
        mock_client.audio.speech.create.assert_not_called()

    async def test_wav_media_type(self) -> None:
        """The media type follows the ``response_format`` parameter."""
        client = _make_mock_client(b"AAAA", [])
        model = self._make_model(
            stream=False,
            parameters=OpenAITTSModel.Parameters(response_format="wav"),
        )
        model.client = client
        result = await model.synthesize("Hello world")

        self.assertEqual(result.content.source.media_type, _MEDIA_TYPE_WAV)

    async def test_per_call_format_controls_media_type(self) -> None:
        """Both output modes label audio using the effective API format."""
        for stream in (False, True):
            model = self._make_model(stream=stream)
            client = _make_mock_client(b"AAAABBBB", [b"AAAA", b"BBBB"])
            model.client = client
            create = (
                client.audio.speech.with_streaming_response.create
                if stream
                else client.audio.speech.create
            )
            for response_format, media_type in (
                ("wav", "audio/wav"),
                ("pcm", "audio/pcm"),
                ("opus", "audio/opus"),
            ):
                with self.subTest(stream=stream, format=response_format):
                    result = await model.synthesize(
                        "Hello",
                        response_format=response_format,
                    )
                    responses = (
                        [chunk async for chunk in result]
                        if stream
                        else [result]
                    )
                    self.assertEqual(
                        create.call_args.kwargs["response_format"],
                        response_format,
                    )
                    self.assertEqual(
                        [r.content.source.media_type for r in responses],
                        [media_type] * len(responses),
                    )
                    self.assertEqual(
                        b"".join(
                            base64.b64decode(r.content.source.data)
                            for r in responses
                        ),
                        b"AAAABBBB",
                    )
                    self.assertEqual(model.parameters.response_format, "mp3")

            # A one-off format override must not change the next call.
            result = await model.synthesize("Next call")
            responses = (
                [chunk async for chunk in result] if stream else [result]
            )
            self.assertEqual(create.call_args.kwargs["response_format"], "mp3")
            self.assertEqual(
                [r.content.source.media_type for r in responses],
                [_MEDIA_TYPE_MP3] * len(responses),
            )

    async def test_per_call_instructions_override_default(self) -> None:
        """Per-call instructions win without mutating the default."""
        for stream in (False, True):
            for default in ("Speak cheerfully", ""):
                model = self._make_model(
                    stream=stream,
                    parameters=OpenAITTSModel.Parameters(
                        instructions=default,
                    ),
                )
                client = _make_mock_client(b"AAAA", [b"AAAA"])
                model.client = client
                create = (
                    client.audio.speech.with_streaming_response.create
                    if stream
                    else client.audio.speech.create
                )
                for override in ("Speak quietly", ""):
                    with self.subTest(
                        stream=stream,
                        default=default,
                        override=override,
                    ):
                        result = await model.synthesize(
                            "Hello",
                            instructions=override,
                        )
                        if stream:
                            async for _ in result:
                                pass
                        self.assertEqual(
                            create.call_args.kwargs["instructions"],
                            override,
                        )
                        self.assertEqual(
                            model.parameters.instructions,
                            default,
                        )

                result = await model.synthesize("Next call")
                if stream:
                    async for _ in result:
                        pass
                if default:
                    self.assertEqual(
                        create.call_args.kwargs["instructions"],
                        default,
                    )
                else:
                    self.assertNotIn("instructions", create.call_args.kwargs)

    async def test_incremental_chunks(self) -> None:
        """Each streamed byte chunk yields one TTSResponse."""
        client = _make_mock_client(b"", [b"AAAA", b"BBBB", b"CCCC"])
        model = self._make_model(stream=True)
        model.client = client
        gen = await model.synthesize("Hello world")
        chunks = [c async for c in gen]

        payloads = [base64.b64decode(c.content.source.data) for c in chunks]
        self.assertEqual(payloads, [b"AAAA", b"BBBB", b"CCCC"])
        self.assertEqual(
            [c.is_last for c in chunks],
            [False, False, True],
        )
        self.assertEqual(
            [c.content.source.media_type for c in chunks],
            [_MEDIA_TYPE_MP3] * 3,
        )

    async def test_single_chunk_marked_last(self) -> None:
        """A lone audio chunk is flagged ``is_last=True``."""
        client = _make_mock_client(b"", [b"ONLYCHUNK"])
        model = self._make_model(stream=True)
        model.client = client
        gen = await model.synthesize("Hello world")
        chunks = [c async for c in gen]

        self.assertEqual(len(chunks), 1)
        self.assertTrue(chunks[0].is_last)
        self.assertEqual(
            base64.b64decode(chunks[0].content.source.data),
            b"ONLYCHUNK",
        )

    async def test_empty_stream_yields_terminal(self) -> None:
        """When the API yields no audio, the generator emits a terminal
        sentinel so consumers can detect EOS."""
        client = _make_mock_client(b"", [])
        model = self._make_model(stream=True)
        model.client = client
        gen = await model.synthesize("Hello world")
        chunks = [c async for c in gen]

        self.assertEqual(len(chunks), 1)
        self.assertIsNone(chunks[0].content)
        self.assertTrue(chunks[0].is_last)