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.

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

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.

Public Members

int level: level

int len: len

char msg[1]: The log message. The actual buffer is longer.

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.

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

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

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).

struct pj_test_runner_param

#include <unittest.h>

Test runner parameters. Use pj_test_runner_param_default() to initialize this structure.

Public Members

pj_bool_t stop_on_error: Stop the test on error (default: false)

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

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

pj_bool_t stopping: Stopping

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