Test utilities

def make_bot(self) -> SignalBot:
    """Build the bot under test; called by `setup()`.

    Override it when the bot is built by your own code, e.g. an application
    object that creates its `SignalBot` internally, and return that
    `SignalBot` (keeping a reference to the wrapper on `self` if tests need
    it). Use `self.config` for a configuration pointing at the mocked
    service. Assigning `self.signal_bot` directly works too.
    """
    return SignalBot(ChatTestCase.config)

@classmethod
def new_edit_message(
    cls,
    text: str,
    *,
    source_uuid: str,
    target_sent_timestamp: int,
    timestamp: int | None = None,
) -> Envelope:
    """A direct message from `source_uuid` editing their earlier message sent
    at `target_sent_timestamp`; it is received as an
    [EditMessage][signalbot.messages.EditMessage] by `DataMessageHandler`s.

    Args:
        text: The new text of the message.
        source_uuid: The sender's uuid, i.e. the author of the edited message.
        target_sent_timestamp: The timestamp of the message being edited.
        timestamp: The timestamp of the edit; a fresh, unique one if `None`.
    """
    if timestamp is None:
        timestamp = _new_timestamp()
    return cls._received_envelope(
        source_uuid=source_uuid,
        timestamp=timestamp,
        editMessage={
            "targetSentTimestamp": target_sent_timestamp,
            "dataMessage": {
                "timestamp": timestamp,
                "message": text,
                "expiresInSeconds": 0,
                "viewOnce": False,
            },
        },
    )

@classmethod
def new_message(cls, text: str) -> Envelope:
    """A text message sent in the test group (`ChatTestCase.group_id`) by the
    bot's own account.

    This is what `mock_chat` turns plain `str` messages into.
    """
    timestamp = _new_timestamp()
    new_uuid = str(uuid.uuid4())
    return cls._sent_message_envelope(
        timestamp=timestamp, new_uuid=new_uuid, message=text
    )

@classmethod
def new_private_message(  # noqa: PLR0913
    cls,
    text: str | None,
    *,
    source_uuid: str | None = None,
    timestamp: int | None = None,
    quote: dict | None = None,
    attachments: list[dict] | None = None,
    view_once: bool = False,
) -> Envelope:
    """A direct (one-on-one) message to the bot, so `message.is_private()` is
    true and it reaches handlers registered with `groups=False`.

    Args:
        text: The message text.
        source_uuid: The sender's uuid; a random uuid4 if `None`.
        timestamp: The message timestamp in milliseconds; a fresh, unique one
            if `None`. Pass it explicitly to refer to this message later
            (e.g. from `new_edit_message` or `new_remote_delete`).
        quote: The quoted message in signal-cli's raw format, e.g.
            `{"id": <quoted timestamp>, "author": ..., "authorUuid": ...,
            "text": ...}`.
        attachments: Attachments in signal-cli's raw format, e.g.
            `{"id": ..., "contentType": "image/png", "isVoiceNote": False}`.
        view_once: Whether the message is a view-once message.
    """
    if timestamp is None:
        timestamp = _new_timestamp()
    data_message: dict[str, object] = {
        "timestamp": timestamp,
        "message": text,
        "expiresInSeconds": 0,
        "viewOnce": view_once,
    }
    if quote is not None:
        data_message["quote"] = quote
    if attachments is not None:
        data_message["attachments"] = attachments
    return cls._received_envelope(
        source_uuid=source_uuid or str(uuid.uuid4()),
        timestamp=timestamp,
        dataMessage=data_message,
    )

@classmethod
def new_reaction_message(cls, emoji: str) -> Envelope:
    """A reaction with `emoji`, sent in the test group by the bot's own
    account."""
    timestamp = _new_timestamp()
    new_uuid = str(uuid.uuid4())
    return cls._sent_message_envelope(
        timestamp=timestamp,
        new_uuid=new_uuid,
        message=None,
        reaction={
            "emoji": emoji,
            "targetAuthor": ChatTestCase.phone_number,
            "targetAuthorNumber": ChatTestCase.phone_number,
            "targetAuthorUuid": new_uuid,
            "targetSentTimestamp": timestamp,
            "isRemove": False,
        },
    )

@classmethod
def new_remote_delete(
    cls,
    *,
    source_uuid: str,
    target_sent_timestamp: int,
    timestamp: int | None = None,
) -> Envelope:
    """A direct message from `source_uuid` deleting their earlier message sent
    at `target_sent_timestamp`; it is received by `RemoteDeleteHandler`s as a
    [RemoteDelete][signalbot.messages.RemoteDelete] whose `timestamp` is
    `target_sent_timestamp`.

    Args:
        source_uuid: The sender's uuid, i.e. the author of the deleted message.
        target_sent_timestamp: The timestamp of the message being deleted.
        timestamp: The timestamp of the delete itself; a fresh, unique one if
            `None`.
    """
    if timestamp is None:
        timestamp = _new_timestamp()
    return cls._received_envelope(
        source_uuid=source_uuid,
        timestamp=timestamp,
        dataMessage={
            "timestamp": timestamp,
            "expiresInSeconds": 0,
            "viewOnce": False,
            "remoteDelete": {"timestamp": target_sent_timestamp},
        },
    )

def setup(self) -> None:
    """Create the bot under test as `self.signal_bot` (see `make_bot`).

    Call it from a fixture, then register handlers on `self.signal_bot`.
    """
    self.signal_bot = self.make_bot()

def results(self) -> list[SendMessageV2]:
    """The message request passed to each send, in call order."""
    return self._first_args()

def results(self) -> list[SendReactionRequest]:
    """The reaction request passed to each call, in call order."""
    return self._first_args()

def results(self) -> list[RemoteDeleteRequest]:
    """The delete request passed to each call, in call order."""
    return self._first_args()

def define(self, messages: Sequence[str]) -> None:
    """Make `receive()` yield `messages`: an
    [Envelope][signalbot.test_utils.Envelope] is yielded as-is, a plain `str`
    is wrapped with `ChatTestCase.new_message`."""
    json_messages = [
        m if isinstance(m, Envelope) else ChatTestCase.new_message(m)
        for m in messages
    ]
    mock_iterator = AsyncMock()
    mock_iterator.__aiter__.return_value = json_messages
    self.return_value = mock_iterator