Skip to content

Writing tests in FreeSWITCH

Jump to bottom
Andrey Volk edited this page Jun 11, 2021 · 2 revisions

Introduction

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.

Writing tests / switch_ivr_play_say example

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.

Adding a new test suite to the build

New core tests

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

New module tests

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)

Running the tests

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
Clone this wiki locally