From 3fab0d4b7c7fc39cc5b92dd7f19743780ccd20b5 Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
Date: Wed, 2 Apr 2014 16:42:11 +0200
Subject: Document the abort_if_missing_suites functionality

OTP-11769
---
 lib/common_test/doc/src/ct_run.xml           |  3 +++
 lib/common_test/doc/src/run_test_chapter.xml | 14 +++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

(limited to 'lib/common_test/doc')

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}.
-- 
cgit v1.2.3