X-Git-Url: http://git.asterisk.org/gitweb/?p=asterisk%2Fasterisk.git;a=blobdiff_plain;f=include%2Fasterisk%2Ftest.h;h=d890b7a3e6de24690ac4ec8c7470bbca44881e14;hp=27ec3cfa8d6105dd1f3001def8cbe2550449579c;hb=e8015cc4603773288525508fc4635993efc654ce;hpb=3b53a9cdb302417e42928225266a763bf826b9be;ds=sidebyside diff --git a/include/asterisk/test.h b/include/asterisk/test.h index 27ec3cf..d890b7a 100644 --- a/include/asterisk/test.h +++ b/include/asterisk/test.h @@ -1,7 +1,7 @@ /* * Asterisk -- An open source telephony toolkit. * - * Copyright (C) 2009-2010, Digium, Inc. + * Copyright (C) 2009-2013, Digium, Inc. * * David Vossel * Russell Bryant @@ -35,7 +35,7 @@ #include "asterisk/strings.h" #endif -/*! +/*! \page AstUnitTestAPI Asterisk Unit Test API @@ -57,7 +57,7 @@ \code AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function - { \\The the function's body + { \\The the function's body switch (cmd) { case TEST_INIT: info->name = "sample_test"; @@ -86,7 +86,7 @@ Details of the test execution, especially failure details, should be provided by using the ast_test_status_update() function. -\subsection RegisterTest Register a Test +\subsection RegisterTest Register a Test Register the test using the AST_TEST_REGISTER macro. @@ -127,45 +127,63 @@ #define AST_TEST_REGISTER(cb) #define AST_TEST_UNREGISTER(cb) #define ast_test_status_update(a,b,c...) +#define ast_test_debug(test, fmt, ...) ast_cli /* Dummy function that should not be called. */ #endif /*! Macros used for the Asterisk Test Suite AMI events */ #ifdef TEST_FRAMEWORK +struct stasis_topic; +struct stasis_message_type; + /*! - * \brief Notifies the test suite of a change in application state + * \since 12 + * \brief Obtain the \ref stasis_topic for \ref ast_test_suite_event_notify + * messages * - * \details - * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters - * The fmt parameter allows additional parameters to be added to the manager event using - * printf style statement formatting. + * \retval A stasis topic + */ +struct stasis_topic *ast_test_suite_topic(void); + +/*! + * \since 12 + * \brief Obtain the \ref stasis_message_type for \ref ast_test_suite_event_notify + * messages * - * \param state The state the application has changed to - * \param fmt The message with format parameters to add to the manager event + * \retval A stasis message type + */ +struct stasis_message_type *ast_test_suite_message_type(void); + +/*! + * \since 12 + * \brief The message payload in a \ref ast_test_suite_message_type + */ +struct ast_test_suite_message_payload; + +/*! + * \since 12 + * \brief Get the JSON for a \ref ast_test_suite_message_payload * - * \returns 0 on success - * \returns any other value on failure + * \retval An \ref ast_json object */ -int __ast_test_suite_event_notify(const char *file, const char *func, int line, - const char *state, const char *fmt, ...) - __attribute__((format(printf, 5, 6))); +struct ast_json *ast_test_suite_get_blob(struct ast_test_suite_message_payload *payload); /*! - * \brief Notifies the test suite of a failed assert on an expression + * \brief Notifies the test suite of a change in application state * * \details - * If the expression provided evaluates to true, no action is taken. If the expression - * evaluates to a false, a TestEvent manager event is raised with a subtype of Assert, notifying - * the test suite that the expression failed to evaluate to true. + * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters + * The fmt parameter allows additional parameters to be added to the manager event using + * printf style statement formatting. * - * \param exp The expression to evaluate + * \param state The state the application has changed to + * \param fmt The message with format parameters to add to the manager event * - * \returns 0 on success - * \returns any other value on failure + * \return Nothing */ -int __ast_test_suite_assert_notify(const char *file, const char *func, int line, - const char *exp); +void __ast_test_suite_event_notify(const char *file, const char *func, int line, const char *state, const char *fmt, ...) + __attribute__((format(printf, 5, 6))); /*! * \ref __ast_test_suite_event_notify() @@ -173,16 +191,9 @@ int __ast_test_suite_assert_notify(const char *file, const char *func, int line, #define ast_test_suite_event_notify(s, f, ...) \ __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__) -/*! - * \ref __ast_test_suite_assert_notify() - */ -#define ast_test_suite_assert(exp) \ - ( (exp) ? (void)0 : __ast_test_suite_assert_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, #exp)) - #else -#define ast_test_suite_event_notify(s, f, ...) (void)0; -#define ast_test_suite_assert(exp) (void)0; +#define ast_test_suite_event_notify(s, f, ...) #endif @@ -233,7 +244,7 @@ struct ast_test_info { * \retval AST_TEST_FAIL for failure */ typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info, - enum ast_test_command cmd, struct ast_test *test); + enum ast_test_command cmd, struct ast_test *test); /*! * \brief unregisters a test with the test framework @@ -256,6 +267,17 @@ int ast_test_unregister(ast_test_cb_t *cb); int ast_test_register(ast_test_cb_t *cb); /*! + * \brief Unit test debug output. + * \since 12.0.0 + * + * \param test Unit test control structure. + * \param fmt printf type format string. + * + * \return Nothing + */ +void ast_test_debug(struct ast_test *test, const char *fmt, ...) __attribute__((format(printf, 2, 3))); + +/*! * \brief update test's status during testing. * * \param test currently executing test @@ -263,14 +285,39 @@ int ast_test_register(ast_test_cb_t *cb); * \retval 0 success * \retval -1 failure */ -int __ast_test_status_update(const char *file, const char *func, int line, - struct ast_test *test, const char *fmt, ...) - __attribute__((format(printf, 5, 6))); +int __ast_test_status_update(const char *file, const char *func, int line, struct ast_test *test, const char *fmt, ...) + __attribute__((format(printf, 5, 6))); /*! * \ref __ast_test_status_update() */ #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__) +/*! + * \brief Check a test condition, failing the test if it's not true. + * + * \since 12.0.0 + * + * This macro evaluates \a condition. If the condition evaluates to true (non-zero), + * nothing happens. If it evaluates to false (zero), then the failure is printed + * using \ref ast_test_status_update, and the current test is ended with AST_TEST_FAIL. + * + * Sadly, the name 'ast_test_assert' was already taken. + * + * Note that since this macro returns from the current test, there must not be any + * cleanup work to be done before returning. Use \ref RAII_VAR for test cleanup. + * + * \param test Currently executing test + * \param condition Boolean condition to check. + */ +#define ast_test_validate(test, condition) \ + do { \ + if (!(condition)) { \ + __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (test), "Condition failed: %s\n", #condition); \ + return AST_TEST_FAIL; \ + } \ + } while(0) + + #endif /* TEST_FRAMEWORK */ #endif /* _AST_TEST_H */