Initial commit

README.md

@@ -0,0 +1,82 @@
+gm_ctflow
+=====
+
+A helper application for cross-testcase test flows in Common Test
+
+Description
+----
+When testing complex systems it often feels convenient to organize test
+sequences as a sequential group where a series of test cases perform a
+flow of operations. A challenge may arise when the results from one
+test case need to be reused by later cases - Common Test does cater for
+this through the `save_config` return.
+
+However, occasionally, one also needs to have bespoke servers running
+for the duration of such a sequence, and this tends to lead to hacking
+a plain process with a custom protocol.
+
+This application attempts to make that a bit more structured.
+In its initial version, there are two APIs:
+
+* `gm_ctflow_fun`, where one can instantiate a stateful handler fun,
+  which can be called by test cases as needed.
+* `gm_ctflow_worker`, a gen_server where the server logic is given
+  by a user-provided fun. The server is spawned under a
+  `simple_one_for_one` supervisor.
+  
+The application `gm_ctflow` is intended to be started in
+`init_per_suite/1` and stopped in `end_per_suite/1`, or in
+`init_per_group/2` / `end_per_group/2`.
+
+Some examples from `test/gm_ctflow_SUITE.erl`:
+
+```erlang
+groups() ->
+    [ {statefuns, [sequence], [ init_counter
+                              , incr
+                              , check1       %% state = 1
+                              , incr
+                              , check2       %% state = 2
+                              , incr
+                              , check3       %% state = 3
+                              ]}
+    , {workers, [sequence], [ init_counter
+                            , init_worker
+                            , append
+                            , checkl1        %% [A0]
+                            , append
+                            , checkl2        %% [A0, A1]
+                            , append
+                            , checkl3        %% [A0, A1, A2]
+                            ]}
+    ].
+```
+
+Here, we interleave test cases with checks of the flow fun states.
+This test suite does nothing but exercize the flow funs, but normally,
+these funs would be used to e.g. spawn an endpoint needed for the tests,
+or thread some state through a test sequence.
+
+The `gm_ctflow` application is started and stopped per-group here:
+```erlang
+init_per_group(_Grp, Config) ->
+    ok = application:start(gm_ctflow, permanent),
+    Config.
+
+end_per_group(_Grp, _Config) ->
+    ok = application:stop(gm_ctflow),
+    ok.
+```
+
+This resets the state and removes all helper processes for each group.
+
+
+Build
+-----
+
+    $ rebar3 compile
+
+Test
+-----
+
+    $ rebar ct