Skip to content

Commit

Permalink
Merge pull request #7825 from jchristgit/remove-documentation-for-dep…
Browse files Browse the repository at this point in the history 
…recated-ct-config-macro

ct: Remove documentation for deprecated ?config
OTP-18858
  • Loading branch information
@u3s
u3s authored Nov 16, 2023
2 parents 4a01a91 + 929a906 commit 902090b
Show file tree
Hide file tree
Showing 6 changed files with 45 additions and 46 deletions.
8 changes: 4 additions & 4 deletions lib/common_test/doc/src/config_file_chapter.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -347,16 +347,16 @@

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},
{require,lm_directory}].

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>

Expand Down
15 changes: 8 additions & 7 deletions lib/common_test/doc/src/ct.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>
Expand Down
3 changes: 1 addition & 2 deletions lib/common_test/doc/src/ct_suite.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 20 additions & 20 deletions lib/common_test/doc/src/dependencies_chapter.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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...
Expand All @@ -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).

Expand Down Expand Up @@ -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
Expand All @@ -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].

Expand All @@ -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
Expand All @@ -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>
Expand Down
14 changes: 7 additions & 7 deletions lib/common_test/doc/src/example_chapter.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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),
Expand Down
11 changes: 5 additions & 6 deletions lib/common_test/doc/src/write_test_chapter.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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};
Expand All @@ -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 ->
Expand Down

0 comments on commit 902090b

Please sign in to comment.