Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


test.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009-2010, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  * Russell Bryant <russell@digium.com>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19 
20 /*!
21  * \file
22  * \brief Test Framework API
23  *
24  * For an overview on how to use the test API, see \ref AstUnitTestAPI
25  *
26  * \author David Vossel <dvossel@digium.com>
27  * \author Russell Bryant <russell@digium.com>
28  */
29 
30 #ifndef _AST_TEST_H_
31 #define _AST_TEST_H_
32 
33 #ifdef TEST_FRAMEWORK
34 #include "asterisk/cli.h"
35 #include "asterisk/strings.h"
36 #endif
37 
38 /*!
39 
40 \page AstUnitTestAPI Asterisk Unit Test API
41 
42 \section UnitTestAPIUsage How to Use the Unit Test API
43 
44 \subsection DefineTest Define a Test
45 
46  Create a callback function for the test using the AST_TEST_DEFINE macro.
47 
48  Each defined test has three arguments available to it's test code.
49  \param struct ast_test_info *info
50  \param enum ast_test_command cmd
51  \param struct ast_test *test
52 
53  While these arguments are not visible they are passed to every test function
54  defined using the AST_TEST_DEFINE macro.
55 
56  Below is an example of how to define and write a test function.
57 
58 \code
59  AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function
60  { \\The the function's body
61  switch (cmd) {
62  case TEST_INIT:
63  info->name = "sample_test";
64  info->category = "main/test/";
65  info->summary = "sample test for example purpose";
66  info->description = "This demonstrates how to initialize a test function";
67 
68  return AST_TEST_NOT_RUN;
69  case TEST_EXECUTE:
70  break;
71  }
72  \test code
73  .
74  .
75  .
76  if (fail) { \\ the following is just some example logic
77  ast_test_status_update(test, "an error occured because...");
78  res = AST_RESULT_FAIL;
79  } else {
80  res = AST_RESULT_PASS
81  }
82  return res; \\ result must be of type enum ast_test_result_state
83  }
84 \endcode
85 
86  Details of the test execution, especially failure details, should be provided
87  by using the ast_test_status_update() function.
88 
89 \subsection RegisterTest Register a Test
90 
91  Register the test using the AST_TEST_REGISTER macro.
92 
93  AST_TEST_REGISTER uses the callback function to retrieve all the information
94  pertaining to a test, so the callback function is the only argument required
95  for registering a test.
96 
97  AST_TEST_REGISTER(sample_test_cb); \\ Test callback function defined by AST_TEST_DEFINE
98 
99  Tests are unregestered by using the AST_TEST_UNREGISTER macro.
100 
101  AST_TEST_UNREGISTER(sample_test_cb); \\ Remove a registered test by callback function
102 
103 \subsection ExecuteTest Execute a Test
104 
105  Execute and generate test results via CLI commands
106 
107  CLI Examples:
108 \code
109  'test show registered all' will show every registered test.
110  'test execute all' will execute every registered test.
111  'test show results all' will show detailed results for ever executed test
112  'test generate results xml' will generate a test report in xml format
113  'test generate results txt' will generate a test report in txt format
114 \endcode
115 */
116 
117 /*! Macros used for defining and registering a test */
118 #ifdef TEST_FRAMEWORK
119 
120 #define AST_TEST_DEFINE(hdr) static enum ast_test_result_state hdr(struct ast_test_info *info, enum ast_test_command cmd, struct ast_test *test)
121 #define AST_TEST_REGISTER(cb) ast_test_register(cb)
122 #define AST_TEST_UNREGISTER(cb) ast_test_unregister(cb)
123 
124 #else
125 
126 #define AST_TEST_DEFINE(hdr) static enum ast_test_result_state attribute_unused hdr(struct ast_test_info *info, enum ast_test_command cmd, struct ast_test *test)
127 #define AST_TEST_REGISTER(cb)
128 #define AST_TEST_UNREGISTER(cb)
129 #define ast_test_status_update(a,b,c...)
130 
131 #endif
132 
133 /*! Macros used for the Asterisk Test Suite AMI events */
134 #ifdef TEST_FRAMEWORK
135 
136 /*!
137  * \brief Notifies the test suite of a change in application state
138  *
139  * \details
140  * Raises a TestEvent manager event with a subtype of StateChange. Additional parameters
141  * The fmt parameter allows additional parameters to be added to the manager event using
142  * printf style statement formatting.
143  *
144  * \param state The state the application has changed to
145  * \param fmt The message with format parameters to add to the manager event
146  *
147  * \returns 0 on success
148  * \returns any other value on failure
149  */
150 int __ast_test_suite_event_notify(const char *file, const char *func, int line,
151  const char *state, const char *fmt, ...)
152  __attribute__((format(printf, 5, 6)));
153 
154 /*!
155  * \brief Notifies the test suite of a failed assert on an expression
156  *
157  * \details
158  * If the expression provided evaluates to true, no action is taken. If the expression
159  * evaluates to a false, a TestEvent manager event is raised with a subtype of Assert, notifying
160  * the test suite that the expression failed to evaluate to true.
161  *
162  * \param exp The expression to evaluate
163  *
164  * \returns 0 on success
165  * \returns any other value on failure
166  */
167 int __ast_test_suite_assert_notify(const char *file, const char *func, int line,
168  const char *exp);
169 
170 /*!
171  * \ref __ast_test_suite_event_notify()
172  */
173 #define ast_test_suite_event_notify(s, f, ...) \
174  __ast_test_suite_event_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, (s), (f), ## __VA_ARGS__)
175 
176 /*!
177  * \ref __ast_test_suite_assert_notify()
178  */
179 #define ast_test_suite_assert(exp) \
180  ( (exp) ? (void)0 : __ast_test_suite_assert_notify(__FILE__, __PRETTY_FUNCTION__, __LINE__, #exp))
181 
182 #else
183 
184 #define ast_test_suite_event_notify(s, f, ...) (void)0;
185 #define ast_test_suite_assert(exp) (void)0;
186 
187 #endif
188 
193 };
194 
198 };
199 
200 /*!
201  * \brief An Asterisk unit test.
202  *
203  * This is an opaque type.
204  */
205 struct ast_test;
206 
207 /*!
208  * \brief Contains all the initialization information required to store a new test definition
209  */
211  /*! \brief name of test, unique to category */
212  const char *name;
213  /*!
214  * \brief test category
215  *
216  * Tests are categorized in a directory tree style hierarchy. It is expected that
217  * this string have both a leading and trailing forward slash ('/').
218  */
219  const char *category;
220  /*! \brief optional short summary of test */
221  const char *summary;
222  /*! \brief optional brief detailed description of test */
223  const char *description;
224 };
225 
226 #ifdef TEST_FRAMEWORK
227 /*!
228  * \brief Generic test callback function
229  *
230  * \param error buffer string for failure results
231  *
232  * \retval AST_TEST_PASS for pass
233  * \retval AST_TEST_FAIL for failure
234  */
235 typedef enum ast_test_result_state (ast_test_cb_t)(struct ast_test_info *info,
236  enum ast_test_command cmd, struct ast_test *test);
237 
238 /*!
239  * \brief unregisters a test with the test framework
240  *
241  * \param test callback function (required)
242  *
243  * \retval 0 success
244  * \retval -1 failure
245  */
246 int ast_test_unregister(ast_test_cb_t *cb);
247 
248 /*!
249  * \brief registers a test with the test framework
250  *
251  * \param test callback function (required)
252  *
253  * \retval 0 success
254  * \retval -1 failure
255  */
256 int ast_test_register(ast_test_cb_t *cb);
257 
258 /*!
259  * \brief update test's status during testing.
260  *
261  * \param test currently executing test
262  *
263  * \retval 0 success
264  * \retval -1 failure
265  */
266 int __ast_test_status_update(const char *file, const char *func, int line,
267  struct ast_test *test, const char *fmt, ...)
268  __attribute__((format(printf, 5, 6)));
269 
270 /*!
271  * \ref __ast_test_status_update()
272  */
273 #define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)
274 
275 #endif /* TEST_FRAMEWORK */
276 #endif /* _AST_TEST_H */
Contains all the initialization information required to store a new test definition.
Definition: test.h:210
const char * summary
optional short summary of test
Definition: test.h:221
String manipulation functions.
const char * description
optional brief detailed description of test
Definition: test.h:223
const char * name
name of test, unique to category
Definition: test.h:212
ast_test_command
Definition: test.h:195
const char * category
test category
Definition: test.h:219
Standard Command Line Interface.
static snd_pcm_format_t format
Definition: chan_alsa.c:93
ast_test_result_state
Definition: test.h:189