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/common.bash

@@ -17,6 +17,7 @@
 function __load_bats_helper() {
   load "${REPOSITORY_ROOT}/test/test_helper/bats-support/load"
   load "${REPOSITORY_ROOT}/test/test_helper/bats-assert/load"
+  load "${REPOSITORY_ROOT}/test/helper/sending"
 }
 
 __load_bats_helper
@@ -414,5 +415,58 @@ function _count_files_in_directory_in_container()
   _should_output_number_of_lines "${NUMBER_OF_LINES}"
 }
 
+# Filters a service's logs (under `/var/log/supervisor/<SERVICE>.log`) given
+# a specific string.
+#
+# @param ${1} = service name
+# @param ${2} = string to filter by
+# @param ${3} = container name [OPTIONAL]
+#
+# ## Attention
+#
+# The string given to this function is interpreted by `grep -E`, i.e.
+# as a regular expression. In case you use characters that are special
+# in regular expressions, you need to escape them!
+function _filter_service_log() {
+  local SERVICE=${1:?Service name must be provided}
+  local STRING=${2:?String to match must be provided}
+  local CONTAINER_NAME=$(__handle_container_name "${3:-}")
+
+  _run_in_container grep -E "${STRING}" "/var/log/supervisor/${SERVICE}.log"
+}
+
+# Like `_filter_service_log` but asserts that the string was found.
+#
+# @param ${1} = service name
+# @param ${2} = string to filter by
+# @param ${3} = container name [OPTIONAL]
+#
+# ## Attention
+#
+# The string given to this function is interpreted by `grep -E`, i.e.
+# as a regular expression. In case you use characters that are special
+# in regular expressions, you need to escape them!
+function _service_log_should_contain_string() {
+  local SERVICE=${1:?Service name must be provided}
+  local STRING=${2:?String to match must be provided}
+  local CONTAINER_NAME=$(__handle_container_name "${3:-}")
+
+  _filter_service_log "${SERVICE}" "${STRING}"
+  assert_success
+}
+
+# Filters the mail log for lines that belong to a certain email identified
+# by its ID. You can obtain the ID of an email you want to send by using
+# `_send_mail_and_get_id`.
+#
+# @param ${1} = email ID
+# @param ${2} = container name [OPTIONAL]
+function _print_mail_log_for_id() {
+  local MAIL_ID=${1:?Mail ID must be provided}
+  local CONTAINER_NAME=$(__handle_container_name "${2:-}")
+
+  _run_in_container grep -F "${MAIL_ID}" /var/log/mail.log
+}
+
 # ? << Miscellaneous helper functions
 # ! -------------------------------------------------------------------