Group PJ_UNITTEST
- group PJ_UNITTEST
Defines
-
PJ_TEST_NON_ZERO(expr, err_reason, err_action)
Check that an expression is non-zero. If the check fails, informative error message will be displayed, and the code in err_action will be executed.
- Parameters:
expr – The expression to check
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_BINARY_OP(expr0, op, expr1, err_reason, err_action)
Generic check for binary operation. If the check fails, informative error message will be displayed, and the code in err_action will be executed.
- Parameters:
expr0 – First expression
op – The operator
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_STR_OP(str_op, ps0, ps1, res_op, res, err_reason, err_action)
Generic check for (PJ) string comparison operation. If the check fails, informative error message will be displayed, and the code in err_action will be executed.
- Parameters:
str_op – The string operation (e.g. pj_strcmp)
ps0 – Pointer to first string
ps1 – Pointer to second string
res_op – Operator to compare result (e.g. ==)
res – Expected return value of str_op(&s0, &s1)
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_SUCCESS(expr, err_reason, err_action)
Check that an expression is PJ_SUCCESS. If the check fails, error message explaining the error code will be displayed, and the code in err_action will be executed.
- Parameters:
expr – The expression to check
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_TRUE(expr, err_reason, err_action)
Alias for PJ_TEST_NON_ZERO()
-
PJ_TEST_NOT_NULL(expr, err_reason, err_action)
Alias for PJ_TEST_NON_ZERO()
-
PJ_TEST_EQ(expr0, expr1, err_reason, err_action)
Check that expr0 equals expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_NEQ(expr0, expr1, err_reason, err_action)
Check that expr0 does not equal expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_LT(expr0, expr1, err_reason, err_action)
Check that expr0 is less than expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_LTE(expr0, expr1, err_reason, err_action)
Check that expr0 is less than or equal to expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_GT(expr0, expr1, err_reason, err_action)
Check that expr0 is greater than expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_GTE(expr0, expr1, err_reason, err_action)
Check that expr0 is greater than or equal to expr1. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
expr0 – First expression
expr1 – Second expression
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_STRCMP(ps0, ps1, res_op, exp_result, err_reason, err_action)
Check string comparison result. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
ps0 – Pointer to first string
ps1 – Pointer to second string
res_op – Operator to compare result (e.g. ==, <, >)
exp_result – Expected result (e.g. zero for equal string)
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_STRICMP(ps0, ps1, res_op, exp_result, err_reason, err_action)
Check case-insensitive string comparison result. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
ps0 – Pointer to first string
ps1 – Pointer to second string
res_op – Operator to compare result (e.g. ==, <, >)
exp_result – Expected result (e.g. zero for equal)
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_STREQ(ps0, ps1, err_reason, err_action)
Check that two strings are equal. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
ps0 – Pointer to first string
ps1 – Pointer to second string
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_STRNEQ(ps0, ps1, err_reason, err_action)
Check that two strings are not equal. If the check fails, informative error message will be displayed and the code in err_action will be executed.
- Parameters:
ps0 – Pointer to first string
ps1 – Pointer to second string
err_reason – NULL or extra text to display when the check fails
err_action – Action to perform when the check fails
-
PJ_TEST_THREAD_WAIT_MSEC
Macro to control how long worker thread should sleep waiting for next ready test.
Enums
-
enum pj_test_case_flag
Bitwise constants that can be used in test case flags (see pj_test_case_init()).
Values:
-
enumerator PJ_TEST_EXCLUSIVE
Do not allow other test cases to run while this test case is running. Note this only makes sense for test runners that support worker threads. Basic runner will always run test cases serially.
-
enumerator PJ_TEST_FUNC_NO_ARG
Specify that the test function must be called without argument. This is mainly for backward compatibility with existing PJ test functions which take no argument.
-
enumerator PJ_TEST_LOG_NO_CACHE
Write the original log at the time it is called instead of pooling the logs to be printed after all tests finish.
-
enumerator PJ_TEST_KEEP_FIRST
Keep this test case in front of the list when shuffling the test cases.
-
enumerator PJ_TEST_KEEP_LAST
Keep this test case in last in the list when shuffling the test cases.
-
enumerator PJ_TEST_EXCLUSIVE
-
enum pj_test_select_tests
Option to select tests (e.g. in pj_test_dump_log_messages())
Values:
-
enumerator PJ_TEST_NO_TEST
Select no test
-
enumerator PJ_TEST_FAILED_TESTS
Select only failed tests
-
enumerator PJ_TEST_SUCCESSFUL_TESTS
Select only successful tests
-
enumerator PJ_TEST_ALL_TESTS
Select all tests
-
enumerator PJ_TEST_NO_HEADER_FOOTER
No header/footer separator
-
enumerator PJ_TEST_NO_TEST
Functions
-
void pj_test_suite_init(pj_test_suite *suite)
Initialize test suite.
- Parameters:
suite – The test suite
-
void pj_test_case_param_default(pj_test_case_param *prm)
Initialize pj_test_case_param with default values. If app only uses default values in params, alternatively it doesn’t need to use param at all and just specify NULL in pj_test_case_init().
- Parameters:
prm – The parameter.
-
void pj_test_case_init(pj_test_case *tc, const char *obj_name, unsigned flags, int (*test_func)(void*), void *arg, void *fifobuf_buf, unsigned buf_size, const pj_test_case_param *prm)
Initialize test case.
- Parameters:
tc – The test case
obj_name – Name that will appear as test name/title
flags – Bitwise of pj_test_case_flag to control threading, function calling, logging, etc.
test_func – The test function to be called to perform the test. By convention, the function must return zero for the test to be considered successful, non-zero on failure, and MUST NEVER return PJ_EPENDING, otherwise the return value will be silently changed to -12345.
arg – Argument to give to the test function
fifobuf_buf – Buffer for saving the logs, if required.
buf_size – Size of the buffer for saving the logs.
prm – Optional additional settings for the test case or NULL
-
void pj_test_suite_add_case(pj_test_suite *suite, pj_test_case *tc)
Add test case to test suite. A test case can only be added to one suite.
- Parameters:
suite – The test suite
tc – The test case
-
void pj_test_suite_shuffle(pj_test_suite *suite, int seed)
Shuffle the tests.
- Parameters:
suite – The test suite
seed – Optional random seed to use, only if the value is greater than or equal to zero. It is recommended to set this value to make the test reproducible.
-
void pj_test_runner_param_default(pj_test_runner_param *prm)
Initialize parameters with reasonable default values. This usually means using one worker thread if threading is enabled, and zero worker thread (i.e. only use the main thread) otherwise.
- Parameters:
prm – Test runner parameter
-
void pj_test_init_basic_runner(pj_test_runner *runner, const pj_test_runner_param *prm)
Initialize a basic test runner. A basic runner can be declared in the stack and it does not require pool nor multithreading.
- Parameters:
runner – The runner.
prm – Runner params, or NULL to accept default values.
-
pj_status_t pj_test_create_text_runner(pj_pool_t *pool, const pj_test_runner_param *prm, pj_test_runner **p_runner)
Create console based test runner.
- Parameters:
pool – The pool to use to allocate memory
prm – Test runner parameter, or NULL for default values.
p_runner – Pointer to receive the text runner
- Returns:
PJ_SUCCESS or the appropriate error code.
-
void pj_test_run(pj_test_runner *runner, pj_test_suite *suite)
Run test suite with the specified runner.
- Parameters:
runner – The test runner
suite – The test suite
-
pj_bool_t pj_test_is_under_test(void)
This is a crude test to detect if thread is currently running under a test. It is mainly used to prevent nested unit testing.
- Returns:
PJ_TRUE if we are currently running in the context of a test case being run.
-
void pj_test_get_stat(const pj_test_suite *suite, pj_test_stat *stat)
Get the test statistics after the run completes. The test suite and test cases instances must be kept alive in order to get and access the statistics or log messages.
- Parameters:
suite – The test suite
stat – The test statistics result.
-
void pj_test_display_stat(const pj_test_stat *stat, const char *test_name, const char *log_sender)
Display statistics to the log.
- Parameters:
stat – The test statistics result.
-
void pj_test_display_log_messages(const pj_test_suite *suite, unsigned flags)
Display previously saved log messages in the test cases to logging. Note that log messages emited during test case’s run are only saved when fifobuf of the test case is configured with a suitable buffer. Also note that the test suite and test cases instances must be kept alive in order to get and access the statistics or log messages.
- Parameters:
suite – The test suite
flags – Select which test logs to display by choosing from pj_test_select_tests.
-
void pj_test_runner_destroy(pj_test_runner *runner)
Destroy the runner. Runner may be destroyed right after it is run, but the test suite and test cases instances must be kept alive in order to get the statistics or log messages.
- Parameters:
runner – The test runner.
-
struct pj_test_log_item
- #include <unittest.h>
An internal structure to represent one logging item that is saved inside pj_test_case.
-
struct pj_test_case_param
- #include <unittest.h>
Additional parameters for creating test case. Use pj_test_case_param_default() to initialize this structure.
Public Members
-
int log_level
Custom log level for this test case, to filter out logs that are more detail than this level. Default is 6, meaning it will accept all log levels.
-
int log_level
-
struct pj_test_case
- #include <unittest.h>
A test case is unit-test object to perform test against a user defined function.
Public Members
-
char obj_name[PJ_MAX_OBJ_NAME]
Test name
-
int (*test_func)(void*)
The test function to be called to perform the test. By convention, the function must return zero for the test to be considered successful, non-zero on failure, and MUST NEVER return PJ_EPENDING, otherwise the return value will be silently changed to -12345.
-
void *arg
Argument to be passed to the test function
-
unsigned flags
Flags, combination of pj_test_flag constants
-
pj_fifobuf_t fb
Circular buffer for logging
-
pj_test_case_param prm
Parameters
-
int result
The return value of the test function. Zero indicates success. Initially the value is PJ_EPENDING before the test is run.
-
pj_test_log_item logs
List of saved logging messages
-
pj_test_runner *runner
Pointer to the runner running this test case
-
pj_timestamp start_time
Start time
-
pj_timestamp end_time
End time
-
char obj_name[PJ_MAX_OBJ_NAME]
-
struct pj_test_suite
- #include <unittest.h>
Test suite is a collection of test cases.
Public Members
-
pj_test_case tests
List of tests
-
pj_timestamp start_time
Start time
-
pj_timestamp end_time
End time
-
pj_test_case tests
-
struct pj_test_stat
- #include <unittest.h>
Test statistics. Collect the statistics after the test runner finishes with pj_test_get_stat().
Public Members
-
pj_time_val duration
Total duration
-
unsigned ntests
Total number of tests in the test suite
-
unsigned nruns
Number of tests run
-
unsigned nfailed
Number of failed tests
-
const char *failed_names[32]
Array of failed test names. Be careful that the number elements are fixed, hence it may not be able to store all failed test names (in case nfailed is more than the capacity, not all failed test names will be stored, hence be careful in the loop).
-
pj_time_val duration
-
struct pj_test_runner_param
- #include <unittest.h>
Test runner parameters. Use pj_test_runner_param_default() to initialize this structure.
Public Members
-
unsigned nthreads
Number of worker threads. Set to zero to disable parallel testings. Only applicable to test text runner. Default is 1 if multithreading is available.
-
unsigned verbosity
0: only display test name and result after test completion (default) 1: display test name test when starting and finishing a test
-
unsigned nthreads
-
struct pj_test_runner
- #include <unittest.h>
This structure represents a test runner. Currently there are two types of test runners, the basic runner and text runner. The basic runner is the simplest test runner that can be used without pool and threads, and can be created with pj_test_init_basic_runner(). The text runner is more powerful since it supports worker threads, and it is mostly suitable for console based environments. It is created with pj_test_create_text_runner().
Forward declaration of test runner
Public Members
-
pj_test_runner_param prm
Parameters
-
pj_test_suite *suite
The test suite being run
-
pj_log_func *orig_log_writer
Saving the original log writer
-
unsigned ntests
Number of tests
-
unsigned nruns
Number of completed tests
-
void (*main)(pj_test_runner*)
main method
-
void (*on_test_complete)(pj_test_runner*, pj_test_case*)
callback when test case completes. Default is to write to log
-
void (*destroy)(pj_test_runner*)
destroy method
-
pj_test_runner_param prm
-
PJ_TEST_NON_ZERO(expr, err_reason, err_action)