docker-mailserver/test/helper/common.bash

419 lines
13 KiB
Bash
Raw Normal View History

#!/bin/bash
# ? ABOUT: Functions defined here aid with common functionality during tests.
# ! ATTENTION: Functions prefixed with `__` are intended for internal use within this file only, not in tests.
# ! -------------------------------------------------------------------
# ? >> Miscellaneous initialization functionality
# shellcheck disable=SC2155
# Load additional BATS libraries for more functionality.
#
# ## Note
#
# This function is internal and should not be used in tests.
function __load_bats_helper() {
load "${REPOSITORY_ROOT}/test/test_helper/bats-support/load"
load "${REPOSITORY_ROOT}/test/test_helper/bats-assert/load"
}
__load_bats_helper
# Properly handle the container name given to tests. This makes the whole
# test suite more robust as we can be sure that the container name is
# properly set. Sometimes, we need to provide an explicit container name;
# this function eases the pain by either providing the explicitly given
# name or `CONTAINER_NAME` if it is set.
#
# @param ${1} = explicit container name [OPTIONAL]
#
# ## Attention
#
# Note that this function checks whether the name given to it starts with
# the prefix `dms-test_`. One must adhere to this naming convention.
#
# ## Panics
#
# If neither an explicit non-empty argument is given nor `CONTAINER_NAME`
# is set.
#
# ## "Calling Convention"
#
# This function should be called the following way:
#
# local SOME_VAR=$(__handle_container_name "${X:-}")
#
# Where `X` is an arbitrary argument of the function you're calling.
#
# ## Note
#
# This function is internal and should not be used in tests.
function __handle_container_name() {
if [[ -n ${1:-} ]] && [[ ${1:-} =~ ^dms-test_ ]]
then
printf '%s' "${1}"
return 0
elif [[ -n ${CONTAINER_NAME+set} ]]
then
printf '%s' "${CONTAINER_NAME}"
return 0
else
2023-01-24 08:21:39 +00:00
echo 'ERROR: (helper/common.sh) Container name was either provided explicitly without the required "dms-test_" prefix, or CONTAINER_NAME is not set for implicit usage' >&2
exit 1
fi
}
# ? << Miscellaneous initialization functionality
# ! -------------------------------------------------------------------
# ? >> Functions to execute commands inside a container
# Execute a command inside a container with an explicit name.
#
# @param ${1} = container name
# @param ... = command to execute
function _exec_in_container_explicit() {
local CONTAINER_NAME=${1:?Container name must be provided when using explicit}
shift 1
docker exec "${CONTAINER_NAME}" "${@}"
}
# Execute a command inside the container with name ${CONTAINER_NAME}.
#
# @param ... = command to execute
function _exec_in_container() {
_exec_in_container_explicit "${CONTAINER_NAME:?Container name must be provided}" "${@}"
}
# Execute a command inside a container with an explicit name. The command is run with
# BATS' `run` so you can check the exit code and use `assert_`.
#
# @param ${1} = container name
# @param ... = command to execute
function _run_in_container_explicit() {
local CONTAINER_NAME=${1:?Container name must be provided when using explicit}
shift 1
run _exec_in_container_explicit "${CONTAINER_NAME}" "${@}"
}
# Execute a command inside the container with name ${CONTAINER_NAME}. The command
# is run with BATS' `run` so you can check the exit code and use `assert_`.
#
# @param ... = command to execute
function _run_in_container() {
_run_in_container_explicit "${CONTAINER_NAME:?Container name must be provided}" "${@}"
}
# Execute a command inside the container with name ${CONTAINER_NAME}. Moreover,
# the command is run by Bash with `/bin/bash -c`.
#
# @param ... = command to execute with Bash
function _exec_in_container_bash() { _exec_in_container /bin/bash -c "${@}" ; }
# Execute a command inside the container with name ${CONTAINER_NAME}. The command
# is run with BATS' `run` so you can check the exit code and use `assert_`. Moreover,
# the command is run by Bash with `/bin/bash -c`.
#
# @param ... = Bash command to execute
function _run_in_container_bash() { _run_in_container /bin/bash -c "${@}" ; }
2023-01-24 08:21:39 +00:00
# Run a command in Bash and filter the output given a regex.
#
# @param ${1} = command to run in Bash
# @param ${2} = regex to filter [OPTIONAL]
#
# ## Attention
#
# The regex is given to `grep -E`, so make sure it is compatible.
#
# ## Note
#
# If no regex is provided, this function will default to one that strips
# empty lines and Bash comments from the output.
function _run_in_container_bash_and_filter_output() {
local COMMAND=${1:?Command must be provided}
local FILTER_REGEX=${2:-^[[:space:]]*$|^ *#}
_run_in_container_bash "${COMMAND} | grep -E -v '${FILTER_REGEX}'"
assert_success
}
# ? << Functions to execute commands inside a container
# ! -------------------------------------------------------------------
# ? >> Functions about executing commands with timeouts
# Repeats a given command inside a container until the timeout is over.
#
# @param ${1} = timeout
# @param ${2} = container name
# @param ... = test command for container
function _repeat_in_container_until_success_or_timeout() {
local TIMEOUT="${1:?Timeout duration must be provided}"
local CONTAINER_NAME="${2:?Container name must be provided}"
shift 2
_repeat_until_success_or_timeout \
--fatal-test "_container_is_running ${CONTAINER_NAME}" \
"${TIMEOUT}" \
_exec_in_container "${@}"
refactor: Parallel Tests - `disabled_clamav_spamassassin`: - Just shuffling the test order around, and removing the restart test at the end which doesn't make sense. - `postscreen`: - Now uses common helper for getting container IP - Does not appear to need the `NET_ADMIN` capability? - Reduced startup time for the 2nd container + additional context about it's relevance. - Test cases are largely the same, but refactored the `nc` alternative that properly waits it's turn. This only needs to run once. Added additional commentary and made into a generic method if needed in other tests. - `fail2ban`: - Use the common container IP helper method. - Postscreen isn't affecting this test, it's not required to do the much slower exchange with the mail server when sending a login failure. - IP being passed into ENV is no longer necessary. - `sleep 5` in the related test cases doesn't seem necessary, can better rely on polling with timeout. - `sleep 10` for `setup.sh` also doesn't appear to be necessary. - `postgrey`: - Reduced POSTGREY_DELAY to 3, which shaves a fair amount of wasted time while still verifying the delay works. - One of the checks in `main.cf` doesn't seem to need to know about the earlier spamhaus portion of the line to work, removed. - Better test case descriptions. - Improved log matching via standard method that better documents the expected triplet under test. - Removed a redundant whitelist file and test that didn't seem to have any relevance. Added a TODO with additional notes about a concern with these tests. - Reduced test time as 8 second timeouts from `-w 8` don't appear to be required, better to poll with grep instead. - Replaced `wc -l` commands with a new method to assert expected line count, better enabling assertions on the actual output. - `undef_spam_subject`: - Split to two separate test cases, and initialize each container in their case instead of `setup_file()`, allowing for using the default `teardown()` method (and slight benefit if running in parallel). - `permit_docker`: - Not a parallel test, but I realized that the repeat helper methods don't necessarily play well with `run` as the command (can cause false positive of what was successful).
2023-01-03 06:11:36 +00:00
}
# Repeats a given command until the timeout is over.
#
# @option --fatal-test <COMMAND EVAL STRING> = additional test whose failure aborts immediately
# @param ${1} = timeout
# @param ... = test to run
function _repeat_until_success_or_timeout() {
local FATAL_FAILURE_TEST_COMMAND
if [[ "${1:-}" == "--fatal-test" ]]
then
FATAL_FAILURE_TEST_COMMAND="${2:?Provided --fatal-test but no command}"
shift 2
fi
local TIMEOUT=${1:?Timeout duration must be provided}
shift 1
if ! [[ "${TIMEOUT}" =~ ^[0-9]+$ ]]
then
echo "First parameter for timeout must be an integer, received \"${TIMEOUT}\""
return 1
fi
local STARTTIME=${SECONDS}
until "${@}"
do
if [[ -n ${FATAL_FAILURE_TEST_COMMAND} ]] && ! eval "${FATAL_FAILURE_TEST_COMMAND}"
then
echo "\`${FATAL_FAILURE_TEST_COMMAND}\` failed, early aborting repeat_until_success of \`${*}\`" >&2
return 1
fi
sleep 1
if [[ $(( SECONDS - STARTTIME )) -gt ${TIMEOUT} ]]
then
echo "Timed out on command: ${*}" >&2
return 1
fi
done
}
# Like `_repeat_until_success_or_timeout` . The command is run with BATS' `run`
# so you can check the exit code and use `assert_`.
#
# @param ${1} = timeout
# @param ... = test command to run
function _run_until_success_or_timeout() {
local TIMEOUT=${1:?Timeout duration must be provided}
shift 1
if [[ ! ${TIMEOUT} =~ ^[0-9]+$ ]]
then
echo "First parameter for timeout must be an integer, received \"${TIMEOUT}\""
return 1
fi
local STARTTIME=${SECONDS}
until run "${@}" && [[ ${status} -eq 0 ]]
do
sleep 1
if (( SECONDS - STARTTIME > TIMEOUT ))
then
echo "Timed out on command: ${*}" >&2
return 1
fi
done
}
# ? << Functions about executing commands with timeouts
# ! -------------------------------------------------------------------
# ? >> Functions to wait until a condition is met
# Wait until a port is ready.
#
# @param ${1} = port
# @param ${2} = container name [OPTIONAL]
function _wait_for_tcp_port_in_container() {
local PORT=${1:?Port number must be provided}
local CONTAINER_NAME=$(__handle_container_name "${2:-}")
_repeat_until_success_or_timeout \
--fatal-test "_container_is_running ${CONTAINER_NAME}" \
"${TEST_TIMEOUT_IN_SECONDS}" \
_exec_in_container_bash "nc -z 0.0.0.0 ${PORT}"
}
# Wait for SMTP port (25) to become ready.
#
# @param ${1} = name of the container [OPTIONAL]
function _wait_for_smtp_port_in_container() {
local CONTAINER_NAME=$(__handle_container_name "${1:-}")
_wait_for_tcp_port_in_container 25
}
# Wait until the SMPT port (25) can respond.
#
# @param ${1} = name of the container [OPTIONAL]
function _wait_for_smtp_port_in_container_to_respond() {
local CONTAINER_NAME=$(__handle_container_name "${1:-}")
local COUNT=0
until [[ $(_exec_in_container timeout 10 /bin/bash -c 'echo QUIT | nc localhost 25') == *'221 2.0.0 Bye'* ]]
do
if [[ ${COUNT} -eq 20 ]]
then
echo "Unable to receive a valid response from 'nc localhost 25' within 20 seconds"
return 1
fi
sleep 1
(( COUNT += 1 ))
done
}
# Checks whether a service is running inside a container (${1}).
#
# @param ${1} = service name
# @param ${2} = container name [OPTIONAL]
function _should_have_service_running_in_container() {
local SERVICE_NAME="${1:?Service name must be provided}"
local CONTAINER_NAME=$(__handle_container_name "${2:-}")
_run_in_container /usr/bin/supervisorctl status "${SERVICE_NAME}"
assert_success
assert_output --partial 'RUNNING'
}
# Wait until a service is running.
#
# @param ${1} = name of the service to wait for
# @param ${2} = container name [OPTIONAL]
function _wait_for_service() {
local SERVICE_NAME="${1:?Service name must be provided}"
local CONTAINER_NAME=$(__handle_container_name "${2:-}")
_repeat_until_success_or_timeout \
--fatal-test "_container_is_running ${CONTAINER_NAME}" \
"${TEST_TIMEOUT_IN_SECONDS}" \
_should_have_service_running_in_container "${SERVICE_NAME}"
}
# An account added to `postfix-accounts.cf` must wait for the `changedetector` service
# to process the update before Dovecot creates the mail account and associated storage dir.
#
# @param ${1} = mail account name
# @param ${2} = container name
function _wait_until_account_maildir_exists() {
local MAIL_ACCOUNT=${1:?Mail account must be provided}
local CONTAINER_NAME=$(__handle_container_name "${2:-}")
local LOCAL_PART="${MAIL_ACCOUNT%@*}"
local DOMAIN_PART="${MAIL_ACCOUNT#*@}"
local MAIL_ACCOUNT_STORAGE_DIR="/var/mail/${DOMAIN_PART}/${LOCAL_PART}"
_repeat_in_container_until_success_or_timeout 60 "${CONTAINER_NAME}" \
/bin/bash -c "[[ -d ${MAIL_ACCOUNT_STORAGE_DIR} ]]"
}
# Wait until the mail queue is empty inside a container (${1}).
#
# @param ${1} = container name [OPTIONAL]
function _wait_for_empty_mail_queue_in_container() {
local CONTAINER_NAME=$(__handle_container_name "${1:-}")
local TIMEOUT=${TEST_TIMEOUT_IN_SECONDS}
# shellcheck disable=SC2016
_repeat_in_container_until_success_or_timeout \
"${TIMEOUT}" \
"${CONTAINER_NAME}" \
/bin/bash -c '[[ $(mailq) == "Mail queue is empty" ]]'
}
tests(refactor): Adjust `mail_changedetector` + change detection helpers (#2997) * tests(refactor): `mail_changedetector.bats` - Leverage DRY methods `supervisorctl tail` is not the most reliably way to get logs for the latest change detection and has been known to be fragile in the past. We can instead read the full log for the service directly with `tac` and `sed` to extract all log content since the last change detection. Common asserts have also been extracted out into separate methods. * tests(chore): Remove sleep and redundant change event Container 1 is still blocked at this point from an existing lock and change event. Make the lock stale immediately and no extra sleep is required when paired with the helper method to wait until the event is processed (which should remove the stale lock). * tests(refactor): Add more DRY methods - Simplify the test case so it's easier to grok. - 2nd test case (blocking) extracts out initial setup into a separate method and merges the later service restart logic which is redundant. - Additional comments for improved context of what is going on / expected. * tests(chore): Revise the change detection helper method - Add explicit counting arg to change detection support. - Extract revised logic into it's own generic helper method. - Utilize this for a separate method that monitors for a change event having started, but not waiting for completion. This allows dropping the 40 sec of remaining `sleep` in `mail_changedetector` test. It was also required due to potentially missing the timing of a change event completing concurrently in a 2nd container that needed to be waited on and then checked. * tests(chore): Migrate to current test conventions - Switch to common container setup helpers - Update container name and change usage to variables instead. - Adopt the new convention of prefix variable for test cases (revised test case descriptions). * tests(chore): Remove legacy change detection This has since been replaced with the new helper watches the `changedetector` service logs directly instead of only detecting a change has occurred via checksum comparison. No tests use this method anymore, it was originally for `tests.bats`. Thus the tests in `test_helper.bats` are being dropped too. The new helper has test coverage in `changedetector` tests. * chore: Lock removal should not incur `sleep 5` afterwards - A new lock should be created by this script after removal. The sleep doesn't help avoid a race condition with lock file creation after removal. - Reduces test time as a bonus. - Added some additional comments to test. * tests(chore): `tls_letsencrypt.bats` leverage improved change detection - No need to wait on the change detection service anymore during container startup. - No need to count change events processed either as waiting a fixed duration is no longer relied on. - This makes the reload count method redundant, dropped. * tests(chore): Convert `setup-cli.bats` to new test conventions This test file was already adapted to the original common setup helpers. - `TEST_NAME` replaced with `CONTAINER_NAME`. - Prefix var added, test case descriptions drop explicit prefix. - No other changes. * tests(chore): Extract out helpers related to change-detection - New helper file for sharing these helpers to tests. - Includes the helpful log method from changedetector tests. - No longer need to maintain duplicate copies of these methods during the test migration. All tests that use them are now importing the separate helper file. - `tls_letsencrypt.bats` has switched to using the log helper. - Generic log count helper is removed from `test_helper/common.bash` as any test that needs it in future can adapt to `helper/common.bash`. * tests(refactor): `tls_letsencrypt.bats` remove `_get_service_logs()` This helper does not seem useful as moving away from `supervisorctl tail` and no other tests had a need for it. * tests(chore): Remove common setup methods from `test_helper/common.bash` No other tests depend on this. Future tests will adopt the revised versions from `helper/setup.bash`. Additionally updates `helper/setup.bash` comments that are no longer applicable to `TEST_TMP_CONFIG` and `CONTAINER_NAME`. * chore: Use `|| true` to simplify setting `EXPECTED_COUNT` correctly
2023-01-16 07:39:46 +00:00
# ? << Functions to wait until a condition is met
# ! -------------------------------------------------------------------
# ? >> Miscellaneous helper functions
# Adds a mail account and waits for the associated files to be created.
#
# @param ${1} = mail account name
# @param ${2} = password [OPTIONAL]
# @param ${3} = container name [OPTIONAL]
function _add_mail_account_then_wait_until_ready() {
local MAIL_ACCOUNT=${1:?Mail account must be provided}
local MAIL_PASS="${2:-password_not_relevant_to_test}"
local CONTAINER_NAME=$(__handle_container_name "${3:-}")
_run_in_container setup email add "${MAIL_ACCOUNT}" "${MAIL_PASS}"
assert_success
_wait_until_account_maildir_exists "${MAIL_ACCOUNT}"
}
# Assert that the number of lines output by a previous command matches the given
# amount (${1}). `lines` is a special BATS variable updated via `run`.
#
# @param ${1} = number of lines that the output should have
function _should_output_number_of_lines() {
assert_equal "${#lines[@]}" "${1:?Number of lines not provided}"
}
# Reloads the postfix service.
#
# @param ${1} = container name [OPTIONAL]
function _reload_postfix() {
local CONTAINER_NAME=$(__handle_container_name "${1:-}")
# Reloading Postfix config after modifying it within 2 seconds will cause Postfix to delay reading `main.cf`:
# WORKAROUND: https://github.com/docker-mailserver/docker-mailserver/pull/2998
_exec_in_container touch -d '2 seconds ago' /etc/postfix/main.cf
_exec_in_container postfix reload
}
# Get the IP of the container (${1}).
#
# @param ${1} = container name [OPTIONAL]
function _get_container_ip() {
local TARGET_CONTAINER_NAME=$(__handle_container_name "${1:-}")
docker inspect --format '{{ .NetworkSettings.IPAddress }}' "${TARGET_CONTAINER_NAME}"
}
# Check if a container is running.
#
# @param ${1} = container name [OPTIONAL]
function _container_is_running() {
local TARGET_CONTAINER_NAME=$(__handle_container_name "${1:-}")
[[ $(docker inspect -f '{{.State.Running}}' "${TARGET_CONTAINER_NAME}") == 'true' ]]
}
# Checks if the directory exists and then how many files it contains at the top-level.
#
# @param ${1} = directory
# @param ${2} = number of files that should be in ${1}
# @param ${3} = container name [OPTIONAL]
function _count_files_in_directory_in_container()
{
local DIRECTORY=${1:?No directory provided}
local NUMBER_OF_LINES=${2:?No line count provided}
local CONTAINER_NAME=$(__handle_container_name "${3:-}")
_run_in_container_bash "[[ -d ${DIRECTORY} ]]"
assert_success
_run_in_container_bash "find ${DIRECTORY} -maxdepth 1 -type f -printf 'x\n'"
assert_success
_should_output_number_of_lines "${NUMBER_OF_LINES}"
}
tests: Extract some test cases out from `tests.bats` (#2980) While working on tests, I noticed that some of the configs being mounted were adding a few seconds to the start-up time of each container. Notably `postfix-*` and `dovecot.conf` config files, which have been extracted out into their own tests with those files moved into a separate config folder. `tests.bats` has been adapted to the common setup helper, and removed ENV no longer required to run those tests. Future PRs will extract out more tests. Review may be easier via individual commit diffs and their associated commit messages describing relevant changes. <details> <summary>Commit message history for reference</summary> ```markdown tests(chore): `tests.bats` - Remove redundant config === - ONEDIR volume support no longer relevant, this should have been dropped. - ClamAV ENV no longer relevant as related tests have been extracted already. - Same with the some of the SpamAssassin ENV config. - `VIRUSMAILS_DELETE_DELAY` is tested in the file, but doesn't use this ENV at all? (runs a separate instance to test the ENV instead) - Hostname updated in preparation for migrating to new test helpers. Relevant test lines referencing the hostname have likewise been updated. ``` ```markdown tests(chore): `tests.bats` - Convert to common setup === ENV remains the same, but required adding `ENABLE_AMAVIS=1` to bring that back, while the following became redundant as they're now defaulting to explicitly disabled in the helper method: - `ENABLE_CLAMAV=0` - `LOG_LEVEL=debug` - `ENABLE_UPDATE_CHECK=0` - `--hostname` + `--tty` + standard `--volume` lines - `-e` option expanded to long-name `--env`, and all `\` dropped as no longer necessary. `wait_for_finished_setup_in_container` is now redundant thanks to `common_container_setup`. ``` ```markdown tests(refactor): `tests.bats` - Extract out Dovecot Sieve tests === Sieve test files relocated into `test/config/dovecot-sieve/` for better isolation. `dovecot.sieve` was not using the `reject` import, and we should not encourage it? (docs still do): https://support.tigertech.net/sieve#the-sieve-reject-jmp ``` ```markdown tests: `tests.bats` - Extract out `checking smtp` tests === Migrated to the standard template and copied over the original test cases with `_run_in_container` adjustment only. Identified minimum required ENV along with which mail is required for each test case. ``` ```markdown tests(refactor): `smtp-delivery.bats` === - Disabled `ENABLE_SRS=1`, not necessary for these tests. - Added a SpamAssassin related test (X-SPAM headers) which requires `SA_TAG` to properly pass (or `ENABLE_SRS=1` to deliver into inbox). - Many lines with double quotes changed to single quote wrapping, and moving out `grep` filters into `assert_output --partial` lines instead. - Instead of `wc -l` making failures less helpful, switch to the helper method `_should_output_number_of_lines` - x2 `assert_output` with different EOF style of usage was not actually failing on tests when it should. Changed to assert partial output of each expected line, and count the number of lines instead. - Added additional comments related to the test cases with a `TODO` note about `SPAMASSASSIN_SPAM_TO_INBOX=1`. - Revised test case names, including using the common prefix var. - `tests.bats` no longer needs to send all these emails, no other test cases require them. This affects a test checking a `/mail` folder exists which has been corrected, and a quotas test case adjusted to expect an empty quota size output. ``` ```markdown tests: `tests.bats` - Extract out test cases for config overrides === Slight improvement by additionally matching `postconf` output to verify the setting is properly applied. ``` ```markdown tests: `tests.bats` - Extract out Amavis SpamAssassin test case === Removes the need for SpamAssassin ENV in `tests.bats`. ``` </details>
2023-01-06 22:36:20 +00:00
# ? << Miscellaneous helper functions
# ! -------------------------------------------------------------------