How to Use the Unit Test API

Define a Test

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

Each defined test has three arguments available to it's test code.

Parameters

struct	ast_test_info *info
enum	ast_test_command cmd
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.

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
}

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

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

Execute a Test

Execute and generate test results via CLI commands

CLI Examples:

'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 every 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