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_statereads the same as. -
unsupported_scheme(Sequence[tuple[Dsn, str | None]]) –Pairs of a DSN
createmust refuse with :class:~xtr_mailer.exception.UnsupportedSchemeErrorand the text its error must contain, orNoneto check the error's type alone. -
incomplete_dsn(Sequence[Dsn]) –DSNs
createmust 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:
-
AssertionError–When another number was sent.
assert_email_is_not_queued ¶
assert_email_is_queued ¶
Check event's email was queued on a message bus rather than sent.
Raises:
-
AssertionError–When it was sent.
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:
-
AssertionError–When another number was queued.
assert_factory_cases ¶
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.