Skip to content

std::mail::testing

Testing code that uses std::mail. Memory is a Mailer that keeps what it sends in memory, so a test sends and asserts with no server:

test "signing up sends a login link"
    memory = Memory.new()
    with App.mailer = memory
    sign_up("ana@example.com")?
    assert [message] = Memory.sent(memory)
    assert message.subject == "Your login link"
end

Failing is a mailer whose every send fails with an error the test picks, for testing what a caller does when mail cannot go out. with_smtp_server runs a small SMTP server on 127.0.0.1 for the length of a test body, with STARTTLS and AUTH when asked, so mail.smtp is tested with no network and no outside tool. conformance is the suite every backend passes: a backend’s own tests run it against mailers it opens.

Import with import std::mail::testing.

struct Received
    from: String
    recipients: List<String>
    data: String
    tls: Bool
    username: Maybe<String>
end

One message as a server received it.

impl Debug for Received

fn inspect(value: Received) -> String

impl Debug.inspect

impl Equatable for Received

fn equal(a: Received, b: Received) -> Bool

impl Equatable.equal

struct Memory

opaque — construction surface is private to its defining module

A Mailer that keeps every message it sends, shared by every copy of the value. It writes each message with mail.render first, so a message any mailer refuses is refused here too.

import std::mail.{Address, Mailer, Message}

memory = Memory.new()

message = Message{
    from: Address.new("a@example.com")?,
    to:   [Address.new("b@example.com")?],
    text: Some("hi"),
}

assert Mailer.send(memory, message) == Ok(Unit)
assert Memory.sent(memory) == [message]
assert Iter.map(Memory.received(memory), &(&1.recipients)) |> Iter.to_list() == [["b@example.com"]]
fn new() -> Memory

type function on Memory

A mailer that has sent nothing.

fn sent(memory: Memory) -> List<Message>

type function on Memory

Every message sent, oldest first.

fn received(memory: Memory) -> List<Received>

type function on Memory

The same sends as a server receives them: envelope and text.

impl Mailer for Memory

fn send(memory: Memory, message: Message) -> Result<Unit, Error>

impl Mailer.send

impl Debug for Memory

fn inspect(value: Memory) -> String

impl Debug.inspect

struct Failing
    error: Error = Error.Network{reason: "the test's mailer is failing"}
end

A Mailer whose every send fails with error, for testing what a caller does when mail cannot go out. The default error is a Network one.

import std::mail.{Address, Error, Mailer, Message}

failing = Failing{error: Error.Rejected{command: "RCPT TO", code: 550, reply: "no"}}

message = Message{
    from: Address.new("a@example.com")?,
    to:   [Address.new("b@example.com")?],
    text: Some("hi"),
}

assert Err(Error.Rejected{command: _, code: 550, reply: _}) = Mailer.send(failing, message)

impl Mailer for Failing

fn send(failing: Failing, _message: Message) -> Result<Unit, Error>

impl Mailer.send

impl Debug for Failing

fn inspect(value: Failing) -> String

impl Debug.inspect

struct SmtpServer

opaque — construction surface is private to its defining module

An SMTP server with_smtp_server runs.

fn config(server: SmtpServer) -> SmtpConfig

type function on SmtpServer

A config that reaches the server: its port, STARTTLS with roots that trust its certificate when it offers it, and its credentials when it asks for them.

fn received(server: SmtpServer) -> List<Received>

type function on SmtpServer

Every message it accepted, oldest first.

impl Debug for SmtpServer

fn inspect(value: SmtpServer) -> String

impl Debug.inspect

fn with_smtp_server<T>(starttls: Bool = False, credentials: Maybe<Credentials> = None, body: (SmtpServer) -> T) -> T

Runs body while an SMTP server listens on 127.0.0.1, then stops it. With starttls it offers STARTTLS with a certificate made for 127.0.0.1; with credentials it offers AUTH PLAIN and LOGIN and takes no mail until a client authenticates with them. It refuses a recipient whose address starts with reject, with a 550. It serves one connection at a time.

import std::mail.{self, Address, Credentials, Mailer, Message}

message = Message{
    from: Address.new("a@example.com")?,
    to:   [Address.new("b@example.com")?],
    text: Some("hi"),
}

credentials = Some(Credentials{username: "u", password: "p"})

(sent, received) = with_smtp_server(starttls: True, credentials:, fn server ->
    (Mailer.send(mail.smtp(SmtpServer.config(server)), message), SmtpServer.received(server))
end)

assert sent == Ok(Unit)

assert [
    Received{
        from: "a@example.com",
        recipients: ["b@example.com"],
        data: _,
        tls: True,
        username: Some("u"),
    },
] = received

Not run here: this example opens network connections and serves network requests, which a browser cannot do. nomi test runs it.

struct Opened
    mailer: Mailer
    received: () -> List<Received>
end

What a backend under conformance is: a mailer, and what has reached its server since it was opened.

impl Debug for Opened

fn inspect(value: Opened) -> String

impl Debug.inspect

struct Broken
    rule: String
    message: String
end

A conformance rule a mailer broke, and how. Its Display is rule: message.

impl Display for Broken

fn to_string(broken: Broken) -> String

impl Display.to_string

impl Debug for Broken

fn inspect(value: Broken) -> String

impl Debug.inspect

impl Equatable for Broken

fn equal(a: Broken, b: Broken) -> Bool

impl Equatable.equal

fn conformance(open: () -> Opened) -> List<Broken>

Runs every conformance rule against mailers from open, and returns the rules broken: none for a backend that conforms. Each rule opens a fresh mailer and reads what reached its server through received.

The rules cover every recipient getting a message once, Bcc in no header, the envelope sender, refusing a message with no recipient, no body, a reserved header or a header value with a line break before anything is sent, a subject with a line break adding no header, a non-ASCII message arriving as 7-bit CRLF text, a line starting with a dot arriving intact, text and HTML as multipart/alternative, extra headers in order, and an attachment.

import std::mail

memory = fn ->
    m = Memory.new()
    Opened{mailer: m, received: fn -> Memory.received(m)}
end

assert conformance(memory) == []

smtp = with_smtp_server(starttls: True, credentials: Some(
    mail.Credentials{username: "u", password: "p"}
), fn server ->
    conformance(fn ->
        before = Iter.count(SmtpServer.received(server))

        Opened{
            mailer:   mail.smtp(SmtpServer.config(server)),
            received: fn -> SmtpServer.received(server) |> Iter.drop(before) |> Iter.to_list(),
        }
    end)
end)

assert smtp == []

Not run here: this example opens network connections and serves network requests, which a browser cannot do. nomi test runs it.

fn rules() -> List<String>

The names of the conformance rules, in the order conformance runs them.

assert Iter.contains(rules(), "bcc is in no header")