FreeSWITCH comes with a header-only unit test framework based on https://github.com/imb/fctx. This test framework is enhanced by src/include/test/switch_test.h to make it simple to create testable calls.

There are many examples of testing FreeSWITCH core in the tests/unit directory. Module tests are located in their test subdirectory.

Below is an example of a test of switch_ivr_play_say(). To test this function, we need a running FreeSWITCH core and an active session. The test framework will easily set both up.

For more details about the available test functions and macros see switch_test.h

FST_CORE_BEGIN("./conf_playsay") { 

FST_CORE_BEGIN creates the FreeSWITCH core instance. The ./conf_playsay argument is the subdirectory containing the FreeSWITCH configuration for this instance.

FST_SUITE_BEGIN(switch_ivr_play_say)	{ 

FST_SUITE_BEGIN marks the start of a test suite. The switch_ivr_play_say argument is the name of the test suite.

FST_SETUP_BEGIN()	{	fst_requires_module("mod_tone_stream");	fst_requires_module("mod_sndfile");	fst_requires_module("mod_dptools");	fst_requires_module("mod_test");	}	FST_SETUP_END()	FST_TEARDOWN_BEGIN()	{	}	FST_TEARDOWN_END() 

FST_SETUP_BEGIN() is run before each test in the test suite. In this example, the setup is checking if some dependent modules are installed. FST_TEARDOWN_END() is run after each test in the test suite. Both FST_SETUP_BEGIN() and FST_TEARDOWN_END() must be in the test suite even if there is nothing to do.

FST_SESSION_BEGIN(play_and_collect_input_failure)	{ 

FST_SESSION_BEGIN() is the start of a test that uses a FreeSWITCH session. It takes the name of the test as an argument. A test created with FST_SESSION_BEGIN() will automatically create the following local variables for you:

• fst_session : the session created for testing
• fst_channel : the session's channel
• fst_session_pool : the session's memory pool
• fst_pool : a memory pool for the test

char terminator_collected = 0;	char *digits_collected = NULL;	cJSON *recognition_result = NULL;	// args	const char *play_files = "silence_stream://2000";	const char *speech_engine = "test";	const char *terminators = "#";	int min_digits = 1;	int max_digits = 3;	int digit_timeout = 15000;	int no_input_timeout = digit_timeout;	int speech_complete_timeout = digit_timeout;	int speech_recognition_timeout = digit_timeout;	char *speech_grammar_args = switch_core_session_sprintf(fst_session, "{start-input-timers=false,no-input-timeout=%d,vad-silence-ms=%d,speech-timeout=%d,language=en-US}default", no_input_timeout, speech_complete_timeout, speech_recognition_timeout);	switch_status_t status;	// collect input - 1#	fst_sched_recv_dtmf("+1", "1");	fst_sched_recv_dtmf("+2", "2");	fst_sched_recv_dtmf("+3", "3");	status = switch_ivr_play_and_collect_input(fst_session, play_files, speech_engine, speech_grammar_args, min_digits, max_digits, terminators, digit_timeout, &recognition_result, &digits_collected, &terminator_collected, NULL); 

Inside the test, you can execute most switch_ core functions on the fst_session. In this example, switch_ivr_play_and_collect_input() is executed on the fst_session with fst_sched_recv_dtmf() executed prior to schedule dtmf injection into the fst_session. This simulates an IVR receiving the digits 123.

fst_check(status == SWITCH_STATUS_SUCCESS);	fst_check_string_equals(cJSON_GetObjectCstr(recognition_result, "text"), NULL);	fst_check_string_equals(digits_collected, "123");	fst_check(terminator_collected == 0); 

This part of the test verifies the behavior of FreeSWITCH is correct using the fst_check* macros. fst_check() will test if the condition inside is true. fst_check_string_equals() will evaluate true if the two string arguments are equal.

In this test, we expect the result of switch_ivr_play_and_collect_input() to be SWITCH_STATUS_SUCCESS and we expect the JSON recognition_result to contain the digits 123 with no terminator_collected.

}	FST_SESSION_END() 

FST_SESSION_END() marks the end of the session being tested.

}	FST_SUITE_END() 

FST_SUITE_END() marks the end of the test suite.

} FST_CORE_END() 

FST_CORE_END() marks the end of the core instance. FreeSWITCH is shut down here.

To add a new test for FreeSWITCH core functions:

• Add the new test file to the tests/unit/ directory.
• Update tests/unit/Makefile.am to add the new test to the noinst_PROGRAMS variable.
  • For example: noinst_PROGRAMS += existing_test_1 my_new_test

To add tests to a module, like mod_sndfile

• Add the new test file to the test subdirectory
• Edit Makefile.am in the module directory to add the tests as noinst_PROGRAMS and set the TESTS variable for make check If this is the first test being added, we also need to create a library file for the test to link to in noinst_LTLIBRARIES.

include $(top_srcdir)/build/modmake.rulesam MODNAME=mod_mytestedmodule noinst_LTLIBRARIES = libmytestedmodule.la libmytestedmodule_la_SOURCES = mod_mytestedmodule.c libmytestedmodule_la_CFLAGS = $(AM_CFLAGS) mod_LTLIBRARIES = mod_mytestedmodule.la mod_mytestedmodule_la_SOURCES = mod_mytestedmodule_la_CFLAGS = $(AM_CFLAGS) mod_mytestedmodule_la_LIBADD = libmytestedmodule.la $(switch_builddir)/libfreeswitch.la mod_mytestedmodule_la_LDFLAGS = -avoid-version -module -no-undefined -shared noinst_PROGRAMS = test/my_new_test test_my_new_test = test/my_new_test.c test_my_new_test_CFLAGS = $(AM_CFLAGS) -I. -DSWITCH_TEST_BASE_DIR_FOR_CONF=\"${abs_builddir}/test\" -DSWITCH_TEST_BASE_DIR_OVERRIDE=\"${abs_builddir}/test\" test_my_new_test_LDFLAGS = $(AM_LDFLAGS) -avoid-version -no-undefined $(freeswitch_LDFLAGS) $(switch_builddir)/libfreeswitch.la $(CORE_LIBS) $(APR_LIBS) test_my_new_test_LDADD = libmytestmodule.la TESTS = $(noinst_PROGRAMS) 

Make sure you did run make install after build.

To run the FreeSWITCH core/module tests: make check

You can also run a specific test program by navigating to the test directory and executing it:

$ cd tests/unit $ ./switch_ivr_play_say 

To run specific test(s) in a test program matching a prefix:

$ cd tests/unit $ ./switch_ivr_play_say play_and_collect_input