test helpers: add functionality for sending emails (#3026)

* add functionality for filtering mail log by ID

This was not planned, but as @polarthene mentioned in
https://github.com/docker-mailserver/docker-mailserver/pull/3033#issuecomment-1407169569
, filtering the mail log by email ID would be (the only) correct
approach for the Rspamd test (to eliminate race conditions).

I asserted the currect state, and came to the conclusion that this might
(or actually is) something we want in more than one place. So I went
ahead and implemented a solution.

The solution for acquiring the ID is a bit slower because it ensures the
mail queue is empty _before_ and _after_ the mail is sent. This is the
tradeoff one has to make if they want to send multiple emails in one
test file and get their IDs.

I hope you like this approach. I will provide another PR that adjusts
our current tests to use these new functions.

* added note about our helper functions in the docs

I think our work for our custom test framework should be noted in the
docs for newcomers to better understand what they should do.

* adjust Rspamd test to use new helpers for sending

* improve filter helpers further

* add sanity check when acquiring mail ID

* re-add `refute_output` to test which should now work well

test/helper/sending.bash

@@ -0,0 +1,68 @@
+#!/bin/bash
+
+# shellcheck disable=SC2034,SC2155
+
+# ? ABOUT: Functions defined here help with sending emails in tests.
+
+# ! ATTENTION: This file is loaded by `common.sh` - do not load it yourself!
+# ! ATTENTION: This file requires helper functions from `common.sh`!
+
+# Sends a mail from localhost (127.0.0.1) via port 25 to the container. To send
+# a custom email, create a file at `test/test-files/email-templates/<TEST FILE>`,
+# and provide `<TEST FILE>` as an argument to this function.
+#
+# @param ${1} = template file (path) name
+# @param ${2} = container name [OPTIONAL]
+#
+# ## Attention
+#
+# This function will just send the email in an "asynchronous" fashion, i.e. it will
+# send the email but it will not make sure the mail queue is empty after the mail
+# has been sent.
+function _send_email() {
+  local TEMPLATE_FILE=${1:?Must provide name of template file}
+  local CONTAINER_NAME=$(__handle_container_name "${2:-}")
+
+  _run_in_container_bash "nc 0.0.0.0 25 < /tmp/docker-mailserver-test/email-templates/${TEMPLATE_FILE}.txt"
+  assert_success
+}
+
+# Like `_send_mail` with two major differences:
+#
+# 1. this function waits for the mail to be processed; there is no asynchronicity
+#    because filtering the logs in a synchronous way is easier and safer!
+# 2. this function prints an ID one can later filter by to check logs
+#
+# No. 2 is especially useful in case you send more than one email in a single
+# test file and need to assert certain log entries for each mail individually.
+#
+# @param ${1} = template file (path) name
+# @param ${2} = container name [OPTIONAL]
+#
+# ## Safety
+#
+# This functions assumes **no concurrent sending of emails to the same container**!
+# If two clients send simultaneously, there is no guarantee the correct ID is
+# chosen. Sending more than one mail at any given point in time with this function
+# is UNDEFINED BEHAVIOR!
+function _send_mail_and_get_id() {
+  local TEMPLATE_FILE=${1:?Must provide name of template file}
+  local CONTAINER_NAME=$(__handle_container_name "${2:-}")
+  local MAIL_ID
+
+  _wait_for_empty_mail_queue_in_container
+  _send_email "${TEMPLATE_FILE}"
+  _wait_for_empty_mail_queue_in_container
+
+  MAIL_ID=$(_exec_in_container tac /var/log/mail.log              \
+    | grep -E -m 1 'postfix/smtpd.*: [A-Z0-9]+: client=localhost' \
+    | grep -E -o '[A-Z0-9]{11}')
+
+  if [[ -z ${MAIL_ID} ]]
+  then
+    echo 'Could not obtain mail ID - aborting!' >&2
+    exit 1
+  fi
+
+  echo "${MAIL_ID}"
+}