File 3885-ct-ct_hooks_order-docs.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3885-ct-ct_hooks_order-docs.patch of Package erlang (Revision 8f70100112790b2ecaef2042dd03930d)

Currently displaying revision 8f70100112790b2ecaef2042dd03930d , Show latest

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

Places

File 3885-ct-ct_hooks_order-docs.patch of Package erlang (Revision 8f70100112790b2ecaef2042dd03930d)

Places