File 7081-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 @@
<p>Elements from the <c>Config</c> list can, for example, be read
with <c>proplists:get_value/2</c> in STDLIB.</p>
- <p>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.</p>
-
- <p>To print some information in field <c>Comment</c> on the HTML
- result page, return <c>{comment, Comment}</c>.</p>
-
- <p>If the function returns anything else, the test case is
- considered successful. The return value always gets printed
- in the test case log file.</p>
+ <p>Possible return values are:</p>
+ <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>
+
+ <p>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.</p>
+
+ <p>If the test case function crashes or exits purposely, it is considered
+ failed.</p>
<p>For details about test case implementation, see section
<seeguide marker="write_test_chapter#test_cases">Test Cases</seeguide>
in the User's Guide.</p>
-
- <p>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.</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 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>.
</p>
- <p>If the test case function crashes or exits purposely, it is considered
- <em>failed</em>. If it returns a value (no matter what value), it is
- considered successful. An exception to this rule is the return value
+ <p>If the test case function crashes, exits purposely or returns <c>{fail,Reason}</c>,
+ it is considered <em>failed</em>. 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.</p>
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
