/**
 * \file
 *
 * \brief Test suite core declarations
 *
 * Copyright (c) 2011-2015 Atmel Corporation. All rights reserved.
 *
 * \asf_license_start
 *
 * \page License
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. The name of Atmel may not be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * 4. This software may only be redistributed and used in connection with an
 *    Atmel microcontroller product.
 *
 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * \asf_license_stop
 *
 */
/*
 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
 */
#ifndef TEST_SUITE_H_INCLUDED
#define TEST_SUITE_H_INCLUDED

#include <compiler.h>
#include <parts.h>
#include <stdio.h>

#if XMEGA
#  include <progmem.h>
#endif

/**
 * \defgroup test_suite_group Test Suite Framework
 *
 * This module is the test suite framework, which provides a set of standard
 * functions and macros for defining and running test suites.
 *
 * A test \e suite consists of test \e cases. Each test case consists of a set
 * of functions that are called in a specific order by the framework when the
 * test suite is run. The runtime environment of a test is referred to as the
 * test \e fixture. A setup function can be defined for the purpose of
 * fulfilling preconditions that are needed for the test to run. To free up or
 * reset resources which were used in the test case, a cleanup function can be
 * defined.
 *
 * The following three functions can be defined for each test case:
 * - fixture \e setup
 * - test \e run
 * - fixture \e cleanup
 *
 * The setup and/or cleanup functions may be skipped if they are not needed.
 *
 * A function may report an error or failure by use of the macros \ref test_fail
 * , \ref test_assert_true and \ref test_assert_false. Note that only the first
 * macro allows for the result value to be specified, while the two latter will
 * automatically return TEST_FAIL if the specified condition is false.
 *
 * If any of the functions return a failure/error result, execution of that
 * specific function is ended. However, depending on which function did not
 * pass, execution of the test case may continue:
 * - if the setup does not pass, the rest of the test case is skipped
 * - if the test itself does not pass, cleanup will still be executed
 *
 * The result of the first function in the test case which does not pass
 * determines the end result.
 *
 * Example code for definition of a test suite:
 * \code
	 void setup_1(const struct test_case *test);
	 void run_1(const struct test_case *test);
	 void cleanup_1(const struct test_case *test);

	 void run_2(const struct test_case *test);

	 ...
	 DEFINE_TEST_CASE(test_1,
	 		setup_1,
	 		run_1,
	 		cleanup_1,
	 		"First test");
	 DEFINE_TEST_CASE(test_2,
	 		NULL,
	 		run_2,
	 		NULL,
	 		"Second test");

	 DEFINE_TEST_ARRAY(my_tests) = {
	 	&test_1,
	 	&test_2,
	 };

	 DEFINE_TEST_SUITE(my_suite, my_tests, "Two-test suite");

	 test_suite_run(&my_suite);
	 ...
\endcode
 *
 * Example code for definition of a test case:
 * \code
	 void setup_1(const struct test_case *test)
	 {
	 	void *resource = allocate_test_resource();

	 	if (resource == NULL) {
	 		test_fail(test, TEST_ERROR,
	 			"Could not allocate test resource");
	 	}
	 	test_set_data(resource);
	 }

	 void run_1(const struct test_case *test)
	 {
	 	void *resource = test_get_data();
	 	int8_t test_result;

	      ...
		// TEST CODE
	      ...
	 	test_assert_true(test, test_result > 0,
	 			"Test result is not larger than 0: %i", test_result);
	 	test_assert_false(test, test_result > 2,
	 			"Test result is larger than 2: %i", test_result);
	 }

	 void cleanup_1(const struct test_case *test)
	 {
	 	void *resource = test_get_data();

	 	free_test_resource(resource);
	 }
\endcode
 *
 * @{
 */

/**
 * \brief A test case
 *
 * This structure represents a test case which tests one specific
 * feature or behavior.
 */
struct test_case {
	/**
	 * \brief Set up the environment in which \a test is to be run
	 *
	 * This may involve allocating memory, initializing hardware,
	 * etc. If something goes wrong, this function may call
	 * test_fail(), normally with a negative status code.
	 */
	void (*setup)(const struct test_case *test);
	//! Run the test
	void (*run)(const struct test_case *test);
	/**
	 * \brief Clean up the environment after \a test has been run
	 *
	 * This may free up any memory allocated by setup(), gracefully
	 * shutting down hardware, etc. If something goes wrong, this
	 * function may call test_fail(), normally with a negative
	 * status code.
	 */
	void (*cleanup)(const struct test_case *test);
	//! The name of the test case
	const char *name;
};

/**
 * \brief A test suite
 *
 * A test suite may contain one or more test cases which are to be run
 * in sequence.
 */
struct test_suite {
	//! The number of tests in this suite
	unsigned int nr_tests;
	//! Array of pointers to the test cases
	const struct test_case *const *tests;
	//! The name of the test suite
	const char *name;
};

/**
 * \name Wrappers for printing debug information
 *
 * \note The test suite framework feeds its output to printf. It is left up to
 * the test application to set up the stream.
 */
//@{
#if XMEGA && !defined(__ICCAVR__)
#  define dbg(__fmt_)                                                          \
	printf_P(PROGMEM_STRING(__fmt_))
#  define dbg_info(__fmt_, ...)                                                \
	printf_P(PROGMEM_STRING(__fmt_), __VA_ARGS__)
#  define dbg_error(_x, ...)                                                   \
	printf_P(PROGMEM_STRING(_x), __VA_ARGS__)
#  define dbg_putchar(c)                                                       \
	putc(c, stdout)
#  define dbg_vprintf_pgm(...)                                                 \
	vfprintf_P(stdout, __VA_ARGS__)
#else
#  define dbg(__fmt_)                                                          \
	printf(__fmt_)
#  define dbg_info(__fmt_, ...)                                                \
	printf(__fmt_, __VA_ARGS__)
#  define dbg_error(_x, ...)                                                   \
	printf(_x, __VA_ARGS__)
#  define dbg_putchar(c)                                                       \
	putc(c, stdout)
#  define dbg_vprintf_pgm(...)                                                 \
	vfprintf(stdout, __VA_ARGS__)
#endif
//@}

//! \name Test suite definition macros
//@{
/**
 * \brief Create a test case struct.
 *
 * \param _sym Variable name of the resulting struct
 * \param _setup Function which sets up a test case environment. Can be NULL.
 * \param _run Test function
 * \param _cleanup Function which cleans up what was set up. Can be NULL.
 * \param _name String describing the test case.
 */
#define DEFINE_TEST_CASE(_sym, _setup, _run, _cleanup, _name)                  \
	static const char _test_str_##_sym[] = _name;                          \
	static const struct test_case _sym = {                                 \
		.setup   = _setup,                                             \
		.run     = _run,                                               \
		.cleanup = _cleanup,                                           \
		.name    = _test_str_##_sym,                                   \
	}

/**
 * \brief Create an array of test case pointers.
 *
 * \param _sym Variable name of the resulting array
 */
#define DEFINE_TEST_ARRAY(_sym)                                                \
	const struct test_case *const _sym[]

/**
 * \brief Create a test suite.
 *
 * \param _sym Variable name of the resulting struct
 * \param _test_array Array of test cases, created with DEFINE_TEST_ARRAY()
 * \param _name String describing the test suite.
 */
#define DEFINE_TEST_SUITE(_sym, _test_array, _name)                            \
	static const char _test_str_##_sym[] = _name;                          \
	const struct test_suite _sym = {                                       \
		.nr_tests = ARRAY_LEN(_test_array),                            \
		.tests    = _test_array,                                       \
		.name     = _test_str_##_sym,                                  \
	}
//@}

#ifndef ARRAY_LEN
/**
 * \internal
 * \brief Convenience macro for counting elements in arrays
 */
# define ARRAY_LEN(a) (sizeof(a) / sizeof((a)[0]))
#endif

//! \name Test data access
//@{
extern void *test_priv_data;

/**
 * \brief Set private data pointer for the current test.
 *
 * \param data Pointer to arbitrary run-time data for the test currently
 * being run.
 */
static inline void test_set_data(void *data)
{
	test_priv_data = data;
}

/**
 * \brief Get the private data pointer for the current test.
 *
 * \return Pointer to arbitrary run-time data for the test currently
 * being run, previously registered using test_set_data().
 */
static inline void *test_get_data(void)
{
	return test_priv_data;
}
//@}

//! \name Test case pointer access
//@{

/**
 * \brief Pointer to current test case
 */
extern struct test_case *test_case_ptr;

/**
 * \internal
 * \brief Set pointer to current test.
 */
static inline void test_set_case(const struct test_case *test)
{
	test_case_ptr = (struct test_case *)test;
}

/**
 * \internal
 * \brief Get pointer to current test.
 */
static inline struct test_case *test_get_case(void)
{
	return test_case_ptr;
}
//@}

//@{
//! \name Test result reporting
//@{
/**
 * \brief Status codes returned by test cases and fixtures
 *
 * Note that test cases and especially fixtures may return any of the
 * status codes defined by \ref status_code as well.
 */
enum test_status {
	TEST_ERROR = -1, //!< Test error
	TEST_PASS  = 0,  //!< Test success
	TEST_FAIL  = 1,  //!< Test failure
};

/**
 * \def test_fail(test, result, ...)
 * \brief Fail the test
 *
 * Calling this function will cause the test to terminate with a
 * failure. It will return directly to the test suite core, not to the
 * caller.
 *
 * \param test Test case which failed
 * \param result The result of the test (may not be 0)
 * \param ... printf()-style format string and arguments
 */
#if XMEGA && !defined(__ICCAVR__)
#  define test_priv_fail_ps(test, result, format, ...)                         \
	do {                                                                   \
		static PROGMEM_DECLARE(char, _fmtstr[]) = format "%s";         \
		test_case_fail(test, result, __FILE__, __LINE__, _fmtstr,      \
				__VA_ARGS__);                                  \
	} while (0)

#  define test_fail(test, result, ...)                                         \
	test_priv_fail_ps(test, result, __VA_ARGS__, "")
#else
#  define test_fail(test, result, ...)                                         \
	test_case_fail(test, result, __FILE__, __LINE__, __VA_ARGS__)
#endif

/**
 * \brief Verify that \a condition is true
 *
 * If \a condition is false, fail the test with an error message
 * indicating the condition which failed.
 *
 * \param test The test case currently being run
 * \param condition Expression to be validated
 * \param ... Format string and arguments
 */
#define test_assert_true(test, condition, ...)                                 \
	do {                                                                   \
		if (!(condition)) {                                            \
			test_fail(test, TEST_FAIL, __VA_ARGS__);               \
		}                                                              \
	} while (0)

/**
 * \brief Verify that \a condition is false
 *
 * If \a condition is true, fail the test with an error message
 * indicating the condition which failed.
 *
 * \param test The test case currently being run
 * \param condition Expression to be validated
 * \param ... Format string and arguments
 */
#define test_assert_false(test, condition, ...)                                \
	test_assert_true(test, !(condition), __VA_ARGS__)
//@}

//! \name Test suite interaction
//@{
extern int test_suite_run(const struct test_suite *suite);
//@}

#if defined(__GNUC__)
/* GCC should perform additional printf() argument sanity checks on the
 * function call site to try to ensure arguments are printf() compatible */
__attribute__((format(__printf__, 5, 6)))
#endif
extern void test_case_fail(const struct test_case *test, int result,
		const char *file, unsigned int line,
		const char *fmt, ...);

//! @}

/**
 * \brief Assert() macro definition for unit testing
 *
 * The Assert() macro is set up to use test_assert_true(),
 * as this will only halt execution of the current test, allowing
 * the remaining tests a chance to complete.
 */
#if defined(_ASSERT_ENABLE_) && defined(TEST_SUITE_DEFINE_ASSERT_MACRO)
#  define Assert(expr) \
 	{ \
 		if (test_get_case() != NULL) { \
 			test_assert_true(test_get_case(), expr, \
 					"Assertion failed: %s", #expr); \
 		} else { \
 			if (!(expr)) { \
 				dbg_error("Assertion '%s' failed at %s:%d\r\n", \
 						#expr, __FILE__, __LINE__); \
				while (true); \
 			} \
 		} \
 	}
#endif

#endif /* TEST_SUITE_H_INCLUDED */