snapdir-test

#!/usr/bin/env bash

# # snapdir-test
#
# Test utilities and runner for snapdir commands.
#
# ## Usage:
#
#     # runs all tests for snapdir
#		  snapdir-test
#
#		  # soucing into an existing script
#     . snapdir-test [sourced-test-file]
#
# The snapdir-test script is intended to be sourced by other
# scripts to expose the following functions.
#
# - describe: Describes a group of checks.
# - check: Using a check will instruct the test runner to expect
#          a fail/pass. The test runner with grep for "check " entries
#          to guess how many tests are expected to be implemented.
# - fail: Fail the test, shows the message and runs the tear down.
# - pass: Decrement the number of pending tests as tracked by check.
# - run_tests: Runs the tests.
# - run_tests_without_teardown: Runs the tests without tear down.
#
# A temporary directory is created for each test run and can be accessed
# via _SNAPDIR_TEST_TMP_DIR. This directory is removed when the test
# finishes unless tests are run with `run_tests_without_teardown`.
#
#
# ## Options:
#
#     sourced-test-file  When specified, the test file is sourced and
#                        the thest suite will take the basename of the
#                        file as the name of the test suite.
#
# ## Examples:
#
#
#      # Import test utilities
#      # shellcheck disable=SC1091
#      . "$(dirname "${BASH_SOURCE[0]}")/snapdir-test" "${BASH_SOURCE[0]}"
#
#      test_suite() {
#        local result
#
#        describe "group of checks description"
#
#        check "check a"
#        result=$(echo "a" 2>&1 || true)
#        test "$result" == "a" || fail "expected '${result}' to be a" && pass
#
#      }
#
#      run_tests
#
# LICENSE: MIT Copyright (c) 2022 Bermi Ferrer

set -eEuo pipefail
IFS=$'\n\t'

if [[ ${BASH_VERSION:0:1} -lt "4" ]]; then
	echo "Bash version 4.0 or higher is required. You have: ${BASH_VERSION}" >&2
	exit 1
fi

_snapdir_test_run_unit_tests() {
	set -eEuo pipefail
	local dir
	dir="$(dirname "${BASH_SOURCE[0]}")"
	SECONDS=0
	"$dir/snapdir-manifest" test
	if command -v md5sum >/dev/null 2>&1; then
		"$dir/snapdir-manifest" test --checksum-bin=md5sum
	fi
	if command -v sha256sum >/dev/null 2>&1; then
		"$dir/snapdir-manifest" test --checksum-bin=sha256sum
	fi
	"$dir/snapdir" test

	if test -f "$dir/snapdir-file-store"; then
		"$dir/snapdir-file-store" test
	else
		echo "# skipping snapdir-file-store test, $dir/snapdir-file-store not found" 2>&1
	fi

	echo "# unit tests completed in ${SECONDS} seconds"
}

_snapdir_test_run_integration_tests() {
	set -eEuo pipefail
	local dir
	dir="$(dirname "${BASH_SOURCE[0]}")"
	echo "# integration tests"
	SECONDS=0

	# source .env if it exists
	if test -f "$dir/.env"; then
		set -a
		# shellcheck disable=SC1091 source=./.env
		. "$dir/.env"
		set +a
	fi

	if test -f "$dir/snapdir-b2-store" && [[ ${SNAPDIR_B2_STORE_TEST_BUCKET:-} != "" ]]; then
		"$dir/snapdir-b2-store" test --store "b2://${SNAPDIR_B2_STORE_TEST_BUCKET}"
	else
		echo "# skipping snapdir-b2-store test. Missing SNAPDIR_B2_STORE_TEST_BUCKET or $dir/snapdir-b2-store" >&2
	fi
	if test -f "$dir/snapdir-s3-store" && [[ ${SNAPDIR_S3_STORE_TEST_BUCKET:-} != "" ]]; then
		"$dir/snapdir-s3-store" test --store "s3://${SNAPDIR_S3_STORE_TEST_BUCKET}"
	else
		echo "# skipping snapdir-s3-store test. Missing SNAPDIR_S3_STORE_TEST_BUCKET or $dir/snapdir-s3-store" >&2
	fi
	echo "# integration tests completed in ${SECONDS} seconds"
}

_snapdir_test_run_catalog_tests() {
	set -eEuo pipefail
	local dir
	dir="$(dirname "${BASH_SOURCE[0]}")"
	echo "# integration tests"
	if command -v "sqlite3" >/dev/null; then
		echo "# using sqlite3 --version: $(sqlite3 --version)"
		"$dir"/snapdir-sqlite3-catalog test
		SNAPDIR_CATALOG=sqlite3 "$dir"/snapdir test
	else
		echo "# skipping sqlite3 catalog test, sqlite3 not found locally" >&2
	fi
}

_snapdir_test_utils() {
	# note: using subshell – '(' instead of '{' – to avoid leaking helper functions
	set -eEuo pipefail
	local target_file="${1:?Missing target file}"
	export _TARGET_TEST_FILE="$target_file"
	_SNAPDIR_MODULE_NAME=$(basename "${target_file}")
	export _SNAPDIR_MODULE_NAME

	setup() {
		set -eEuo pipefail

		rm -rf /tmp/"${_SNAPDIR_MODULE_NAME}"_tests*
		_SNAPDIR_TEST_TMP_DIR="$(mktemp -d -t "${_SNAPDIR_MODULE_NAME}"_tests.XXXXXXXXXX)"
		# get the realpath to the tmp dir, on macos it might be prefixed with /private
		_SNAPDIR_TEST_TMP_DIR=$(realpath "$_SNAPDIR_TEST_TMP_DIR")

		umask 077 "$_SNAPDIR_TEST_TMP_DIR"

		export _SNAPDIR_TEST_TMP_DIR
		export _SNAPDIR_CWD="$_SNAPDIR_TEST_TMP_DIR"
		export _SNAPDIR_CACHE_DIR="${_SNAPDIR_TEST_TMP_DIR}/.cache/${_SNAPDIR_MODULE_NAME}"
		export SNAPDIR_CACHE_DIR="${_SNAPDIR_CACHE_DIR}"
		export _SNAPDIR_MANIFEST_CACHE_DIR="${_SNAPDIR_CACHE_DIR}"
		export SNAPDIR_SQLITE3_CATALOG_DB_PATH="${_SNAPDIR_TEST_TMP_DIR}/catalog.db"

		cd "$_SNAPDIR_TEST_TMP_DIR" || return 1

		setup_suite
	}
	_SNAPDIR_TEST_TOTAL_CHECKS=$(grep -c 'check "[^"]*"' "${target_file}" || echo "-1")
	_SNAPDIR_TESTS_PENDING_CHECKS=$_SNAPDIR_TEST_TOTAL_CHECKS
	_SNAPDIR_TEST_SUITE_DESCRIPTION="${_SNAPDIR_MODULE_NAME}"
	_SNAPDIR_TEST_DESCRIPTION=$_SNAPDIR_TEST_SUITE_DESCRIPTION

	if [[ $_SNAPDIR_TESTS_PENDING_CHECKS -lt 0 ]]; then
		echo "not ok 0..0 - no tests found for $_SNAPDIR_TEST_SUITE_DESCRIPTION" >&2
		echo "# could not find 'check \"some test description\"' in '$target_file'." >&2
		exit 1
	fi

	echo "# running tests for ${_SNAPDIR_MODULE_NAME}"
	echo "1..${_SNAPDIR_TEST_TOTAL_CHECKS}"

	_SNAPDIR_TEST_TEARDOWN_COMPLETE=false
	teardown() {
		set -eEuo pipefail
		# return if _SNAPDIR_TEST_TEARDOWN_COMPLETE is already true
		if [[ ${_SNAPDIR_TEST_TEARDOWN_COMPLETE} == true ]]; then
			return 0
		fi
		_SNAPDIR_TEST_TEARDOWN_COMPLETE=true
		teardown_suite
		rm -rf "$_SNAPDIR_TEST_TMP_DIR"
		# exit with not ok if _SNAPDIR_TEST_TOTAL_CHECKS is not zero
		if [[ $_SNAPDIR_TESTS_PENDING_CHECKS -gt 0 ]]; then
			echo "not ok ${_SNAPDIR_TESTS_PENDING_CHECKS}..${_SNAPDIR_TEST_TOTAL_CHECKS} - ${_SNAPDIR_TESTS_PENDING_CHECKS} ${_SNAPDIR_TEST_SUITE_DESCRIPTION} tests pending" >&2
			exit 1
		else
			echo "ok - all $_SNAPDIR_TEST_SUITE_DESCRIPTION tests passed in $SECONDS seconds"
			exit 0
		fi
	}

	describe() {
		set -eEuo pipefail
		_SNAPDIR_TEST_DESCRIPTION="$1"
		_snapdir_test_log_line "describe: $1"
	}

	_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS=false
	_SNAPDIR_TEST_CHECK_NAME="missing check calls on test"
	check() {
		set -eEuo pipefail
		if [[ $_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS == true ]]; then
			fail "calling check \"$1\" while pending pass is not allowed"
		fi
		_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS=true
		_SNAPDIR_TEST_CHECK_NAME="$1"
		_snapdir_test_log_line "check: $1"
	}

	# suites can override setup function to prepare the test environment
	setup_suite() {
		set -eEuo pipefail
	}
	# suites can override teardown function to clean up after tests finished
	teardown_suite() {
		set -eEuo pipefail
	}

	pass() {
		set -eEuo pipefail
		if [[ $_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS == true ]]; then
			_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS=false
			_SNAPDIR_TEST_NUMBER=$((_SNAPDIR_TEST_TOTAL_CHECKS - _SNAPDIR_TESTS_PENDING_CHECKS + 1))
			_SNAPDIR_TESTS_PENDING_CHECKS=$((_SNAPDIR_TESTS_PENDING_CHECKS - 1))
		fi
		echo "ok ${_SNAPDIR_TEST_NUMBER:-0} - ${_SNAPDIR_TEST_DESCRIPTION} / $_SNAPDIR_TEST_CHECK_NAME"
	}

	skip() {
		set -eEuo pipefail
		_SNAPDIR_TEST_CHECK_LOCKED_UNTIL_PASS=false
		_SNAPDIR_TEST_NUMBER=$((_SNAPDIR_TEST_TOTAL_CHECKS - _SNAPDIR_TESTS_PENDING_CHECKS + 1))
		_SNAPDIR_TESTS_PENDING_CHECKS=$((_SNAPDIR_TESTS_PENDING_CHECKS - 1))
		echo "ok ${_SNAPDIR_TEST_NUMBER} - # skip ${_SNAPDIR_TEST_DESCRIPTION} / $_SNAPDIR_TEST_CHECK_NAME"
	}

	fail() {
		set -eEuo pipefail
		_SNAPDIR_TEST_NUMBER=$((_SNAPDIR_TEST_TOTAL_CHECKS - _SNAPDIR_TESTS_PENDING_CHECKS + 1))
		echo "not ok ${_SNAPDIR_TEST_NUMBER} - ${_SNAPDIR_TEST_DESCRIPTION} / $_SNAPDIR_TEST_CHECK_NAME: $*" >&2
		echo "# fail called by: ${_TARGET_TEST_FILE}:$(caller 0 | awk '{print $1}')" >&2
		teardown
		exit 1
	}

	generate_files() {
		set -eEuo pipefail
		local dir=$_SNAPDIR_TEST_TMP_DIR
		mkdir -p "$dir/files/"
		echo "foo" >"$dir/files/foo"
		echo "bar" >"$dir/files/bar"
	}

	generate_nested_files() {
		set -eEuo pipefail
		local dir=$_SNAPDIR_TEST_TMP_DIR
		mkdir -p "$dir/files/a/a1" "$dir/files/b/b1"
		echo "foo" >"$dir/files/a/a1/foo"
		echo "bar" >"$dir/files/b/b1/bar"
	}

	clean_files() {
		rm -rf "$_SNAPDIR_TEST_TMP_DIR/files"
	}

	run_tests() {
		SECONDS=0
		trap teardown EXIT
		setup
		test_suite || {
			teardown
			return 1
		}
		teardown
	}
	run_tests_without_teardown() {
		SECONDS=0
		_SNAPDIR_TEST_TEARDOWN_COMPLETE=true
		setup
		test_suite || {
			echo "Left directory $_SNAPDIR_TEST_TMP_DIR untouched." >&2
			return 1
		}
		echo "Left directory $_SNAPDIR_TEST_TMP_DIR untouched." >&2
	}
}

_snapdir_test_help() {
	set -eEuo pipefail
	sed '/# LICENSE: MIT Copyright (c) 2022 Bermi Ferrer/q; 1,2d' "${BASH_SOURCE[0]}" | sed -E 's|^# ?||g; $d' | more
	exit 0
}

# is any of the arguments -h or --help?
if [[ ${1:-} == -h || ${1:-} == --help ]]; then
	_snapdir_test_help
fi

_snapdir_test_init_log() {
	set -eEuo pipefail
	# Saves the command into the run log for debugging, documentation, etc.
	# _SNAPDIR_RUN_LOG_PATH=$(pwd)/test-log ./snapdir-test
	if [[ ${_SNAPDIR_RUN_LOG_PATH:-} != "" ]] && test -f "$_SNAPDIR_RUN_LOG_PATH"; then
		echo "" >"$_SNAPDIR_RUN_LOG_PATH"
		export _SNAPDIR_RUN_LOG_PATH
	else
		unset _SNAPDIR_RUN_LOG_PATH
	fi
}

_snapdir_test_log_line() {
	set -eEuo pipefail
	local line="$1"
	if [[ ${_SNAPDIR_RUN_LOG_PATH:-} != "" ]]; then
		echo "# $line" >>"$_SNAPDIR_RUN_LOG_PATH"
	fi
}

_snapdir_test_normalize_log() {
	set -eEuo pipefail
	# Cleanup the run log to delete random stuff and make it
	# easier to read and ensure it's valid bash.
	if [[ ${_SNAPDIR_RUN_LOG_PATH:-} != "" ]] && test -f "$_SNAPDIR_RUN_LOG_PATH"; then
		{
			echo "#!/usr/bin/env bash"
			# shellcheck disable=SC2016
			echo '# WARNING, do not edit manually.
# generated by running:
# _SNAPDIR_RUN_LOG_PATH="$(pwd)/docs/tests/tested-commands.sh" ./snapdir-test integration
# We use the results to generate documentation and generative testing.
'
			# shellcheck disable=SC2016
			sed -E '
				s|/tmp/([^.]*).[^/]*(/?)|/tmp/\1\2|g;
				s|([a-f0-9]{3}/[a-f0-9]{3}/[a-f0-9]{3}/[a-f0-9]{55})|"${ID_PATH}"|g;
				s|([a-f0-9]{32,64})|"${ID}"|g;
				s|--([a-z0-9-]*)=|--\1 |g;
				s|--([a-z]*)-file ([^ ]*)|--\1-file "${\U\1_PATH}"|g;
				s#--([a-z]*)-(path|dir) ([^ ]*)#--\1-\2 "${\U\1_\2}"#g;
				s# /tmp/[^ ]*# "${DIR}"#g;
				s#( ([^ ]*)-dir|\..*)$# "${DIR}"#g;
				s# ([^ ]*)-file$# "${FILE_PATH}"#g;
				s#--(store|path) ([^ ]*)#--\1 "${\U\1}"#g;
				s#--(exclude|include) ([^ ]*)#--\1 "${\U\1_PATTERN}"#g;
			'
		} <"${_SNAPDIR_RUN_LOG_PATH}" >"${_SNAPDIR_RUN_LOG_PATH}.tmp"
		mv "${_SNAPDIR_RUN_LOG_PATH}.tmp" "${_SNAPDIR_RUN_LOG_PATH}"
		# ensure the previous steps have not messed up with the shell commands
		if command -v "shellcheck" >/dev/null 2>&1; then
			shellcheck "${_SNAPDIR_RUN_LOG_PATH}"
		fi
		if command -v "shfmt" >/dev/null 2>&1; then
			shfmt -w -s "${_SNAPDIR_RUN_LOG_PATH}"
		fi
	fi
}

if [[ "$(uname -s)" == "Darwin" ]]; then
	_snapdir_test_readlink() {
		set -eEuo pipefail
		echo "$(cd "$(dirname "$1")" || echo "" && pwd)/$(basename "$1")"
	}
	# Disable on macOS, we expect to run this only when
	# running the whole test suite, including integrations
	_snapdir_test_init_log() {
		unset _SNAPDIR_RUN_LOG_PATH
	}
	_snapdir_test_normalize_log() {
		true
	}
else
	_snapdir_test_readlink() {
		set -eEuo pipefail
		readlink -f "$1"
	}
fi

export ENVIRONMENT="test"

# Run if is not sourced
if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
	# does ${1:-} matches -h, --help or help?
	if [[ ${1:-} == -h || ${1:-} == --help || ${1:-} == help ]]; then
		_snapdir_test_help
		exit 0
	fi
	# avoid trashing the user catalog if they are running the test suite
	unset SNAPDIR_CATALOG
	export _SNAPDIR_TEST_BIN_PATH="${_SNAPDIR_TEST_BIN_PATH:-$(_snapdir_test_readlink "${BASH_SOURCE[0]}")}"
	_SNAPDIR_BIN_PATH="$(dirname "${_SNAPDIR_TEST_BIN_PATH}")/snapdir"

	if [[ ${1:-} == integration ]]; then
		_snapdir_test_init_log
	fi

	if ! test -f "$_SNAPDIR_BIN_PATH"; then
		if snapdir -v 2>/dev/null >/dev/null; then
			_SNAPDIR_BIN_PATH="snapdir"
		else
			echo "error: Could not find snapdir binary"
			exit 1
		fi
	fi
	_snapdir_test_run_unit_tests
	_snapdir_test_run_catalog_tests
	# was integration passed?
	if [[ ${1:-} == integration ]]; then
		_snapdir_test_run_integration_tests
		_snapdir_test_normalize_log
	fi
	exit 0
elif [[ ${1:-""} != "" ]]; then
	_snapdir_test_utils "${1}"
fi