Email

Check the emails your services send: who they went to and from, their subject, their text, their HTML, their attachments and their headers.

Your service sends its mail as it always does, by SMTP, to the mail server of your test environment: smtp4dev, Mailpit or any other. Axx reads the mailbox that catches it. Register it once, usually in the Background; every mail step of the scenario uses it:

Given the shops mailbox with the following properties:
  | url | http://localhost:8025 |

• Any mailbox, a real one included, is read over POP3 (pop3://, pop3s://) or IMAP (imap://, imaps://): smtp4dev, GreenMail, Inbucket, Dovecot, a staging inbox.
• Mailpit is read through its API (http:// or https://).
• A check only looks at the emails that arrived since its scenario started, and waits for one that meets it: 10 seconds, or within {duration}. For a run, Axx reads each mailbox the checks name from when the services are up, and never deletes or marks what it reads.
• Scenarios share the mailbox, so each checks its own mail, by a recipient or a subject unique to it.
• Refused mail is a stub of the mail server’s, as WireMock’s mappings are for HTTP: smtp4dev refuses the recipients its RecipientValidationExpression says to, with the code it gives, and a scenario that uses such a recipient sees how your service copes.
• Mail sent through a provider’s HTTP API (SendGrid, SES, Mailgun, Postmark) is not in a mailbox: mock the provider with WireMock and check the request with the mock pack.
• Secrets stay secret: the password, and ${env:..} values, are masked in logs and failures.

Add it to a project with axx pack add mail.

Steps

mail.mailbox

Given the {word} mailbox with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register the mailbox the steps read.

• The first mailbox registered is the one the scenario’s mail steps use.
• Values expand ${env:..} and ${sys:..}; the password is masked.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
url	where the mailbox is: Mailpit’s address, http://localhost:8025, or pop3://, pop3s://, imap:// or imaps:// and the mail server’s host	required
username	the user Axx signs in as: for POP3 and IMAP, and for a Mailpit behind a password
password	its password, like ${env:MAILBOX_PASSWORD}
folder	the IMAP folder	INBOX

Example:

Given the shops mailbox with the following properties:
  | url | http://localhost:8025 |
Given the shops mailbox with the following properties:
  | url      | imaps://imap.parcels.example   |
  | username | shop-notifications@parcels.example |
  | password | ${env:MAILBOX_PASSWORD}        |

Since 0.1.5.

mail.received

Then [[within {duration} ]]the {word} mailbox has an email where:
  | field | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the mailbox has an email with those values, arrived since the scenario started.

• The check waits for it: 10 seconds, or within {duration}.
• Addresses compare without regard to case; text and html are text the body contains, with runs of spaces and line breaks as one space.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Field	Takes
to	an address the email went to
cc	an address it was copied to
from	the address it came from
subject	its subject, all of it
text	text its plain-text body contains
html	text its HTML body contains, tags and all
attachment	the file name of an attachment
header <name>	a header’s value: its name after header

Variants, the parts in [[...]] said or left out:

• the {word} mailbox has an email where:
• within {duration} the {word} mailbox has an email where:

Example:

Then within 10s the shops mailbox has an email where:
  | to         | orders@hawthorn-home.example |
  | subject    | Parcel PX-MAIL-9701 registered |
  | attachment | PX-MAIL-9701-label.zpl       |

Since 0.1.5.