From 378da5aef27e1679aa30b8f4a2a6569accb70ff2 Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
Date: Tue, 24 Oct 2017 16:24:18 +0200
Subject: Add tests and doc for the new remaining_test_procs function

---
 lib/common_test/src/ct.erl      | 39 +++++++++++++++++++++++++++++++--------
 lib/common_test/src/ct_util.erl |  4 ++--
 2 files changed, 33 insertions(+), 10 deletions(-)

(limited to 'lib/common_test/src')

diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index 8289e8d9af..4c4dc8bede 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -89,7 +89,7 @@
 -export([get_target_name/1]).
 -export([parse_table/1, listenv/1]).
 
--export([get_test_processes/0]).
+-export([remaining_test_procs/0]).
 
 %%----------------------------------------------------------------------
 %% Exported types
@@ -1479,10 +1479,33 @@ continue(TestCase) ->
 
 
 %%%-----------------------------------------------------------------
-%%% @spec get_test_processes() -> TestProcs
-%%%       TestProcs = [{Pid,GroupLeader}]
-%%%
-%%% @doc 
-%%%
-get_test_processes() ->
-    ct_util:get_test_processes().
+%%% @spec remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
+%%%       TestProcs = [{pid(),GL}]
+%%%       GL = SharedGL = pid()
+%%%       OtherGLs = [pid()]
+%%%
+%%% @doc <p>This function will return the identity of test- and group
+%%%      leader processes that are still running at the time of this call.
+%%%      TestProcs are processes in the system that have a Common Test IO
+%%%      process as group leader. SharedGL is the central Common Test
+%%%      IO process, responsible for printing to log files for configuration
+%%%      functions and sequentially executing test cases. OtherGLs are
+%%%      Common Test IO processes that print to log files for test cases
+%%%      in parallel test case groups.</p>
+%%%      <p>The process information returned by this function may be
+%%%      used to locate and terminate remaining processes after tests have
+%%%      finished executing. The function would typically by called from
+%%%      Common Test Hook functions.</p>
+%%%      <p>Note that processes that execute configuration functions or
+%%%      test cases are never included in TestProcs. It is therefore safe
+%%%      to use post configuration hook functions (such as post_end_per_suite,
+%%%      post_end_per_group, post_end_per_testcase) to terminate all processes
+%%%      in TestProcs that have the current group leader process as its group
+%%%      leader.</p>
+%%%      <p>Note also that the shared group leader (SharedGL) must never be
+%%%      terminated by the user, only by Common Test. Group leader processes
+%%%      for parallel test case groups (OtherGLs) may however be terminated
+%%%      in post_end_per_group hook functions.</p>
+%%%      
+remaining_test_procs() ->
+    ct_util:remaining_test_procs().
diff --git a/lib/common_test/src/ct_util.erl b/lib/common_test/src/ct_util.erl
index 796a459bfe..468edc4bee 100644
--- a/lib/common_test/src/ct_util.erl
+++ b/lib/common_test/src/ct_util.erl
@@ -66,7 +66,7 @@
 -export([warn_duplicates/1]).
 
 -export([mark_process/0, mark_process/1, is_marked/1, is_marked/2,
-         get_test_processes/0]).
+         remaining_test_procs/0]).
 
 -export([get_profile_data/0, get_profile_data/1,
 	 get_profile_data/2, open_url/3]).
@@ -955,7 +955,7 @@ is_marked(Pid, Type) ->
             false
     end.
 
-get_test_processes() ->
+remaining_test_procs() ->
     Procs = processes(),
     {SharedGL,OtherGLs,Procs2} =
         lists:foldl(
-- 
cgit v1.2.3