File 7861-Add-documentation-for-fail-Reason-to-ct-te... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 7861-Add-documentation-for-fail-Reason-to-ct-test-case-re.patch of Package erlang

From 6216c9f9b2b4e78e57ba9390e4251aff130525a2 Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Wed, 29 Nov 2023 13:41:55 +0100
Subject: [PATCH 1/4] Add documentation for {fail,Reason} to ct test case
 return values

---
 lib/common_test/doc/src/ct_suite.xml          | 47 ++++++++++++-------
 .../doc/src/write_test_chapter.xml            |  6 +--
 lib/common_test/src/ct_suite.erl              |  1 +
 3 files changed, 35 insertions(+), 19 deletions(-)

diff --git a/lib/common_test/doc/src/ct_suite.xml b/lib/common_test/doc/src/ct_suite.xml
index 90db965829..91e80433ac 100644
--- a/lib/common_test/doc/src/ct_suite.xml
+++ b/lib/common_test/doc/src/ct_suite.xml
@@ -576,7 +576,7 @@
 </func>
 
 <func>
-	<name since="OTP R14B">Module:Testcase(Config) -> term() | {skip, Reason} | {comment, Comment} | {save_config, SaveConfig} | {skip_and_save, Reason, SaveConfig} | exit()</name>
+ <name since="OTP R14B">Module:Testcase(Config) -> term() | {skip, Reason} | {fail, Reason} | {comment, Comment} | {save_config, SaveConfig} | {skip_and_save, Reason, SaveConfig} | exit()</name>
 <fsummary>A test case.</fsummary>
 <type>
 	<v>Config = SaveConfig = <seetype marker="#ct_config">ct_config()</seetype></v>
@@ -596,25 +596,40 @@
 	Elements from the <c>Config</c> list can, for example, be read
 	 with <c>proplists:get_value/2</c> in STDLIB.
 
-	If you decide not to run the test case after all, return
-	 <c>{skip, Reason}</c>. <c>Reason</c> is then
-	 printed in field <c>Comment</c> on the HTML result page.
-
-	To print some information in field <c>Comment</c> on the HTML
-	 result page, return <c>{comment, Comment}</c>.
-
-	If the function returns anything else, the test case is
-	 considered successful. The return value always gets printed
-	 in the test case log file.
+	Possible return values are:
+	<taglist>
+	 <tag><c>{fail, Reason}</c></tag>
+	 <item>The test case is considered failed, and the <c>Reason</c>
+	 will be logged.</item>
+	 <tag><c>{skip, Reason}</c></tag>
+	 <item>The test case is considered skipped, and the <c>Reason</c>
+	 will be logged.</item>
+	 <tag><c>{comment, Comment}</c></tag>
+	 <item>The test case is considered successful, and the <c>Comment</c>
+	 will be logged.</item>
+	 <tag><c>{save_config, SaveConfig}</c></tag>
+	 <item>The test case is considered successful, and the <c>SaveConfig</c>
+	 will be stored in the <c>Config</c> (see section
+	 <seeguide marker="dependencies_chapter#save_config">Saving
+	 Configuration Data</seeguide> in the User's Guide).</item>
+	 <tag><c>{skip_and_save, Reason, SaveConfig}</c></tag>
+	 <item>The test case is considered skipped, the <c>Reason</c>
+	 will be logged, and the <c>SaveConfig</c> will be stored in the
+	 <c>Config</c> (see section
+ <seeguide marker="dependencies_chapter#save_config">Saving
+ Configuration Data</seeguide> in the User's Guide).</item>
+	</taglist>
+
+	If the function returns any other term, the test case is considered
+	 successful. It is common practice to explicitly return <c>ok</c> from
+	 successful test cases.
+
+	If the test case function crashes or exits purposely, it is considered
+	 failed.
 
 	For details about test case implementation, see section
 	 <seeguide marker="write_test_chapter#test_cases">Test Cases</seeguide>
 	 in the User's Guide.
-
-	For information on <c>save_config</c> and <c>skip_and_save</c>,
-	 see section
-	 <seeguide marker="dependencies_chapter#save_config">Saving
-	 Configuration Data</seeguide> in the User's Guide.
 </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 d945e0a58f..6489502e10 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -282,9 +282,9 @@
 be used. For example: <c>PrivDir = proplists:get_value(priv_dir, Config)</c>.
 
 
- If the test case function crashes or exits purposely, it is considered
- failed. If it returns a value (no matter what value), it is
- considered successful. An exception to this rule is the return value
+ If the test case function crashes, exits purposely or returns <c>{fail,Reason}</c>,
+ it is considered failed. If it returns any other value (no matter what value),
+ it is considered successful. An exception to this rule is the return value
 <c>{skip,Reason}</c>. If this tuple is returned, the test case is considered
 skipped and is logged as such.
 
diff --git a/lib/common_test/src/ct_suite.erl b/lib/common_test/src/ct_suite.erl
index 603485c77a..e6eeb09013 100644
--- a/lib/common_test/src/ct_suite.erl
+++ b/lib/common_test/src/ct_suite.erl
@@ -119,6 +119,7 @@
 -callback 'Testcase'(Config) ->
 term() |
 {skip, Reason} |
+ {fail, Reason} |
 {comment, Comment} |
 {save_config, SaveConfig} |
 {skip_and_save, Reason, SaveConfig}
-- 
2.35.3

Places

File 7861-Add-documentation-for-fail-Reason-to-ct-test-case-re.patch of Package erlang

Places