Created Writing tests in FreeSWITCH (markdown)

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
+```