Detour

Detour provides the ability to easily test email deliverability using simple-to-use assertions against a real SMTP server.

Installation

Add detour to your list of dependencies in mix.exs:

def deps do
  [{:detour, "~> 0.2", only: :test}]
end

Usage

Ensure detour is started before running any tests.

ExUnit.start()

Application.ensure_all_started(:detour)

Starting a Detour Server

Detour.open/1 can be used to start a Detour server. A Detour server is an in-memory SMTP server that can be used to receive SMTP traffic and perform assertions to verify behavior.

Detour.open/1 returns a %Detour{} struct with fields pid and port. pid is the address of the Detour server and port is the port number used when sending traffic to Detour. The relay used by your SMTP client should always be localhost when sending traffic to a Detour server.

By default, Detour.open/1 will choose an open port. This is preferable over specifying a static port as it makes working with Detour more flexible. You can specify a port by passing the :port option to Detour.open/1.

When allowing Detour to provide a port Detour will take take care of releasing the port after a test finishes. If you specify a port you will need to perform this clean up yourself. You can do this by calling Detour.shutdown/2 after a test has run.

Examples

When allowing Detour to provide a port.

test "automatic port assignment" do
  detour = Detour.open()

  from = "me@notyou.com"

  to = ["you@notme.com"]

  body = "To: you@notme.com\r\nSubject: Hello, world!\r\nFrom: me@notyou.com\r\nContent-Type: text/plain\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nNice to meet you"

  message = {from, to, body}

  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])

  assert_message_delivered message
end

When providing a port to Detour.

test "specifying a port" do
  detour = Detour.open([port: 2525])

  from = "me@notyou.com"

  to = ["you@notme.com"]

  body = "To: you@notme.com\r\nSubject: Hello, world!\r\nFrom: me@notyou.com\r\nContent-Type: text/plain\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nNice to meet you"

  message = {from, to, body}

  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])

  assert_message_delivered message

  Detour.shutdown(detour)
end

Message Format

Messages are expected to be in the format {from, [to], body}. from, to and body are all string values. body will be the raw text your SMTP client sends to Detour. This will typically be an RFC2822 encoded string. If your email library doesn't provide facilities to parse a message body you can use the mail package.

Example

def test "rfc2822 messages" do
  detour = Detour.open()

  from = "me@notyou.com"

  to = ["you@notme.com"]

  message =
    Mail.build()
    |> Mail.put_from(from)
    |> Mail.put_to(to)
    |> Mail.put_subject("Hello, world!")
    |> Mail.put_text("Nice to meet you")

  body = Mail.render(message)

  message = {from, to, body}

  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])

  assert_message_delivered message
end

Assertions

assert_message_delivered/3

Ensure a message has successfully been sent.

test "a message has been delivered" do
  detour = Detour.open()

  from = "me@notyou.com"

  to = ["you@notme.com"]

  body = "To: you@notme.com\r\nSubject: Hello, world!\r\nFrom: me@notyou.com\r\nContent-Type: text/plain\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nNice to meet you"

  message = {from, to, body}

  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])

  assert_message_delivered message
end

refute_message_delivered/3

Ensure a message has not been sent.

test "a message has not been delivered" do
  detour = Detour.open()

  from = "me@notyou.com"

  to = ["you@notme.com"]

  body = "To: you@notme.com\r\nSubject: Hello, world!\r\nFrom: me@notyou.com\r\nContent-Type: text/plain\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nNice to meet you"

  message = {from, to, body}

  :gen_smtp_client.send_blocking({"we@us.com", to, body}, [address: "localhost", port: detour.port])

  refute_message_delivered message
end

assert_number_of_messages_delivered/3

Ensure the expected number of messages has been delivered.

test "the expected number of messages have been delivered" do
  detour = Detour.open()

  from = "me@notyou.com"

  to = ["you@notme.com"]

  body = "To: you@notme.com\r\nSubject: Hello, world!\r\nFrom: me@notyou.com\r\nContent-Type: text/plain\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\nNice to meet you"

  message = {from, to, body}

  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])
  :gen_smtp_client.send_blocking(message, [address: "localhost", port: detour.port])

  assert_number_of_messages_delivered 2
end