Skip to content

xtr_mailer.testing

Testing what an application emails, and the transport factories a provider library ships.

For an application, the email checks read what a :class:~xtr_mailer.event_listener.MessageLoggerListener recorded, listening to :class:~xtr_mailer.event.MessageEvent::

events = listener.get_events()

assert_email_count(events, 1, "null://")
assert_email_is_not_queued(events.get_events()[0])

What an email says — its headers, its subject, its bodies, its attachments — is checked with :mod:xtr_mime.testing, on the emails events.get_messages() returns.

For a provider library, :func:assert_factory_cases holds its transport factory to what every factory owes — the schemes it serves, the transport it builds from a DSN, a DSN refused for the reason it is wrong. The library states its cases in 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, and the package itself never imports this module.

FactoryCases dataclass

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

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

Every transport factory owes the same things — to serve its schemes and no other, to build the transport a DSN describes, to refuse a scheme it does not serve and a DSN missing what its transport needs — so a factory'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_factory (Callable[[], TransportFactoryInterface]) –

    Builds the factory under test.

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

    Pairs of a DSN and whether the factory must serve it.

  • create (Sequence[tuple[Dsn, TransportInterface]]) –

    Pairs of a DSN and the transport the factory must build from it: one of the same class, which read_state reads the same as.

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

    Pairs of a DSN create must refuse with :class:~xtr_mailer.exception.UnsupportedSchemeError and the text its error must contain, or None to check the error's type alone.

  • incomplete_dsn (Sequence[Dsn]) –

    DSNs create must refuse with :class:~xtr_mailer.exception.IncompleteDsnError — a user or a password missing.

  • read_state (Callable[[TransportInterface], object]) –

    Reads what two transports built alike agree on: their string form, unless given. A transport's string never shows its credentials, nor every setting a DSN option makes, so a factory whose transports carry those reads them here.

assert_email_count

assert_email_count(events: MessageEvents, expected_count: int, transport_name: str | None = None) -> None

Check expected_count emails were sent — through transport_name only, when given.

events is what a :class:~xtr_mailer.event_listener.MessageLoggerListener recorded; a transport goes by the name it gives itself, null:// or smtp://mail.example.com.

Raises:

assert_email_is_not_queued

assert_email_is_not_queued(event: MessageEvent) -> None

Check event's email was sent rather than queued.

Raises:

assert_email_is_queued

assert_email_is_queued(event: MessageEvent) -> None

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

Raises:

assert_queued_email_count

assert_queued_email_count(events: MessageEvents, expected_count: int, transport_name: str | None = None) -> None

Check expected_count emails were queued on a message bus, for transport_name.

transport_name left out, every email queued counts.

Raises:

assert_factory_cases

assert_factory_cases(cases: FactoryCases) -> None

Check a transport factory against every one of cases.

For example::

assert_factory_cases(
    FactoryCases(
        create_factory=lambda: AcmeTransportFactory(http_client=MockHttpClient()),
        supports=[(Dsn("acme", "default"), True), (Dsn("other", "default"), False)],
        create=[(Dsn("acme", "default", USER), AcmeTransport(USER, MockHttpClient()))],
        unsupported_scheme=[(Dsn("other", "default", USER), None)],
        incomplete_dsn=[Dsn("acme", "default")],
    )
)

A transport built for smtp or smtps must also read as smtp://…host…, the scheme first and the DSN's host somewhere after it, whatever read_state reads.

Raises:

  • AssertionError –

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