File 6411-ct-Remove-documentation-for-deprecated-config.patch of Package erlang
From 929a906eab3e11c0f4a8994e90b36ac02e185156 Mon Sep 17 00:00:00 2001
From: Johannes Christ <jc@jchri.st>
Date: Fri, 3 Nov 2023 17:08:30 +0100
Subject: [PATCH] ct: Remove documentation for deprecated ?config
Per dcda9b507bf and review of #7806, usage of CT's `?config` macro is no
longer recommended. Replace the documentation referencing it with
`proplists:get_value`, which works the same way and can take an optional
third argument for the default return value.
---
.../doc/src/config_file_chapter.xml | 8 ++--
lib/common_test/doc/src/ct.xml | 15 +++----
lib/common_test/doc/src/ct_suite.xml | 3 +-
.../doc/src/dependencies_chapter.xml | 40 +++++++++----------
lib/common_test/doc/src/example_chapter.xml | 14 +++----
.../doc/src/write_test_chapter.xml | 11 +++--
6 files changed, 45 insertions(+), 46 deletions(-)
diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml
index 2d47b143c8..2ab9259dfb 100644
--- a/lib/common_test/doc/src/config_file_chapter.xml
+++ b/lib/common_test/doc/src/config_file_chapter.xml
@@ -332,7 +332,7 @@
ftptest(Config) ->
Remote = filename:join(ct:get_config(lm_directory), "loadmodX"),
- Local = filename:join(?config(priv_dir,Config), "loadmodule"),
+ Local = filename:join(proplists:get_value(priv_dir,Config), "loadmodule"),
ok = ct_ftp:recv(ftp, Remote, Local),
...</pre>
@@ -347,7 +347,7 @@
end_per_testcase(ftptest, Config) ->
lists:foreach(fun(Handle) -> ct_ftp:close(Handle) end,
- ?config(ftp_handles,Config)).
+ proplists:get_value(ftp_handles,Config)).
ftptest() ->
[{require,ftp_host},
@@ -355,8 +355,8 @@
ftptest(Config) ->
Remote = filename:join(ct:get_config(lm_directory), "loadmodX"),
- Local = filename:join(?config(priv_dir,Config), "loadmodule"),
- [Handle | MoreHandles] = ?config(ftp_handles,Config),
+ Local = filename:join(proplists:get_value(priv_dir,Config), "loadmodule"),
+ [Handle | MoreHandles] = proplists:get_value(ftp_handles,Config),
ok = ct_ftp:recv(Handle, Remote, Local),
...</pre>
diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml
index 0d7095db5d..613ecbd05b 100644
--- a/lib/common_test/doc/src/ct.xml
+++ b/lib/common_test/doc/src/ct.xml
@@ -43,13 +43,10 @@
tests and basic functions for <c>Common Test</c> case issues, such as
configuration and logging.</p>
- <p><em>Test Suite Support Macros</em></p>
-
- <p>The <c>config</c> macro is defined in <c>ct.hrl</c>. This macro is
- to be used to retrieve information from the <c>Config</c> variable sent
- to all test cases. It is used with two arguments; the first is the name
- of the configuration variable to retrieve, the second is the
- <c>Config</c> variable supplied to the test case.</p>
+ <p>The framework stores configuration values in a property list usually named
+ <c>Config</c>. The list contains information about the test run added by the
+ framework itself and may also contain user-provided values. The configuration
+ is passed into individual test cases as well as support functions if defined.</p>
<p>Possible configuration variables include:</p>
@@ -63,6 +60,10 @@
in the test suite.</p></item>
</list>
+ <warning><p>The <c>?config</c> macro, used to receive individual config values from
+ the <c>Config</c> property list, is deprecated. Please use
+ <c>proplists:get_value/2-3</c> instead.</p></warning>
+
</description>
<datatypes>
diff --git a/lib/common_test/doc/src/ct_suite.xml b/lib/common_test/doc/src/ct_suite.xml
index 8e5a73143e..bb7e6b51f9 100644
--- a/lib/common_test/doc/src/ct_suite.xml
+++ b/lib/common_test/doc/src/ct_suite.xml
@@ -593,8 +593,7 @@
(which also causes the test case process to terminate).</p>
<p>Elements from the <c>Config</c> list can, for example, be read
- with <c>proplists:get_value/2</c> in STDLIB
- (or the macro <c>?config</c> defined in <c>ct.hrl</c>).</p>
+ 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
diff --git a/lib/common_test/doc/src/dependencies_chapter.xml b/lib/common_test/doc/src/dependencies_chapter.xml
index f5d409686e..7458533984 100644
--- a/lib/common_test/doc/src/dependencies_chapter.xml
+++ b/lib/common_test/doc/src/dependencies_chapter.xml
@@ -118,8 +118,8 @@
end_per_testcase(start_and_stop, _) ->
ok;
- end_per_testcase(_, _) ->
- ServerPid = ?config(server_pid),
+ end_per_testcase(_, Config) ->
+ ServerPid = proplists:get_value(server_pid, Config),
stop_server(ServerPid).
%%% test cases...
@@ -133,12 +133,12 @@
%% configuration test
config(Config) ->
- ServerPid = ?config(server_pid, Config),
+ ServerPid = proplists:get_value(server_pid, Config),
configure_server(ServerPid).
%% test connecting and disconnecting client
connect_and_disconnect(Config) ->
- ServerPid = ?config(server_pid, Config),
+ ServerPid = proplists:get_value(server_pid, Config),
{ok,SessionId} = my_server:connect(ServerPid),
ok = my_server:disconnect(ServerPid, SessionId).
@@ -179,18 +179,18 @@
<p>To save <c>Config</c> data, return tuple <c>{save_config,ConfigList}</c>
from <c>end_per_testcase</c> or from the main test case function.</p>
- <p>To read data saved by a previous test case, use macro <c>config</c> with a
- <c>saved_config</c> key as follows:</p>
+ <p>To read data saved by a previous test case, use <c>proplists:get_value</c>
+ with a <c>saved_config</c> key as follows:</p>
- <p><c>{Saver,ConfigList} = ?config(saved_config, Config)</c></p>
+ <p><c>{Saver,ConfigList} = proplists:get_value(saved_config, Config)</c></p>
<p><c>Saver</c> (<c>atom()</c>) is the name of the previous test case (where the
- data was saved). The <c>config</c> macro can be used to extract particular data
- also from the recalled <c>ConfigList</c>. It is strongly recommended that
- <c>Saver</c> is always matched to the expected name of the saving test case.
- This way, problems because of restructuring of the test suite can be avoided.
- Also, it makes the dependency more explicit and the test suite easier to read
- and maintain.</p>
+ data was saved). The <c>proplists:get_value</c> function can be used to extract
+ particular data also from the recalled <c>ConfigList</c>. It is strongly
+ recommended that <c>Saver</c> is always matched to the expected name of
+ the saving test case. This way, problems because of restructuring of the
+ test suite can be avoided. Also, it makes the dependency more explicit
+ and the test suite easier to read and maintain.</p>
<p>To pass data from one test suite to another, the same mechanism is used. The data
is to be saved by finction
@@ -211,9 +211,9 @@
init_per_suite(Config) ->
%% read config saved by previous test suite
- {server_a_SUITE,OldConfig} = ?config(saved_config, Config),
+ {server_a_SUITE,OldConfig} = proplists:get_value(saved_config, Config),
%% extract server identity (comes from server_a_SUITE)
- ServerId = ?config(server_id, OldConfig),
+ ServerId = proplists:get_value(server_id, OldConfig),
SessionId = connect_to_server(ServerId),
[{ids,{ServerId,SessionId}} | Config].
@@ -226,16 +226,16 @@
all() -> [allocate, deallocate].
allocate(Config) ->
- {ServerId,SessionId} = ?config(ids, Config),
+ {ServerId,SessionId} = proplists:get_value(ids, Config),
{ok,Handle} = allocate_resource(ServerId, SessionId),
%% save handle for deallocation test
NewConfig = [{handle,Handle}],
{save_config,NewConfig}.
deallocate(Config) ->
- {ServerId,SessionId} = ?config(ids, Config),
- {allocate,OldConfig} = ?config(saved_config, Config),
- Handle = ?config(handle, OldConfig),
+ {ServerId,SessionId} = proplists:get_value(ids, Config),
+ {allocate,OldConfig} = proplists:get_value(saved_config, Config),
+ Handle = proplists:get_value(handle, OldConfig),
ok = deallocate_resource(ServerId, SessionId, Handle).</pre>
<p>To save <c>Config</c> data from a test case that is to be
@@ -245,7 +245,7 @@
<p>The result is that the test case is skipped with <c>Reason</c> printed to
the log file (as described earlier) and <c>ConfigList</c> is saved
for the next test case. <c>ConfigList</c> can be read using
- <c>?config(saved_config, Config)</c>, as described earlier. <c>skip_and_save</c>
+ <c>proplists:get_value(saved_config, Config)</c>, as described earlier. <c>skip_and_save</c>
can also be returned from <c>init_per_suite</c>. In this case, the saved data can
be read by <c>init_per_suite</c> in the suite that follows.</p>
</section>
diff --git a/lib/common_test/doc/src/example_chapter.xml b/lib/common_test/doc/src/example_chapter.xml
index b82d14d2d8..e355e6ae7c 100644
--- a/lib/common_test/doc/src/example_chapter.xml
+++ b/lib/common_test/doc/src/example_chapter.xml
@@ -90,7 +90,7 @@
%% Description: Cleanup after the suite.
%%--------------------------------------------------------------------
end_per_suite(Config) ->
- Ref = ?config(con_ref, Config),
+ Ref = proplists:get_value(con_ref, Config),
db:disconnect(Ref),
ok.
@@ -105,8 +105,8 @@
%% Description: Initialization before each test case.
%%--------------------------------------------------------------------
init_per_testcase(Case, Config) ->
- Ref = ?config(con_ref, Config),
- TableName = ?config(table_name, Config),
+ Ref = proplists:get_value(con_ref, Config),
+ TableName = proplists:get_value(table_name, Config),
ok = db:create_table(Ref, TableName, table_type(Case)),
Config.
@@ -121,8 +121,8 @@
%% Description: Cleanup after each test case.
%%--------------------------------------------------------------------
end_per_testcase(_Case, Config) ->
- Ref = ?config(con_ref, Config),
- TableName = ?config(table_name, Config),
+ Ref = proplists:get_value(con_ref, Config),
+ TableName = proplists:get_value(table_name, Config),
ok = db:delete_table(Ref, TableName),
ok.
@@ -154,8 +154,8 @@
insert_and_lookup(Key, Value, Config) ->
- Ref = ?config(con_ref, Config),
- TableName = ?config(table_name, Config),
+ Ref = proplists:get_value(con_ref, Config),
+ TableName = proplists:get_value(table_name, Config),
ok = db:insert(Ref, TableName, Key, Value),
[Value] = db:lookup(Ref, TableName, Key),
ok = db:delete(Ref, TableName, Key),
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 248ef317b9..d945e0a58f 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -277,10 +277,9 @@
<seemfa marker="stdlib:proplists#get_value/2"><c>proplists:get_value/2</c></seemfa>.
Also, or alternatively, the general <seeerl marker="stdlib:lists"><c>lists</c></seeerl>
module contains useful functions. Normally, the only operations
- performed on <c>Config</c> is insert (adding a tuple to the head of the list)
- and lookup. <c>Common Test</c> provides a simple macro named <c>?config</c>,
- which returns a value of an item in <c>Config</c> given the key (exactly like
- <c>proplists:get_value</c>). Example: <c>PrivDir = ?config(priv_dir, Config)</c>.
+ performed on <c>Config</c> are insertion (adding a tuple to the head of the list)
+ and lookup. To look up a value in the config, <c>proplists:get_value</c> can
+ 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
@@ -717,7 +716,7 @@
<p>The following is an example of how to return the status from a group:</p>
<pre>
end_per_group(_Group, Config) ->
- Status = ?config(tc_group_result, Config),
+ Status = proplists:get_value(tc_group_result, Config),
case proplists:get_value(failed, Status) of
[] -> % no failed cases
{return_group_result,ok};
@@ -733,7 +732,7 @@
<p><em>Example:</em></p>
<pre>
end_per_group(group1, Config) ->
- Status = ?config(tc_group_result, Config),
+ Status = proplists:get_value(tc_group_result, Config),
Failed = proplists:get_value(failed, Status),
case lists:member({group_result,group2}, Failed) of
true ->
--
2.35.3
