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.
Exports
Section titled “Exports”struct Received
Section titled “struct Received”struct Received from: String recipients: List<String> data: String tls: Bool username: Maybe<String> end
One message as a server received it.
Received.inspect
Section titled “Received.inspect”impl Debug for Received
fn inspect(value: Received) -> String
impl Debug.inspect
Received.equal
Section titled “Received.equal”impl Equatable for Received
fn equal(a: Received, b: Received) -> Bool
impl Equatable.equal
struct Memory
Section titled “struct Memory”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"]]
Memory.new
Section titled “Memory.new”fn new() -> Memory
type function on Memory
A mailer that has sent nothing.
Memory.sent
Section titled “Memory.sent”fn sent(memory: Memory) -> List<Message>
type function on Memory
Every message sent, oldest first.
Memory.received
Section titled “Memory.received”fn received(memory: Memory) -> List<Received>
type function on Memory
The same sends as a server receives them: envelope and text.
Memory.send
Section titled “Memory.send”impl Mailer for Memory
fn send(memory: Memory, message: Message) -> Result<Unit, Error>
impl Mailer.send
Memory.inspect
Section titled “Memory.inspect”impl Debug for Memory
fn inspect(value: Memory) -> String
impl Debug.inspect
struct Failing
Section titled “struct Failing”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)
Failing.send
Section titled “Failing.send”impl Mailer for Failing
fn send(failing: Failing, _message: Message) -> Result<Unit, Error>
impl Mailer.send
Failing.inspect
Section titled “Failing.inspect”impl Debug for Failing
fn inspect(value: Failing) -> String
impl Debug.inspect
struct SmtpServer
Section titled “struct SmtpServer”struct SmtpServer
opaque — construction surface is private to its defining module
An SMTP server with_smtp_server runs.
SmtpServer.config
Section titled “SmtpServer.config”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.
SmtpServer.received
Section titled “SmtpServer.received”fn received(server: SmtpServer) -> List<Received>
type function on SmtpServer
Every message it accepted, oldest first.
SmtpServer.inspect
Section titled “SmtpServer.inspect”impl Debug for SmtpServer
fn inspect(value: SmtpServer) -> String
impl Debug.inspect
testing.with_smtp_server
Section titled “testing.with_smtp_server”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
Section titled “struct Opened”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.
Opened.inspect
Section titled “Opened.inspect”impl Debug for Opened
fn inspect(value: Opened) -> String
impl Debug.inspect
struct Broken
Section titled “struct Broken”struct Broken rule: String message: String end
A conformance rule a mailer broke, and how. Its Display is rule: message.
Broken.to_string
Section titled “Broken.to_string”impl Display for Broken
fn to_string(broken: Broken) -> String
impl Display.to_string
Broken.inspect
Section titled “Broken.inspect”impl Debug for Broken
fn inspect(value: Broken) -> String
impl Debug.inspect
Broken.equal
Section titled “Broken.equal”impl Equatable for Broken
fn equal(a: Broken, b: Broken) -> Bool
impl Equatable.equal
testing.conformance
Section titled “testing.conformance”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.
testing.rules
Section titled “testing.rules”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")