Document the abort_if_missing_suites functionality

OTP-11769

4 files changed, 20 insertions, 4 deletions

diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 39259b092a..d8e79ca80e 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -108,6 +108,7 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
@@ -144,6 +145,7 @@
 	 EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
@@ -171,6 +173,7 @@
 	[-decrypt_key Key] | [-decrypt_file KeyFile]
 	[-include InclDir1 InclDir2 .. InclDirN]
 	[-no_auto_compile]
+	[-abort_if_missing_suites]
 	[-muliply_timetraps Multiplier]
 	[-scale_timetraps]
 	[-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index ef21948f89..864f82cb63 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -59,7 +59,15 @@
     <p>If compilation should fail for one or more suites, the compilation errors
       are printed to tty and the operator is asked if the test run should proceed
       without the missing suites, or be aborted. If the operator chooses to proceed, 
-      it is noted in the HTML log which tests have missing suites.</p>
+      it is noted in the HTML log which tests have missing suites. If Common Test is
+      unable to prompt the user after compilation failure (if Common Test doesn't
+      control stdin), the test run will proceed automatically without the missing
+      suites. This behaviour can however be modified with the
+      <c><![CDATA[ct_run]]></c> flag <c><![CDATA[-abort_if_missing_suites]]></c>, 
+      or the <c><![CDATA[ct:run_test/1]]></c> option
+      <c><![CDATA[{abort_if_missing_suites,TrueOrFalse}]]></c>. If 
+      <c><![CDATA[abort_if_missing_suites]]></c> is set (to true), the test run
+      will stop immediately if some suites fail to compile.</p>
 
     <p>Any help module (i.e. regular Erlang module with name not ending with
       "_SUITE") that resides in the same test object directory as a suite 
@@ -167,6 +175,7 @@
         <seealso marker="ct_hooks_chapter#builtin_cths">Built-in Common Test Hooks</seealso>. Default is <c>true</c>.</item>
       <item><c><![CDATA[-include]]></c>, specifies include directories (see above).</item>
       <item><c><![CDATA[-no_auto_compile]]></c>, disables the automatic test suite compilation feature (see above).</item>
+      <item><c><![CDATA[-abort_if_missing_suites]]></c>, aborts the test run if one or more suites fail to compile (see above).</item>
       <item><c><![CDATA[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
 	  timeout</seealso> values.</item>
       <item><c><![CDATA[-scale_timetraps <bool>]]></c>, enables automatic <seealso marker="write_test_chapter#timetraps">timetrap
@@ -744,6 +753,9 @@
 	{auto_compile, Bool},
 	{auto_compile, NodeRefs, Bool},
 	
+	{abort_if_missing_suites, Bool},
+	{abort_if_missing_suites, NodeRefs, Bool},
+
 	{config, ConfigFiles}.
 	{config, ConfigDir, ConfigBaseNames}.
 	{config, NodeRefs, ConfigFiles}.
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index e6732f7fc7..241cd928b7 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -150,7 +150,8 @@ run(TestDirs) ->
 %%%               {silent_connections,Conns} | {stylesheet,CSSFile} |
 %%%               {cover,CoverSpecFile} | {cover_stop,Bool} | {step,StepOpts} |
 %%%               {event_handler,EventHandlers} | {include,InclDirs} |
-%%%               {auto_compile,Bool} | {create_priv_dir,CreatePrivDir}  |
+%%%               {auto_compile,Bool} | {abort_if_missing_suites,Bool} |
+%%%               {create_priv_dir,CreatePrivDir}  |
 %%%               {multiply_timetraps,M} | {scale_timetraps,Bool} |
 %%%               {repeat,N} | {duration,DurTime} | {until,StopTime} |
 %%%               {force_stop,ForceStop} | {decrypt,DecryptKeyOrFile} |
diff --git a/lib/common_test/src/ct_telnet.erl b/lib/common_test/src/ct_telnet.erl
index 596756348b..c9dc2338cd 100644
--- a/lib/common_test/src/ct_telnet.erl
+++ b/lib/common_test/src/ct_telnet.erl
@@ -64,7 +64,7 @@
 %% `conn_mod()' is the name of the common_test module implementing
 %% the connection protocol, i.e. `ct_telnet'.
 %%
-%% The `cth_conn_log' hook provides unformatted logging of telnet data to
+%% The `cth_conn_log' hook performs unformatted logging of telnet data to
 %% a separate text file. All telnet communication is captured and printed,
 %% including arbitrary data sent from the server. The link to this text file
 %% can be found on the top of the test case HTML log.
@@ -106,7 +106,7 @@
 %%'''
 %%
 %% As previously explained, the above specification could also be provided
-%% with the following entry in a configuration file:
+%% by means of an entry like this in a configuration file:
 %%
 %% ```
 %% {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.