Multi Process Testing framework

Signed-off-by: Martin Bremmer <martin.bremmer@adlinktech.com>

docs/dev/mpt_req.md

@@ -0,0 +1,86 @@
+# Eclipse Cyclone DDS Multi Process Testing Requirements
+
+This document present some requirements and considerations regarding the
+[Multi Process Test Framework](multi_process_testing.md).
+
+## Requirements
+1.1) To test certain Cyclone DDS features, multiple processes running Cyclone
+     DDS are needed to force communication through the whole stack.
+
+1.2) Should be buildable and runnable on platforms that support multiprocess
+     and filesystems including the ones used in the continues integration
+     context.
+
+1.3) Results should be easily analyzable within the continues integration
+     context and when running locally. This can be done by reporting the
+     results in a standard format like xunit or cunit.
+
+1.4) No processes must be left behind (f.i. deadlock in child process) when the
+     test finished (or timed out).
+
+1.5) When running tests parallel, they should not interfere with each other.
+
+1.6) Processes of the same test should be able to communicate (for settings,
+     syncing, etc).
+
+1.7) It should be possible to analyze output/messages/tracing of the parent
+     and child processes to be able to draw a proper test conclusion.
+
+
+## Considerations
+2.1)
+The files that actually contain the tests, should be focused on those tests.
+This means that the process management and setting up (and usage of) IPC
+between test processes should be handled by a test framework so that the
+test files can remain as clean as possible.
+
+2.2)
+If possible, there shouldn't be a need for writing log files to a file system
+when running the tests normally. It could be helpful, however, that these log
+files are written when debugging related tests.
+
+2.3)
+Preferably, the DDS communication between the processes should not leave
+localhost.
+
+
+## Intentions
+There doesn't seem to be a 3rd party test framework that addresses our
+requirements in a satisfactory manner.
+
+After some discussions with a few people (different people in different
+meetings), it was decided to create our own framework and to go in the
+following direction:
+
+- Process creation/destruction/etc is (re)introduced in the ddsrt.<br>
+  [1.1/1.2]
+
+- The files that contain the tests, should be easy to understand and focus on
+  the tests themselves.<br>
+  [2.1]
+
+- Other files (generated or in the framework) should take care of the
+  intricacies of starting/monitoring the proper processes with the proper
+  settings.<br>
+  [1.4/1.6/2.1]
+
+- To do this, a similar approach of the current CUnit build will be used;
+  CMake will scan the test files and create runners according to macros within
+  the test files.<br>
+  [2.1]
+
+- The tests should be executed by CTest. For now this means that a proper
+  runner exit code for pass/fail is enough. We would like to add CUnit like
+  output in the future.<br>
+  [1.2/1.3]
+
+- The Cyclone DDS API contains the possibility to monitor generated log traces.
+  This means we won't be needing to monitor actual log files. Just register a
+  log callback and go from there.<br>
+  [1.7/2.2]
+
+- The framework should be able to generate unique domain ids and unique topic
+  names when necessary. That way, tests won't interfere with each other when
+  running in parallel.<br>
+  [1.5]
+

docs/dev/multi_process_testing.md

@@ -0,0 +1,86 @@
+# Eclipse Cyclone DDS Multi Process Testing
+
+Some features and functionalities of Cyclone DDS can only be tested when
+there's communication between processes. Examples are durability, security,
+etc. To really make sure that these kind of features work, extended tests
+with multiple processes are needed.
+
+This results in a number of [requirements](mpt_req.md).
+
+There doesn't seem to be a 3rd party test framework that addresses our
+requirements in a satisfactory manner. Therefore, it was decided to create
+our own Multi Process Testing (MPT) framework.
+
+This document will provide an overview of the MPT framework.
+
+
+## Overview
+
+An MPT application is basically divided into two components
+1. Tests
+2. Runner
+
+The Tests are created by the developer. They don't need to worry about the
+process management. They only have to provide process entry point(s), tests
+and test processes that use these entry points. E.g.
+```cpp
+MPT_ProcessEntry(publisher, MPT_Args(int domain))
+{
+  /* Publish a sample on the given domain. */
+  MPT_ASSERT(success, "publisher failed");
+}
+MPT_ProcessEntry(subscriber, MPT_Args(int domain))
+{
+  /* Subscribe to a sample from the given domain. */
+  MPT_ASSERT(success, "subscriber failed");
+}
+
+MPT_TestProcess(helloworld, domain0, pub, publisher,  MPT_ArgValues(0));
+MPT_TestProcess(helloworld, domain0, sub, subscriber, MPT_ArgValues(0));
+MPT_Test(helloworld, domain0);
+
+MPT_TestProcess(helloworld, domain42, pub, publisher,  MPT_ArgValues(42));
+MPT_TestProcess(helloworld, domain42, sub, subscriber, MPT_ArgValues(42));
+MPT_Test(helloworld, domain42);
+```
+
+There are more options, but see the
+[usage test](../../src/mpt/tests/self/usage.c) for more elaborate examples.
+
+CMake will identify suites, tests and processes depending on those MPT
+macros.<br>
+It'll use that to generate part of the MPT Runner. The Runner takes care
+of starting test(s) and handling the process management.
+
+The runner also takes care of preparing IPC between test processes so that
+these processes can sync if they need to (NB, this will be a future extension).
+
+
+#### Suite-Test-Process tree
+
+A process is related to a test and that test is related to a suite.<br>
+A suite can have multiple tests and tests can have multiple processes.<br>
+
+This results in the following tree quite naturally.
+
+<img src="pictures/mpt_tree.png" alt="Suite-Test-Process tree">
+
+
+#### Test execution
+
+There are 3 main ways to start an MPT application.
+1. Without argument.<br>
+   All tests will be run.
+2. With suite and/or test name patterns as arguments.<br>
+   A subset of tests will be run depending on the provided patterns.<br>
+   This allows ctest to execute single tests.
+3. With a specific suite/test/process combination as arguments.<br>
+   An user will normally not use this.
+
+The third option is used by the MPT application itself to start a specific
+test related process. It does so by restarting itself with the proper
+suite/test/process combination as indicated by the test. This results
+in the following flow.
+
+<img src="pictures/mpt_flow.png" alt="MPT application flow">
+