aboutsummaryrefslogtreecommitdiffstats
path: root/include/asterisk/test.h
blob: 57e05b47199efdc616e1ed48b031132b5b87cd80 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2009-2010, Digium, Inc.
 *
 * David Vossel <dvossel@digium.com>
 * Russell Bryant <russell@digium.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 * \brief Test Framework API
 *
 * For an overview on how to use the test API, see \ref AstUnitTestAPI
 *
 * \author David Vossel <dvossel@digium.com>
 * \author Russell Bryant <russell@digium.com>
 */

#ifndef _AST_TEST_H_
#define _AST_TEST_H_

#ifdef TEST_FRAMEWORK
#include "asterisk/cli.h"
#include "asterisk/strings.h"
#endif

/*! 

\page AstUnitTestAPI Asterisk Unit Test API

\section UnitTestAPIUsage How to Use the Unit Test API

\subsection DefineTest Define a Test

   Create a callback function for the test using the AST_TEST_DEFINE macro.

   Each defined test has three arguments avaliable to it's test code.
       \param struct ast_test_info *info
       \param enum ast_test_command cmd
       \param struct ast_test *test

   While these arguments are not visible they are passed to every test function
   defined using the AST_TEST_DEFINE macro.

   Below is an example of how to define and write a test function.

\code
   AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function
   {                               \\The the function's body 
      switch (cmd) {
      case TEST_INIT:
          info->name = "sample_test";
          info->category = "main/test/";
          info->summary = "sample test for example purpose";
          info->description = "This demonstrates how to initialize a test function";

          return AST_TEST_NOT_RUN;
      case TEST_EXECUTE:
          break;
      }
      \test code
      .
      .
      .
      if (fail) {                 \\ the following is just some example logic
          ast_test_status_update(test, "an error occured because...");
          res = AST_RESULT_FAIL;
      } else {
          res = AST_RESULT_PASS
      }
      return res;                 \\ result must be of type enum ast_test_result_state
   }
\endcode

      Details of the test execution, especially failure details, should be provided
      by using the ast_test_status_update() function.

\subsection RegisterTest Register a Test 

   Register the test using the AST_TEST_REGISTER macro.

   AST_TEST_REGISTER uses the callback function to retrieve all the information
   pertaining to a test, so the callback function is the only argument required
   for registering a test.

   AST_TEST_REGISTER(sample_test_cb);    \\ Test callback function defined by AST_TEST_DEFINE

   Tests are unregestered by using the AST_TEST_UNREGISTER macro.

   AST_TEST_UNREGISTER(sample_test_cb);  \\ Remove a registered test by callback function

\subsection ExecuteTest Execute a Test

   Execute and generate test results via CLI commands

   CLI Examples:
\code
   'test show registered all'  will show every registered test.
   'test execute all'          will execute every registered test.
   'test show results all'     will show detailed results for ever executed test
   'test generate results xml' will generate a test report in xml format
   'test generate results txt' will generate a test report in txt format
\endcode
*/

/*! Macros used for defining and registering a test */
#ifdef TEST_FRAMEWORK

#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)
#define AST_TEST_REGISTER(cb) ast_test_register(cb)
#define AST_TEST_UNREGISTER(cb) ast_test_unregister(cb)

#else

#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)
#define AST_TEST_REGISTER(cb)
#define AST_TEST_UNREGISTER(cb)
#define ast_test_status_update(a,b,c...)

#endif

enum ast_test_result_state {
	AST_TEST_NOT_RUN,
	AST_TEST_PASS,
	AST_TEST_FAIL,
};

enum ast_test_command {
	TEST_INIT,
	TEST_EXECUTE,
};

/*!
 * \brief An Asterisk unit test.
 *
 * This is an opaque type.
 */
struct ast_test;

/*!
 * \brief Contains all the initialization information required to store a new test definition
 */
struct ast_test_info {
	/*! \brief name of test, unique to category */
	const char *name;
	/*!
	 * \brief test category
	 *
	 * Tests are categorized in a directory tree style hierarchy.  It is expected that
	 * this string have both a leading and trailing forward slash ('/').
	 */
	const char *category;
	/*! \brief optional short summary of test */
	const char *summary;
	/*! \brief optional brief detailed description of test */
	const char *description;
};

#ifdef TEST_FRAMEWORK
/*!
 * \brief Generic test callback function
 *
 * \param error buffer string for failure results
 *
 * \retval AST_TEST_PASS for pass
 * \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);

/*!
 * \brief unregisters a test with the test framework
 *
 * \param test callback function (required)
 *
 * \retval 0 success
 * \retval -1 failure
 */
int ast_test_unregister(ast_test_cb_t *cb);

/*!
 * \brief registers a test with the test framework
 *
 * \param test callback function (required)
 *
 * \retval 0 success
 * \retval -1 failure
 */
int ast_test_register(ast_test_cb_t *cb);

/*!
 * \brief update test's status during testing.
 *
 * \param test currently executing test
 *
 * \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)));

/*!
 * \ref __ast_test_status_update()
 */
#define ast_test_status_update(t, f, ...) __ast_test_status_update(__FILE__, __PRETTY_FUNCTION__, __LINE__, (t), (f), ## __VA_ARGS__)

#endif /* TEST_FRAMEWORK */
#endif /* _AST_TEST_H */