Skip to content

xtr_notifier.testing

Testing what an application notifies, and the transports a provider library ships.

For an application, the assert_notification_* checks read what a :class:~xtr_notifier.event_listener.NotificationLoggerListener recorded::

assert_notification_count(listener.events, 1, "slack")
assert_notification_subject_contains(listener.events.get_messages()[0], "Disk")

For a provider library, :func:assert_transport_cases and :func:assert_factory_cases hold its transport and its factory to what every provider owes — a string form without credentials, the messages it sends, a refusal of the others, a host and port that can be overridden, a DSN refused for the reason it is wrong. The library states its cases in a :class:TransportCases and a :class:FactoryCases; every case is checked, and every failure is reported at once.

Nothing here needs a test framework: each check raises :class:AssertionError.

FactoryCases dataclass

FactoryCases(create_factory: Callable[[], TransportFactoryInterface], supports: Sequence[tuple[bool, str]] = tuple[tuple[bool, str], ...](), create: Sequence[tuple[str, str]] = tuple[tuple[str, str], ...](), unsupported_scheme: Sequence[tuple[str, str | None]] = tuple[tuple[str, str | None], ...](), incomplete_dsn: Sequence[tuple[str, str | None]] = tuple[tuple[str, str | None], ...](), missing_required_option: Sequence[tuple[str, str | None]] = tuple[tuple[str, str | None], ...]())

The cases :func:~xtr_notifier.testing.assert_factory_cases drives a factory over.

Each refusal pairs a DSN with the text its error must contain, or None to check the error's type alone. The sequences are copied into tuples, so the cases cannot change half way through a run.

Attributes:

  • create_factory (Callable[[], TransportFactoryInterface]) –

    Builds the factory under test.

  • supports (Sequence[tuple[bool, str]]) –

    Pairs of whether the factory must serve a DSN, and that DSN.

  • create (Sequence[tuple[str, str]]) –

    Pairs of the string the transport built from a DSN must read as, and that DSN.

  • unsupported_scheme (Sequence[tuple[str, str | None]]) –

    DSNs create must refuse with :class:~xtr_notifier.exception.UnsupportedSchemeError.

  • incomplete_dsn (Sequence[tuple[str, str | None]]) –

    DSNs create must refuse with :class:~xtr_notifier.exception.IncompleteDsnError — a missing token, a malformed one.

  • missing_required_option (Sequence[tuple[str, str | None]]) –

    DSNs create must refuse with :class:~xtr_notifier.exception.MissingRequiredOptionError.

TransportCases dataclass

TransportCases(create_transport: Callable[[], AbstractTransport], to_string: Sequence[tuple[str, TransportInterface]] = tuple[tuple[str, TransportInterface], ...](), supported: Sequence[MessageInterface] = tuple[MessageInterface, ...](), unsupported: Sequence[MessageInterface] = tuple[MessageInterface, ...]())

The cases :func:~xtr_notifier.testing.assert_transport_cases drives a transport over.

Every provider transport owes the same things — a string form without credentials, the messages it sends, a refusal of the rest, a host and port that can be overridden — so a provider's test states its cases here and the checks are written once. The sequences are copied into tuples, so the cases cannot change half way through a run.

Attributes:

  • create_transport (Callable[[], AbstractTransport]) –

    Builds a fresh transport for each check — usually over a MockHttpClient, since only the unsupported messages are sent, and those must be refused before any request.

  • to_string (Sequence[tuple[str, TransportInterface]]) –

    Pairs of the string a transport must read as, and that transport — one per DSN option that changes it.

  • supported (Sequence[MessageInterface]) –

    Messages the transport must say it sends.

  • unsupported (Sequence[MessageInterface]) –

    Messages it must refuse, both in supports and by raising :class:~xtr_notifier.exception.UnsupportedMessageTypeError when sent.

assert_factory_cases

assert_factory_cases(cases: FactoryCases) -> None

Check a factory against every one of cases.

For example::

assert_factory_cases(
    FactoryCases(
        create_factory=lambda: AcmeTransportFactory(MockHttpClient()),
        supports=[(True, "acme://TOKEN@default"), (False, "other://TOKEN@default")],
        create=[("acme://api.acme.test", "acme://TOKEN@default")],
        unsupported_scheme=[("other://TOKEN@default", None)],
        incomplete_dsn=[("acme://default", "Missing token.")],
    )
)

Raises:

  • AssertionError –

    Listing every case the factory fails. Raised rather than asserted, so the check holds however the suite is run.

assert_notification_count

assert_notification_count(events: NotificationEvents, count: int, transport: str | None = None) -> None

Check count notifications were sent — on transport only, when given.

events is what a :class:~xtr_notifier.event_listener.NotificationLoggerListener recorded; a notification naming no transport is filed under "".

Raises:

assert_notification_is_not_queued

assert_notification_is_not_queued(event: MessageEvent) -> None

Check event's message was sent rather than queued.

Raises:

assert_notification_is_queued

assert_notification_is_queued(event: MessageEvent) -> None

Check event's message was queued on a bus rather than sent.

Raises:

assert_notification_subject_contains

assert_notification_subject_contains(message: MessageInterface, text: str) -> None

Check message's subject contains text.

Raises:

assert_notification_subject_not_contains

assert_notification_subject_not_contains(message: MessageInterface, text: str) -> None

Check message's subject does not contain text.

Raises:

assert_notification_transport_is

assert_notification_transport_is(message: MessageInterface, transport: str | None) -> None

Check message names the transport transport — None for none.

Raises:

assert_notification_transport_is_not

assert_notification_transport_is_not(message: MessageInterface, transport: str | None) -> None

Check message does not name the transport transport.

Raises:

assert_queued_notification_count

assert_queued_notification_count(events: NotificationEvents, count: int, transport: str | None = None) -> None

Check count notifications were queued on a bus — on transport only, when given.

Raises:

assert_transport_cases async

assert_transport_cases(cases: TransportCases) -> None

Check a transport against every one of cases.

Beyond the cases, a transport pointed at :data:CUSTOM_HOST and :data:CUSTOM_PORT must show them in its string form, which is how an application tells a self-hosted provider from the default one::

await assert_transport_cases(
    TransportCases(
        create_transport=lambda: AcmeTransport("TOKEN", MockHttpClient()),
        to_string=[("acme://api.acme.test", AcmeTransport("TOKEN", MockHttpClient()))],
        supported=[ChatMessage("Hello")],
        unsupported=[SmsMessage("+33", "Hello")],
    )
)

Raises:

  • AssertionError –

    Listing every case the transport fails. Raised rather than asserted, so the check holds however the suite is run.