File 6435-ct-ct_hooks_order-docs.patch of Package erlang
From 913a311447a73aa086902c1c81a897b1035b9b31 Mon Sep 17 00:00:00 2001
From: Jakub Witczak <kuba@erlang.org>
Date: Thu, 13 Jul 2023 12:43:49 +0200
Subject: [PATCH 5/6] ct: ct_hooks_order docs
---
lib/common_test/doc/src/ct_hooks_chapter.xml | 28 +++++++++++++++-----
lib/common_test/doc/src/ct_run_cmd.xml | 2 ++
lib/common_test/doc/src/ct_suite.xml | 9 ++++---
lib/common_test/doc/src/run_test_chapter.xml | 8 ++++++
lib/common_test/src/ct_run.erl | 1 +
5 files changed, 38 insertions(+), 10 deletions(-)
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index 840bd58cc4..78678c0ebe 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -119,13 +119,27 @@
<marker id="cth_execution_order"/>
<title>CTH Execution Order</title>
<p>By default, each CTH installed is executed in the order that
- they are installed for init calls, and then reversed for end calls.
- This is not always desired, so <c>Common Test</c> allows
- the user to specify a priority for each hook. The priority can either
- be specified in the CTH function
- <seemfa marker="ct_hooks#Module:init/2">init/2</seemfa> or when
- installing the hook. The priority specified at installation overrides the
- priority returned by the CTH.</p>
+ they are installed for init calls, and then reversed for end
+ calls. This order can be referred as test centric, as order is
+ reversed after testcase is executed and corresponds to default
+ value <c>test</c> of <c>ct_hooks_order</c> option.</p>
+ <p>Installation based order is not always
+ desired, so <c>Common Test</c> allows the user to specify a
+ priority for each hook. The priority can either be specified in
+ the CTH function <seemfa
+ marker="ct_hooks#Module:init/2">init/2</seemfa> or when
+ installing the hook. The priority specified at installation
+ overrides the priority returned by the CTH.</p>
+ <p>In some cases, reversed order for all end calls is not
+ desired and instead user might prefer reversed order for post
+ hook calls. Such behavior can be enabled with
+ <c>ct_hooks_order</c> option with <c>config</c> value. When
+ option is enabled, execution order is configuration centric, as
+ the reversed order happens after each configuration function and
+ not in relation to testcase.</p>
+ <p>Note that <c>ct_hooks_order</c> option is considered as a
+ global framework setting. In case when option is configured
+ multiple times framework with process only the first value.</p>
</section>
</section>
diff --git a/lib/common_test/doc/src/ct_run_cmd.xml b/lib/common_test/doc/src/ct_run_cmd.xml
index be3dc8a726..94c955a6ff 100644
--- a/lib/common_test/doc/src/ct_run_cmd.xml
+++ b/lib/common_test/doc/src/ct_run_cmd.xml
@@ -128,6 +128,7 @@
[-keep_logs all | NLogs]
[-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
CTHModuleN CTHOptsN]
+ [-ct_hooks_order test | config]
[-exit_status ignore_config]
[-help]</pre>
</section>
@@ -168,6 +169,7 @@
[-keep_logs all | NLogs]
[-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
CTHModuleN CTHOptsN]
+ [-ct_hooks_order test | config]
[-exit_status ignore_config]</pre>
</section>
diff --git a/lib/common_test/doc/src/ct_suite.xml b/lib/common_test/doc/src/ct_suite.xml
index 8e5a73143e..4c99181e2c 100644
--- a/lib/common_test/doc/src/ct_suite.xml
+++ b/lib/common_test/doc/src/ct_suite.xml
@@ -161,7 +161,7 @@
<fsummary>Test suite info function (providing default data
for the suite).</fsummary>
<type>
- <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs}</v>
+ <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs} | {ct_hooks_order, CTHOrder}</v>
<v>Time = TimeVal | TimeFunc</v>
<v>TimeVal = MilliSec | {seconds, integer()} | {minutes, integer()} | {hours, integer()}</v>
<v>TimeFunc = {Mod, Func, Args} | Fun</v>
@@ -184,6 +184,7 @@
<v>CTHModule = atom()</v>
<v>CTHInitArgs = term()</v>
<v>CTHPriority = integer()</v>
+ <v>CTHOrder = test | config</v>
</type>
<desc>
@@ -292,7 +293,7 @@
subgroups).</fsummary>
<type>
<v>GroupName = <seetype marker="#ct_groupname">ct_groupname()</seetype></v>
- <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs}</v>
+ <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs} | {ct_hooks_order, CTHOrder}</v>
<v>Time = TimeVal | TimeFunc</v>
<v>TimeVal = MilliSec | {seconds, integer()} | {minutes, integer()} | {hours, integer()}</v>
<v>TimeFunc = {Mod, Func, Args} | Fun</v>
@@ -315,6 +316,7 @@
<v>CTHModule = atom()</v>
<v>CTHInitArgs = term()</v>
<v>CTHPriority = integer()</v>
+ <v>CTHOrder = test | config</v>
</type>
<desc>
@@ -497,7 +499,7 @@
<name since="OTP R14B">Module:Testcase() -> [ct_info()] </name>
<fsummary>Test case information function.</fsummary>
<type>
- <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs}</v>
+ <v><seetype marker="#ct_info">ct_info()</seetype> = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile} | {ct_hooks, CTHs} | {ct_hooks_order, CTHOrder}</v>
<v>Time = TimeVal | TimeFunc</v>
<v>TimeVal = MilliSec | {seconds, integer()} | {minutes, integer()} | {hours, integer()}</v>
<v>TimeFunc = {Mod, Func, Args} | Fun</v>
@@ -520,6 +522,7 @@
<v>CTHModule = atom()</v>
<v>CTHInitArgs = term()</v>
<v>CTHPriority = integer()</v>
+ <v>CTHOrder = test | config</v>
</type>
<desc>
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index dfdaf2badb..94a137b7fb 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -210,6 +210,11 @@
<seeguide marker="ct_hooks_chapter#installing">Common Test Hooks</seeguide>
including start arguments.</p></item>
+ <tag><c><![CDATA[-ct_hooks_order [test|config]]]></c></tag>
+ <item><p>To modify
+ <seeguide marker="ct_hooks_chapter#installing">Common Test Hooks</seeguide>
+ execution order.</p></item>
+
<tag><c><![CDATA[-enable_builtin_hooks <bool>]]></c></tag>
<item><p>To enable or disable
<seeguide marker="ct_hooks_chapter#builtin_cths">Built-in Common Test Hooks</seeguide>.
@@ -883,6 +888,8 @@
{ct_hooks, CTHModules}.
{ct_hooks, NodeRefs, CTHModules}.
+ {ct_hooks_order, CTHOrder}.
+
{enable_builtin_hooks, Bool}.
{basic_html, Bool}.
@@ -952,6 +959,7 @@
{CTHModule, CTHInitArgs, CTHPriority}]
CTHModule = atom()
CTHInitArgs = term()
+ CTHOrder = test | config
Dir = string()
Suites = atom() | [atom()] | all
Suite = atom()
diff --git a/lib/common_test/src/ct_run.erl b/lib/common_test/src/ct_run.erl
index 3507f3513d..e16dc79c27 100644
--- a/lib/common_test/src/ct_run.erl
+++ b/lib/common_test/src/ct_run.erl
@@ -766,6 +766,7 @@ script_usage() ->
"\n\t [-cover_stop Bool]"
"\n\t [-event_handler EvHandler1 EvHandler2 .. EvHandlerN]"
"\n\t [-ct_hooks CTHook1 CTHook2 .. CTHookN]"
+ "\n\t [-ct_hooks_order test | config]"
"\n\t [-include InclDir1 InclDir2 .. InclDirN]"
"\n\t [-no_auto_compile]"
"\n\t [-abort_if_missing_suites]"
--
2.35.3
