From 0634077b636eb0c879e1f71ba78ea1565b6617b2 Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
Date: Tue, 19 Apr 2011 16:54:46 +0200
Subject: Document the new init_per_testcase return value.

---
 lib/common_test/doc/src/common_test_app.xml    | 12 +++++++-----
 lib/common_test/doc/src/write_test_chapter.xml | 12 ++++++++----
 2 files changed, 15 insertions(+), 9 deletions(-)

(limited to 'lib/common_test/doc')

diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index 1ee73b890b..c92566de37 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -296,7 +296,7 @@
     </func>
 
       <func>
-	<name>Module:init_per_testcase(TestCase, Config) -> NewConfig | {skip,Reason}</name>
+	<name>Module:init_per_testcase(TestCase, Config) -> NewConfig | {fail,Reason} | {skip,Reason}</name>
 	<fsummary>Test case initialization.</fsummary>
 	<type>
 	  <v> TestCase = atom()</v>
@@ -311,10 +311,12 @@
 	  
 	  <p>This function is called before each test case. The
 	  <c>TestCase</c> argument is the name of the test case, and
-	  <c>Config</c> is the configuration which can be modified
-	  here. Whatever is returned from this function is given as
-	  <c>Config</c> to the test case. If <c>{skip,Reason}</c> is returned, 
-	  the test case will be skipped and <c>Reason</c> printed
+	  <c>Config</c> (list of key-value tuples) is the configuration
+	  data that can be modified here. The <c>NewConfig</c> list returned
+	  from this function is given as <c>Config</c> to the test case.
+	  If <c>{fail,Reason}</c> is returned, the test case is
+	  marked as failed without being executed. If <c>{skip,Reason}</c> is
+	  returned, the test case will be skipped and <c>Reason</c> printed
 	  in the overview log for the suite.</p>
     </desc>
     </func>
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 723492d8f3..3f9fdb7121 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -167,12 +167,16 @@
       returning <c>{fail,Reason}</c>, nor will it be able to save data with
       <c>{save_config,Data}</c>.</p>
 
-    <p>If <c>init_per_testcase</c> crashes, the test case itself is skipped 
+    <p>If <c>init_per_testcase</c> crashes, the test case itself gets skipped 
     automatically (so called <em>auto skipped</em>). If <c>init_per_testcase</c>
-    returns a <c>skip</c> tuple, also then will the test case be skipped (so
-    called <em>user skipped</em>). In either event, the <c>end_per_testcase</c> is 
-    never called.
+    returns a tuple <c>{skip,Reason}</c>, also then the test case gets skipped
+    (so called <em>user skipped</em>). It is also possible, by returning a tuple
+    <c>{fail,Reason}</c> from <c>init_per_testcase</c>, to mark the test case
+    as failed without actually executing it.
     </p>
+    <note><p>If <c>init_per_testcase</c> crashes, or returns <c>{skip,Reason}</c>
+    or <c>{fail,Reason}</c>, the <c>end_per_testcase</c> function is not called.
+    </p></note>
 
     <p>If it is determined during execution of <c>end_per_testcase</c> that
     the status of a successful test case should be changed to failed, 
-- 
cgit v1.2.3