From 784648708b80e340fea43b83abfba2855e283f20 Mon Sep 17 00:00:00 2001 From: Chris Rienzo Date: Wed, 19 May 2021 14:36:15 -0400 Subject: [PATCH] Created Writing tests in FreeSWITCH (markdown) --- Writing-tests-in-FreeSWITCH.md | 164 +++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 Writing-tests-in-FreeSWITCH.md diff --git a/Writing-tests-in-FreeSWITCH.md b/Writing-tests-in-FreeSWITCH.md new file mode 100644 index 0000000..35c69de --- /dev/null +++ b/Writing-tests-in-FreeSWITCH.md @@ -0,0 +1,164 @@ +## 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`](https://github.com/signalwire/freeswitch/tree/master/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`](https://github.com/signalwire/freeswitch/tree/master/tests/unit) directory. Module tests are located in their [`test`](https://github.com/signalwire/freeswitch/tree/master/src/mod/formats/mod_sndfile/test) subdirectory. + +## Writing tests / switch_ivr_play_say example + +Below is an example of a test of [`switch_ivr_play_say()`](https://github.com/signalwire/freeswitch/tree/master/tests/unit/switch_ivr_play_say.c). 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](https://github.com/signalwire/freeswitch/tree/master/src/include/test/switch_test.h) + +``` +FST_CORE_BEGIN("./conf_playsay") +{ +``` +`FST_CORE_BEGIN` creates the FreeSWITCH core instance. The [`./conf_playsay`](https://github.com/signalwire/freeswitch/tree/master/tests/unit/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](https://github.com/signalwire/freeswitch/tree/master/src): + +- Add the new test file to the [`tests/unit/`](https://github.com/signalwire/freeswitch/tree/master/tests/unit) directory. +- Update [`tests/unit/Makefile.am`](https://github.com/signalwire/freeswitch/blob/master/tests/unit/Makefile.am#L5) 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](https://github.com/signalwire/freeswitch/tree/master/src/mod/formats/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 + +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 +```