From f9a818d0378d1e7e4e91d13b7ce1208dc2d628af Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 5 Jun 2018 10:13:43 +0200 Subject: common_test: Remove EDoc documentation in internal modules --- lib/common_test/src/ct_event.erl | 8 +- lib/common_test/src/ct_framework.erl | 46 +++--- lib/common_test/src/ct_gen_conn.erl | 97 ++++++------ lib/common_test/src/ct_groups.erl | 10 +- lib/common_test/src/ct_hooks_lock.erl | 14 +- lib/common_test/src/ct_logs.erl | 249 ++++++++++++++----------------- lib/common_test/src/ct_master_event.erl | 8 +- lib/common_test/src/ct_master_logs.erl | 8 +- lib/common_test/src/ct_master_status.erl | 8 +- lib/common_test/src/ct_release_test.erl | 156 +++++++++---------- lib/common_test/src/ct_repeat.erl | 8 +- lib/common_test/src/ct_util.erl | 105 +++++-------- lib/common_test/src/cth_log_redirect.erl | 8 +- lib/common_test/src/cth_surefire.erl | 8 +- 14 files changed, 321 insertions(+), 412 deletions(-) (limited to 'lib/common_test/src') diff --git a/lib/common_test/src/ct_event.erl b/lib/common_test/src/ct_event.erl index 8b5bba7600..3689c6bc45 100644 --- a/lib/common_test/src/ct_event.erl +++ b/lib/common_test/src/ct_event.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2006-2017. All Rights Reserved. +%% Copyright Ericsson AB 2006-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,14 +18,14 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework Event Handler +%%% doc Common Test Framework Event Handler %%% -%%%

This module implements an event handler that CT uses to +%%% This module implements an event handler that CT uses to %%% handle status and progress notifications during test runs. %%% The notifications are handled locally (per node) and passed %%% on to ct_master when CT runs in distributed mode. This %%% module may be used as a template for other event handlers -%%% that can be plugged in to handle local logging and reporting.

+%%% that can be plugged in to handle local logging and reporting. -module(ct_event). -behaviour(gen_event). diff --git a/lib/common_test/src/ct_framework.erl b/lib/common_test/src/ct_framework.erl index 7f7e9ae6f9..134ae0e1cc 100644 --- a/lib/common_test/src/ct_framework.erl +++ b/lib/common_test/src/ct_framework.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2004-2017. All Rights Reserved. +%% Copyright Ericsson AB 2004-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,10 +18,10 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework callback module. +%%% Common Test Framework callback module. %%% -%%%

This module exports framework callback functions which are -%%% called from the test_server.

+%%% This module exports framework callback functions which are +%%% called from the test_server. -module(ct_framework). @@ -42,7 +42,7 @@ -define(rev(L), lists:reverse(L)). %%%----------------------------------------------------------------- -%%% @spec init_tc(Mod,Func,Args) -> {ok,NewArgs} | {error,Reason} | +%%% -spec init_tc(Mod,Func,Args) -> {ok,NewArgs} | {error,Reason} | %%% {skip,Reason} | {auto_skip,Reason} %%% Mod = atom() %%% Func = atom() @@ -50,7 +50,7 @@ %%% NewArgs = list() %%% Reason = term() %%% -%%% @doc Test server framework callback, called by the test_server +%%% Test server framework callback, called by the test_server %%% when a new test case is started. init_tc(_,{end_per_testcase_not_run,_},[Config]) -> %% Testcase is completed (skipped or failed), but end_per_testcase @@ -649,7 +649,7 @@ try_set_default(Name,Key,Info,Where) -> %%%----------------------------------------------------------------- -%%% @spec end_tc(Mod,Func,Args) -> {ok,NewArgs}| {error,Reason} | +%%% -spec end_tc(Mod,Func,Args) -> {ok,NewArgs}| {error,Reason} | %%% {skip,Reason} | {auto_skip,Reason} %%% Mod = atom() %%% Func = atom() @@ -657,7 +657,7 @@ try_set_default(Name,Key,Info,Where) -> %%% NewArgs = list() %%% Reason = term() %%% -%%% @doc Test server framework callback, called by the test_server +%%% Test server framework callback, called by the test_server %%% when a test case is finished. end_tc(Mod, Fun, Args) -> %% Have to keep end_tc/3 for backwards compatibility issues @@ -903,15 +903,15 @@ tag(_Other) -> ok. %%%----------------------------------------------------------------- -%%% @spec error_notification(Mod,Func,Args,Error) -> ok +%%% -spec error_notification(Mod,Func,Args,Error) -> ok %%% Mod = atom() %%% Func = atom() %%% Args = list() %%% Error = term() %%% -%%% @doc This function is called as the result of testcase -%%% Func in suite Mod crashing. -%%% Error specifies the reason for failing. +%%% This function is called as the result of testcase +%%% Func in suite Mod crashing. +%%% Error specifies the reason for failing. error_notification(Mod,Func,_Args,{Error,Loc}) -> ErrorSpec = case Error of {What={_E,_R},Trace} when is_list(Trace) -> @@ -1049,11 +1049,11 @@ group_or_func(Func, _Config) -> Func. %%%----------------------------------------------------------------- -%%% @spec get_suite(Mod, Func) -> Tests +%%% -spec get_suite(Mod, Func) -> Tests %%% -%%% @doc Called from test_server for every suite (Func==all) -%%% and every test case. If the former, all test cases in the suite -%%% should be returned. +%%% Called from test_server for every suite (Func==all) +%%% and every test case. If the former, all test cases in the suite +%%% should be returned. get_suite(Mod, all) -> case catch apply(Mod, groups, []) of @@ -1355,7 +1355,7 @@ end_per_group(GroupName, _) -> ok. %%%----------------------------------------------------------------- -%%% @spec report(What,Data) -> ok +%%% -spec report(What,Data) -> ok report(What,Data) -> case What of loginfo -> @@ -1519,14 +1519,14 @@ add_to_stats(Result) -> ct_util:update_testdata(stats, Update). %%%----------------------------------------------------------------- -%%% @spec warn(What) -> true | false +%%% -spec warn(What) -> true | false warn(What) when What==nodes; What==processes -> false; warn(_What) -> true. %%%----------------------------------------------------------------- -%%% @spec add_data_dir(File0, Config) -> File1 +%%% -spec add_data_dir(File0, Config) -> File1 add_data_dir(File,Config) when is_atom(File) -> add_data_dir(atom_to_list(File),Config); @@ -1545,7 +1545,7 @@ add_data_dir(File,Config) when is_list(File) -> end. %%%----------------------------------------------------------------- -%%% @spec get_logopts() -> [LogOpt] +%%% -spec get_logopts() -> [LogOpt] get_logopts() -> case ct_util:get_testdata(logopts) of undefined -> @@ -1555,12 +1555,12 @@ get_logopts() -> end. %%%----------------------------------------------------------------- -%%% @spec format_comment(Comment) -> HtmlComment +%%% -spec format_comment(Comment) -> HtmlComment format_comment(Comment) -> "" ++ Comment ++ "". %%%----------------------------------------------------------------- -%%% @spec get_html_wrapper(TestName, PrintLabel, Cwd) -> Header +%%% -spec get_html_wrapper(TestName, PrintLabel, Cwd) -> Header get_html_wrapper(TestName, PrintLabel, Cwd, TableCols) -> get_html_wrapper(TestName, PrintLabel, Cwd, TableCols, utf8). @@ -1568,6 +1568,6 @@ get_html_wrapper(TestName, PrintLabel, Cwd, TableCols, Encoding) -> ct_logs:get_ts_html_wrapper(TestName, PrintLabel, Cwd, TableCols, Encoding). %%%----------------------------------------------------------------- -%%% @spec get_log_dir() -> {ok,LogDir} +%%% -spec get_log_dir() -> {ok,LogDir} get_log_dir() -> ct_logs:get_log_dir(true). diff --git a/lib/common_test/src/ct_gen_conn.erl b/lib/common_test/src/ct_gen_conn.erl index 456bfd8bd1..1ab9946d96 100644 --- a/lib/common_test/src/ct_gen_conn.erl +++ b/lib/common_test/src/ct_gen_conn.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2003-2017. All Rights Reserved. +%% Copyright Ericsson AB 2003-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,9 +18,9 @@ %% %CopyrightEnd% %% -%%% @doc Generic connection owner process. +%%% Generic connection owner process. %%% -%%% @type handle() = pid(). A handle for using a connection implemented +%%% -type handle() = pid(). A handle for using a connection implemented %%% with ct_gen_conn.erl. -module(ct_gen_conn). @@ -48,7 +48,7 @@ ct_util_server}). %%%----------------------------------------------------------------- -%%% @spec start(Address,InitData,CallbackMod,Opts) -> +%%% -spec start(Address,InitData,CallbackMod,Opts) -> %%% {ok,Handle} | {error,Reason} %%% Name = term() %%% CallbackMod = atom() @@ -58,57 +58,52 @@ %%% Opt = {name,Name} | {use_existing_connection,boolean()} | %%% {reconnect,boolean()} | {forward_messages,boolean()} %%% -%%% @doc Open a connection and start the generic connection owner process. +%%% Open a connection and start the generic connection owner process. %%% -%%%

The CallbackMod is a specific callback module for +%%% The CallbackMod is a specific callback module for %%% each type of connection (e.g. telnet, ftp,...). It must export the -%%% function init/3 which takes the arguments -%%% Name, Addresse) and -%%% InitData and returna -%%% {ok,ConnectionPid,State} or -%%% {error,Reason}.

+%%% function init/3 which takes the arguments +%%% Name, Addresse) and +%%% InitData and returna +%%% {ok,ConnectionPid,State} or +%%% {error,Reason}. %%% -%%% If no name is given, the Name argument in init/3 will -%%% have the value undefined. +%%% If no name is given, the Name argument in init/3 will +%%% have the value undefined. %%% %%% The callback modules must also export -%%% ``` +%%% %%% handle_msg(Msg,From,State) -> {reply,Reply,State} | %%% {noreply,State} | %%% {stop,Reply,State} %%% terminate(ConnectionPid,State) -> term() %%% close(Handle) -> term() -%%% ''' %%% -%%% The close/1 callback function is actually a callback +%%% The close/1 callback function is actually a callback %%% for ct_util, for closing registered connections when -%%% ct_util_server is terminated. Handle is the Pid of +%%% ct_util_server is terminated. Handle is the Pid of %%% the ct_gen_conn process. %%% -%%% If option reconnect is true, then the +%%% If option reconnect is true, then the %%% callback must also export -%%% ``` +%%% %%% reconnect(Address,State) -> {ok,ConnectionPid,State} -%%% ''' %%% -%%% If option forward_messages is true, then +%%% If option forward_messages is true, then %%% the callback must also export -%%% ``` +%%% %%% handle_msg(Msg,State) -> {noreply,State} | {stop,State} -%%% ''' %%% %%% An old interface still exists. This is used by ct_telnet, ct_ftp %%% and ct_ssh. The start function then has an explicit -%%% Name argument, and no Opts argument. The +%%% Name argument, and no Opts argument. The %%% callback must export: %%% -%%% ``` %%% init(Name,Address,InitData) -> {ok,ConnectionPid,State} %%% handle_msg(Msg,State) -> {Reply,State} %%% reconnect(Address,State) -> {ok,ConnectionPid,State} %%% terminate(ConnectionPid,State) -> term() %%% close(Handle) -> term() -%%% ''' %%% start(Address,InitData,CallbackMod,Opts) when is_list(Opts) -> do_start(Address,InitData,CallbackMod,Opts); @@ -116,73 +111,73 @@ start(Name,Address,InitData,CallbackMod) -> do_start(Address,InitData,CallbackMod,[{name,Name},{old,true}]). %%%----------------------------------------------------------------- -%%% @spec stop(Handle) -> ok +%%% -spec stop(Handle) -> ok %%% Handle = handle() %%% -%%% @doc Close the connection and stop the process managing it. +%%% Close the connection and stop the process managing it. stop(Handle) -> call(Handle,stop,5000). %%%----------------------------------------------------------------- -%%% @spec get_conn_pid(Handle) -> ok +%%% -spec get_conn_pid(Handle) -> ok %%% Handle = handle() %%% -%%% @doc Return the connection pid associated with Handle +%%% Return the connection pid associated with Handle get_conn_pid(Handle) -> call(Handle,get_conn_pid). %%%----------------------------------------------------------------- -%%% @spec log(Heading,Format,Args) -> ok +%%% -spec log(Heading,Format,Args) -> ok %%% -%%% @doc Log activities on the current connection (tool-internal use only). -%%% @see ct_logs:log/3 +%%% Log activities on the current connection (tool-internal use only). +%%% See ct_logs:log/3 log(Heading,Format,Args) -> log(log,[Heading,Format,Args]). %%%----------------------------------------------------------------- -%%% @spec start_log(Heading) -> ok +%%% -spec start_log(Heading) -> ok %%% -%%% @doc Log activities on the current connection (tool-internal use only). -%%% @see ct_logs:start_log/1 +%%% Log activities on the current connection (tool-internal use only). +%%% See ct_logs:start_log/1 start_log(Heading) -> log(start_log,[Heading]). %%%----------------------------------------------------------------- -%%% @spec cont_log(Format,Args) -> ok +%%% -spec cont_log(Format,Args) -> ok %%% -%%% @doc Log activities on the current connection (tool-internal use only). -%%% @see ct_logs:cont_log/2 +%%% Log activities on the current connection (tool-internal use only). +%%% See ct_logs:cont_log/2 cont_log(Format,Args) -> log(cont_log,[Format,Args]). %%%----------------------------------------------------------------- -%%% @spec cont_log_no_timestamp(Format,Args) -> ok +%%% -spec cont_log_no_timestamp(Format,Args) -> ok %%% -%%% @doc Log activities on the current connection (tool-internal use only). -%%% @see ct_logs:cont_log/2 +%%% Log activities on the current connection (tool-internal use only). +%%% See ct_logs:cont_log/2 cont_log_no_timestamp(Format,Args) -> log(cont_log_no_timestamp,[Format,Args]). %%%----------------------------------------------------------------- -%%% @spec end_log() -> ok +%%% -spec end_log() -> ok %%% -%%% @doc Log activities on the current connection (tool-internal use only). -%%% @see ct_logs:end_log/0 +%%% Log activities on the current connection (tool-internal use only). +%%% See ct_logs:end_log/0 end_log() -> log(end_log,[]). %%%----------------------------------------------------------------- -%%% @spec do_within_time(Fun,Timeout) -> FunResult | {error,Reason} +%%% -spec do_within_time(Fun,Timeout) -> FunResult | {error,Reason} %%% Fun = function() %%% Timeout = integer() %%% -%%% @doc Execute a function within a limited time (tool-internal use only). +%%% Execute a function within a limited time (tool-internal use only). %%% -%%%

Execute the given Fun, but interrupt if it takes -%%% more than Timeout milliseconds.

+%%% Execute the given Fun, but interrupt if it takes +%%% more than Timeout milliseconds. %%% -%%%

The execution is also interrupted if the connection is -%%% closed.

+%%% The execution is also interrupted if the connection is +%%% closed. do_within_time(Fun,Timeout) -> Self = self(), Silent = get(silent), diff --git a/lib/common_test/src/ct_groups.erl b/lib/common_test/src/ct_groups.erl index 2235365a0e..d867069dce 100644 --- a/lib/common_test/src/ct_groups.erl +++ b/lib/common_test/src/ct_groups.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2004-2017. All Rights Reserved. +%% Copyright Ericsson AB 2004-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,11 +18,9 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework callback module. -%%% -%%%

This module contains CT internal help functions for searching -%%% through groups specification trees and producing resulting -%%% tests.

+%%% This module contains CT internal help functions for searching +%%% through groups specification trees and producing resulting +%%% tests. -module(ct_groups). diff --git a/lib/common_test/src/ct_hooks_lock.erl b/lib/common_test/src/ct_hooks_lock.erl index a82be288e1..be50a33e01 100644 --- a/lib/common_test/src/ct_hooks_lock.erl +++ b/lib/common_test/src/ct_hooks_lock.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2004-2016. All Rights Reserved. +%% Copyright Ericsson AB 2004-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,11 +18,6 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework test execution control module. -%%% -%%%

This module is a proxy for calling and handling locks in -%%% common test hooks.

- -module(ct_hooks_lock). -behaviour(gen_server). @@ -42,7 +37,6 @@ %%% API %%%=================================================================== -%% @doc Starts the server start(Id) -> case gen_server:start({local, ?SERVER}, ?MODULE, Id, []) of {error,{already_started, Pid}} -> @@ -76,12 +70,10 @@ release() -> %%% gen_server callbacks %%%=================================================================== -%% @doc Initiates the server init(Id) -> ct_util:mark_process(), {ok, #state{ id = Id }}. -%% @doc Handling call messages handle_call({stop,Id}, _From, #state{ id = Id, requests = Reqs } = State) -> _ = [gen_server:reply(Req, locker_stopped) || {Req,_ReqId} <- Reqs], {stop, normal, stopped, State}; @@ -108,11 +100,9 @@ handle_call({release, Pid}, _From, handle_call({release, _Pid}, _From, State) -> {reply, not_locked, State}. -%% @doc Handling cast messages handle_cast(_Msg, State) -> {noreply, State}. -%% @doc Handling all non call/cast messages handle_info({'DOWN',Ref,process,Pid,_}, #state{ locked = {true, Pid, Ref}, requests = [{NextFrom,NextPid}|Rest] } = State) -> @@ -121,11 +111,9 @@ handle_info({'DOWN',Ref,process,Pid,_}, {noreply,State#state{ locked = {true, NextPid, NextRef}, requests = Rest } }. -%% @doc This function is called by a gen_server when it is about to terminate. terminate(_Reason, _State) -> ok. -%% @doc Convert process state when code is changed code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/lib/common_test/src/ct_logs.erl b/lib/common_test/src/ct_logs.erl index 9861b1e521..07a1693d5d 100644 --- a/lib/common_test/src/ct_logs.erl +++ b/lib/common_test/src/ct_logs.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2003-2017. All Rights Reserved. +%% Copyright Ericsson AB 2003-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,14 +18,12 @@ %% %CopyrightEnd% %% -%%% @doc Logging functionality for Common Test Framework. +%%% Logging functionality for Common Test Framework. %%% -%%%

This module implements -%%%

    -%%%
  • Internal logging of activities in Common Test Framework
    • -%%%
  • Compilation of test results into index pages on several levels
    • -%%%
-%%%

+%%% This module implements: +%%% +%%% Internal logging of activities in Common Test Framework, and +%%% Compilation of test results into index pages on several levels -module(ct_logs). @@ -84,17 +82,17 @@ tests = []}). %%%----------------------------------------------------------------- -%%% @spec init(Mode, Verbosity) -> Result +%%% -spec init(Mode, Verbosity) -> Result %%% Mode = normal | interactive %%% Result = {StartTime,LogDir} %%% StartTime = term() %%% LogDir = string() %%% -%%% @doc Initiate the logging mechanism (tool-internal use only). +%%% Initiate the logging mechanism (tool-internal use only). %%% -%%%

This function is called by ct_util.erl when testing is -%%% started. A new directory named ct_run.<timestamp> is created -%%% and all logs are stored under this directory.

+%%% This function is called by ct_util.erl when testing is +%%% started. A new directory named ct_run. is created +%%% and all logs are stored under this directory. %%% init(Mode, Verbosity) -> Self = self(), @@ -129,9 +127,9 @@ datestr_from_dirname([]) -> "". %%%----------------------------------------------------------------- -%%% @spec close(Info, StartDir) -> ok +%%% -spec close(Info, StartDir) -> ok %%% -%%% @doc Create index pages with test results and close the CT Log +%%% Create index pages with test results and close the CT Log %%% (tool-internal use only). close(Info, StartDir) -> %% close executes on the ct_util process, not on the logger process @@ -204,22 +202,22 @@ close(Info, StartDir) -> ok. %%%----------------------------------------------------------------- -%%% @spec set_stylesheet(TC,SSFile) -> ok +%%% -spec set_stylesheet(TC,SSFile) -> ok set_stylesheet(TC, SSFile) -> cast({set_stylesheet,TC,SSFile}). %%%----------------------------------------------------------------- -%%% @spec clear_stylesheet(TC) -> ok +%%% -spec clear_stylesheet(TC) -> ok clear_stylesheet(TC) -> cast({clear_stylesheet,TC}). %%%----------------------------------------------------------------- -%%% @spec get_log_dir() -> {ok,Dir} | {error,Reason} +%%% -spec get_log_dir() -> {ok,Dir} | {error,Reason} get_log_dir() -> get_log_dir(false). %%%----------------------------------------------------------------- -%%% @spec get_log_dir(ReturnAbsName) -> {ok,Dir} | {error,Reason} +%%% -spec get_log_dir(ReturnAbsName) -> {ok,Dir} | {error,Reason} get_log_dir(ReturnAbsName) -> case call({get_log_dir,ReturnAbsName}) of {error,does_not_exist} when ReturnAbsName == true -> @@ -278,58 +276,58 @@ get_format_args(Content) -> end, Content). %%%----------------------------------------------------------------- -%%% @spec init_tc(RefreshLog) -> ok +%%% -spec init_tc(RefreshLog) -> ok %%% -%%% @doc Test case initiation (tool-internal use only). +%%% Test case initiation (tool-internal use only). %%% -%%%

This function is called by ct_framework:init_tc/3

+%%% This function is called by ct_framework:init_tc/3 init_tc(RefreshLog) -> call({init_tc,self(),group_leader(),RefreshLog}), tc_io_format(group_leader(), xhtml("", "
"), []), ok. %%%----------------------------------------------------------------- -%%% @spec end_tc(TCPid) -> ok +%%% -spec end_tc(TCPid) -> ok %%% -%%% @doc Test case clean up (tool-internal use only). +%%% Test case clean up (tool-internal use only). %%% -%%%

This function is called by ct_framework:end_tc/3

+%%% This function is called by ct_framework:end_tc/3 end_tc(TCPid) -> %% use call here so that the TC process will wait and receive %% possible exit signals from ct_logs before end_tc returns ok call({end_tc,TCPid}). %%%----------------------------------------------------------------- -%%% @spec register_groupleader(Pid,GroupLeader) -> ok +%%% -spec register_groupleader(Pid,GroupLeader) -> ok %%% -%%% @doc To enable logging to a group leader (tool-internal use only). +%%% To enable logging to a group leader (tool-internal use only). %%% -%%%

This function is called by ct_framework:report/2

+%%% This function is called by ct_framework:report/2 register_groupleader(Pid,GroupLeader) -> call({register_groupleader,Pid,GroupLeader}), ok. %%%----------------------------------------------------------------- -%%% @spec unregister_groupleader(Pid) -> ok +%%% -spec unregister_groupleader(Pid) -> ok %%% -%%% @doc To disable logging to a group leader (tool-internal use only). +%%% To disable logging to a group leader (tool-internal use only). %%% -%%%

This function is called by ct_framework:report/2

+%%% This function is called by ct_framework:report/2 unregister_groupleader(Pid) -> call({unregister_groupleader,Pid}), ok. %%%----------------------------------------------------------------- -%%% @spec log(Heading,Format,Args) -> ok +%%% -spec log(Heading,Format,Args) -> ok %%% -%%% @doc Log internal activity (tool-internal use only). +%%% Log internal activity (tool-internal use only). %%% -%%%

This function writes an entry to the currently active log, -%%% i.e. either the CT log or a test case log.

+%%% This function writes an entry to the currently active log, +%%% i.e. either the CT log or a test case log. %%% -%%%

Heading is a short string indicating what type of -%%% activity it is. Format and Args is the -%%% data to log (as in io:format(Format,Args)).

+%%% Heading is a short string indicating what type of +%%% activity it is. Format and Args is the +%%% data to log (as in io:format(Format,Args)). log(Heading,Format,Args) -> cast({log,sync,self(),group_leader(),ct_internal,?MAX_IMPORTANCE, [{hd,int_header(),[log_timestamp(?now),Heading]}, @@ -339,32 +337,29 @@ log(Heading,Format,Args) -> ok. %%%----------------------------------------------------------------- -%%% @spec start_log(Heading) -> ok +%%% -spec start_log(Heading) -> ok %%% -%%% @doc Starts the logging of an activity (tool-internal use only). +%%% Starts the logging of an activity (tool-internal use only). %%% -%%%

This function must be used in combination with -%%% cont_log/2 and end_log/0. The intention -%%% is to call start_log once, then cont_log -%%% any number of times and finally end_log once.

+%%% This function must be used in combination with +%%% cont_log/2 and end_log/0. The intention +%%% is to call start_log once, then cont_log +%%% any number of times and finally end_log once. %%% -%%%

For information about the parameters, see log/3.

+%%% For information about the parameters, see log/3. %%% -%%% @see log/3 -%%% @see cont_log/2 -%%% @see end_log/0 +%%% See log/3, cont_log/2, and end_log/0. start_log(Heading) -> cast({log,sync,self(),group_leader(),ct_internal,?MAX_IMPORTANCE, [{hd,int_header(),[log_timestamp(?now),Heading]}],false}), ok. %%%----------------------------------------------------------------- -%%% @spec cont_log(Format,Args) -> ok +%%% -spec cont_log(Format,Args) -> ok %%% -%%% @doc Adds information about an activity (tool-internal use only). +%%% Adds information about an activity (tool-internal use only). %%% -%%% @see start_log/1 -%%% @see end_log/0 +%%% See start_log/1 and end_log/0. cont_log([],[]) -> ok; cont_log(Format,Args) -> @@ -374,12 +369,11 @@ cont_log(Format,Args) -> ok. %%%----------------------------------------------------------------- -%%% @spec cont_log_no_timestamp(Format,Args) -> ok +%%% -spec cont_log_no_timestamp(Format,Args) -> ok %%% -%%% @doc Adds information about an activity (tool-internal use only). +%%% Adds information about an activity (tool-internal use only). %%% -%%% @see start_log/1 -%%% @see end_log/0 +%%% See start_log/1 and end_log/0. cont_log_no_timestamp([],[]) -> ok; cont_log_no_timestamp(Format,Args) -> @@ -388,12 +382,11 @@ cont_log_no_timestamp(Format,Args) -> ok. %%%----------------------------------------------------------------- -%%% @spec end_log() -> ok +%%% -spec end_log() -> ok %%% -%%% @doc Ends the logging of an activity (tool-internal use only). +%%% Ends the logging of an activity (tool-internal use only). %%% -%%% @see start_log/1 -%%% @see cont_log/2 +%%% See start_log/1 and cont_log/2. end_log() -> cast({log,sync,self(),group_leader(),ct_internal,?MAX_IMPORTANCE, [{ft,int_footer(), []}],false}), @@ -401,15 +394,15 @@ end_log() -> %%%----------------------------------------------------------------- -%%% @spec add_external_logs(Logs) -> ok +%%% -spec add_external_logs(Logs) -> ok %%% Logs = [Log] %%% Log = string() %%% -%%% @doc Print a link to each given Log in the test case +%%% Print a link to each given Log in the test case %%% log. %%% -%%%

The given Logs must exist in the priv dir of the -%%% calling test suite.

+%%% The given Logs must exist in the priv dir of the +%%% calling test suite. add_external_logs(Logs) -> start_log("External Logs"), [cont_log("~ts\n", @@ -417,12 +410,12 @@ add_external_logs(Logs) -> end_log(). %%%----------------------------------------------------------------- -%%% @spec add_link(Heading,File,Type) -> ok +%%% -spec add_link(Heading,File,Type) -> ok %%% Heading = string() %%% File = string() %%% Type = string() %%% -%%% @doc Print a link to a given file stored in the priv_dir of the +%%% Print a link to a given file stored in the priv_dir of the %%% calling test suite. add_link(Heading,File,Type) -> log(Heading,"~ts\n", @@ -430,25 +423,25 @@ add_link(Heading,File,Type) -> %%%----------------------------------------------------------------- -%%% @spec tc_log(Category,Format,Args) -> ok -%%% @equiv tc_log(Category,?STD_IMPORTANCE,Format,Args) +%%% -spec tc_log(Category,Format,Args) -> ok +%%% Equivalent to tc_log(Category,?STD_IMPORTANCE,Format,Args) tc_log(Category,Format,Args) -> tc_log(Category,?STD_IMPORTANCE,"User",Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_log(Category,Importance,Format,Args) -> ok -%%% @equiv tc_log(Category,Importance,"User",Format,Args) +%%% -spec tc_log(Category,Importance,Format,Args) -> ok +%%% Equivalent to tc_log(Category,Importance,"User",Format,Args) tc_log(Category,Importance,Format,Args) -> tc_log(Category,Importance,"User",Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_log(Category,Importance,Format,Args) -> ok -%%% @equiv tc_log(Category,Importance,"User",Format,Args) +%%% -spec tc_log(Category,Importance,Format,Args) -> ok +%%% Equivalent to tc_log(Category,Importance,"User",Format,Args) tc_log(Category,Importance,Format,Args,Opts) -> tc_log(Category,Importance,"User",Format,Args,Opts). %%%----------------------------------------------------------------- -%%% @spec tc_log(Category,Importance,Heading,Format,Args,Opts) -> ok +%%% -spec tc_log(Category,Importance,Heading,Format,Args,Opts) -> ok %%% Category = atom() %%% Importance = integer() %%% Heading = string() @@ -456,11 +449,11 @@ tc_log(Category,Importance,Format,Args,Opts) -> %%% Args = list() %%% Opts = list() %%% -%%% @doc Printout from a testcase. +%%% Printout from a testcase. %%% -%%%

This function is called by ct when logging +%%% This function is called by ct when logging %%% stuff directly from a testcase (i.e. not from within the CT -%%% framework).

+%%% framework). tc_log(Category,Importance,Heading,Format,Args,Opts) -> Data = case lists:member(no_css, Opts) of @@ -481,26 +474,26 @@ tc_log(Category,Importance,Heading,Format,Args,Opts) -> ok. %%%----------------------------------------------------------------- -%%% @spec tc_log_async(Category,Format,Args) -> ok -%%% @equiv tc_log_async(Category,?STD_IMPORTANCE,"User",Format,Args) +%%% -spec tc_log_async(Category,Format,Args) -> ok +%%% Equivalent to tc_log_async(Category,?STD_IMPORTANCE,"User",Format,Args) tc_log_async(Category,Format,Args) -> tc_log_async(Category,?STD_IMPORTANCE,"User",Format,Args). %%%----------------------------------------------------------------- -%%% @spec tc_log_async(Category,Importance,Format,Args) -> ok +%%% -spec tc_log_async(Category,Importance,Format,Args) -> ok %%% Category = atom() %%% Importance = integer() %%% Heading = string() %%% Format = string() %%% Args = list() %%% -%%% @doc Internal use only. +%%% Internal use only. %%% -%%%

This function is used to perform asynchronous printouts +%%% This function is used to perform asynchronous printouts %%% towards the test server IO handler. This is necessary in order %%% to avoid deadlocks when e.g. the hook that handles SASL printouts %%% prints to the test case log file at the same time test server -%%% asks ct_logs for an html wrapper.

+%%% asks ct_logs for an html wrapper. tc_log_async(Category,Importance,Heading,Format,Args) -> cast({log,async,self(),group_leader(),Category,Importance, [{hd,div_header(Category,Heading),[]}, @@ -509,29 +502,29 @@ tc_log_async(Category,Importance,Heading,Format,Args) -> true}), ok. %%%----------------------------------------------------------------- -%%% @spec tc_print(Category,Format,Args) -%%% @equiv tc_print(Category,?STD_IMPORTANCE,Format,Args,[]) +%%% -spec tc_print(Category,Format,Args) +%%% Equivalent to tc_print(Category,?STD_IMPORTANCE,Format,Args,[]) tc_print(Category,Format,Args) -> tc_print(Category,?STD_IMPORTANCE,Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_print(Category,Importance,Format,Args) -%%% @equiv tc_print(Category,Importance,Format,Args,[]) +%%% -spec tc_print(Category,Importance,Format,Args) +%%% Equivalent to tc_print(Category,Importance,Format,Args,[]) tc_print(Category,Importance,Format,Args) -> tc_print(Category,Importance,Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_print(Category,Importance,Format,Args,Opts) -> ok +%%% -spec tc_print(Category,Importance,Format,Args,Opts) -> ok %%% Category = atom() %%% Importance = integer() %%% Format = string() %%% Args = list() %%% Opts = list() %%% -%%% @doc Console printout from a testcase. +%%% Console printout from a testcase. %%% -%%%

This function is called by ct when printing -%%% stuff from a testcase on the user console.

+%%% This function is called by ct when printing +%%% stuff from a testcase on the user console. tc_print(Category,Importance,Format,Args,Opts) -> VLvl = case ct_util:get_verbosity(Category) of undefined -> @@ -572,44 +565,44 @@ get_header(Heading) -> %%%----------------------------------------------------------------- -%%% @spec tc_pal(Category,Format,Args) -> ok -%%% @equiv tc_pal(Category,?STD_IMPORTANCE,Format,Args,[]) -> ok +%%% -spec tc_pal(Category,Format,Args) -> ok +%%% Equivalent to tc_pal(Category,?STD_IMPORTANCE,Format,Args,[]) -> ok tc_pal(Category,Format,Args) -> tc_pal(Category,?STD_IMPORTANCE,Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_pal(Category,Importance,Format,Args) -> ok -%%% @equiv tc_pal(Category,Importance,Format,Args,[]) -> ok +%%% -spec tc_pal(Category,Importance,Format,Args) -> ok +%%% Equivalent to tc_pal(Category,Importance,Format,Args,[]) -> ok tc_pal(Category,Importance,Format,Args) -> tc_pal(Category,Importance,Format,Args,[]). %%%----------------------------------------------------------------- -%%% @spec tc_pal(Category,Importance,Format,Args,Opts) -> ok +%%% -spec tc_pal(Category,Importance,Format,Args,Opts) -> ok %%% Category = atom() %%% Importance = integer() %%% Format = string() %%% Args = list() %%% Opts = list() %%% -%%% @doc Print and log from a testcase. +%%% Print and log from a testcase. %%% -%%%

This function is called by ct when logging +%%% This function is called by ct when logging %%% stuff directly from a testcase. The info is written both in the -%%% log and on the console.

+%%% log and on the console. tc_pal(Category,Importance,Format,Args,Opts) -> tc_print(Category,Importance,Format,Args,Opts), tc_log(Category,Importance,"User",Format,Args,[esc_chars|Opts]). %%%----------------------------------------------------------------- -%%% @spec ct_log(Category,Format,Args) -> ok +%%% -spec ct_log(Category,Format,Args) -> ok %%% Category = atom() %%% Format = string() %%% Args = list() %%% -%%% @doc Print to the ct framework log +%%% Print to the ct framework log %%% -%%%

This function is called by internal ct functions to -%%% force logging to the ct framework log

+%%% This function is called by internal ct functions to +%%% force logging to the ct framework log ct_log(Category,Format,Args) -> cast({ct_log,[{hd,div_header(Category),[]}, {Format,Args}, @@ -2993,13 +2986,13 @@ rm_files([]) -> ok. %%%----------------------------------------------------------------- -%%% @spec simulate() -> pid() +%%% -spec simulate() -> pid() %%% -%%% @doc Simulate the logger process. +%%% Simulate the logger process. %%% -%%%

Simulate the logger process - for use when testing code using +%%% Simulate the logger process - for use when testing code using %%% ct_logs logging mechanism without using the ct -%%% environment. (E.g. when testing code with ts)

+%%% environment. (E.g. when testing code with ts) simulate() -> cast(stop), S = self(), @@ -3027,9 +3020,7 @@ simulate_logger_loop() -> end. %%%----------------------------------------------------------------- -%%% @spec notify_and_lock_file(Files) -> ok -%%% -%%% @doc +%%% -spec notify_and_lock_file(Files) -> ok %%% notify_and_lock_file(File) -> case ct_event:is_alive() of @@ -3042,9 +3033,7 @@ notify_and_lock_file(File) -> end. %%%----------------------------------------------------------------- -%%% @spec notify_and_unlock_file(Files) -> ok -%%% -%%% @doc +%%% -spec notify_and_unlock_file(Files) -> ok %%% notify_and_unlock_file(File) -> case ct_event:is_alive() of @@ -3057,9 +3046,7 @@ notify_and_unlock_file(File) -> end. %%%----------------------------------------------------------------- -%%% @spec get_run_dirs(Dir) -> [string()] | false -%%% -%%% @doc +%%% -spec get_run_dirs(Dir) -> [string()] | false %%% get_run_dirs(Dir) -> case filelib:wildcard(filename:join(Dir, "run.[1-2]*")) of @@ -3070,9 +3057,7 @@ get_run_dirs(Dir) -> end. %%%----------------------------------------------------------------- -%%% @spec xhtml(HTML, XHTML) -> HTML | XHTML -%%% -%%% @doc +%%% -spec xhtml(HTML, XHTML) -> HTML | XHTML %%% xhtml(HTML, XHTML) when is_function(HTML), is_function(XHTML) -> @@ -3087,9 +3072,7 @@ xhtml(HTML, XHTML) -> end. %%%----------------------------------------------------------------- -%%% @spec odd_or_even() -> "odd" | "even" -%%% -%%% @doc +%%% -spec odd_or_even() -> "odd" | "even" %%% odd_or_even() -> case get(odd_or_even) of @@ -3102,9 +3085,7 @@ odd_or_even() -> end. %%%----------------------------------------------------------------- -%%% @spec basic_html() -> true | false -%%% -%%% @doc +%%% -spec basic_html() -> true | false %%% basic_html() -> case application:get_env(common_test, basic_html) of @@ -3115,9 +3096,7 @@ basic_html() -> end. %%%----------------------------------------------------------------- -%%% @spec locate_priv_file(FileName) -> PrivFile -%%% -%%% @doc +%%% -spec locate_priv_file(FileName) -> PrivFile %%% locate_priv_file(FileName) -> {ok,CWD} = file:get_cwd(), @@ -3147,13 +3126,13 @@ locate_priv_file(FileName) -> end. %%%----------------------------------------------------------------- -%%% @spec make_relative(AbsDir, Cwd) -> RelDir +%%% -spec make_relative(AbsDir, Cwd) -> RelDir %%% -%%% @doc Return directory path to File (last element of AbsDir), which -%%% is the path relative to Cwd. Examples when Cwd == "/ldisk/test/logs": -%%% make_relative("/ldisk/test/logs/run/trace.log") -> "run/trace.log" -%%% make_relative("/ldisk/test/trace.log") -> "../trace.log" -%%% make_relative("/ldisk/test/logs/trace.log") -> "trace.log" +%%% Return directory path to File (last element of AbsDir), which +%%% is the path relative to Cwd. Examples when Cwd == "/ldisk/test/logs": +%%% make_relative("/ldisk/test/logs/run/trace.log") -> "run/trace.log" +%%% make_relative("/ldisk/test/trace.log") -> "../trace.log" +%%% make_relative("/ldisk/test/logs/trace.log") -> "trace.log" make_relative(AbsDir) -> {ok,Cwd} = file:get_cwd(), make_relative(AbsDir, Cwd). @@ -3177,11 +3156,9 @@ make_relative1(DirTs, CwdTs) -> Ups ++ DirTs. %%%----------------------------------------------------------------- -%%% @spec get_ts_html_wrapper(TestName, PrintLabel, Cwd, TableCols, Encoding) +%%% -spec get_ts_html_wrapper(TestName, PrintLabel, Cwd, TableCols, Encoding) %%% -> {Mode,Header,Footer} %%% -%%% @doc -%%% get_ts_html_wrapper(TestName, PrintLabel, Cwd, TableCols, Encoding) -> get_ts_html_wrapper(TestName, undefined, PrintLabel, Cwd, TableCols, Encoding). diff --git a/lib/common_test/src/ct_master_event.erl b/lib/common_test/src/ct_master_event.erl index bd4d1efc92..a6ec5a7a75 100644 --- a/lib/common_test/src/ct_master_event.erl +++ b/lib/common_test/src/ct_master_event.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2006-2017. All Rights Reserved. +%% Copyright Ericsson AB 2006-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,13 +18,13 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework Event Handler +%%% Common Test Framework Event Handler %%% -%%%

This module implements an event handler that the CT Master +%%% This module implements an event handler that the CT Master %%% uses to handle status and progress notifications sent to the %%% master node during test runs. This module may be used as a %%% template for other event handlers that can be plugged in to -%%% handle logging and reporting on the master node.

+%%% handle logging and reporting on the master node. -module(ct_master_event). -behaviour(gen_event). diff --git a/lib/common_test/src/ct_master_logs.erl b/lib/common_test/src/ct_master_logs.erl index 1308720823..ea6f93b565 100644 --- a/lib/common_test/src/ct_master_logs.erl +++ b/lib/common_test/src/ct_master_logs.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2006-2017. All Rights Reserved. +%% Copyright Ericsson AB 2006-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,10 +18,10 @@ %% %CopyrightEnd% %% -%%% @doc Logging functionality for Common Test Master. +%%% Logging functionality for Common Test Master. %%% -%%%

This module implements a logger for the master -%%% node.

+%%% This module implements a logger for the master +%%% node. -module(ct_master_logs). -export([start/2, make_all_runs_index/0, log/3, nodedir/2, diff --git a/lib/common_test/src/ct_master_status.erl b/lib/common_test/src/ct_master_status.erl index b27fdd341e..cb01220121 100644 --- a/lib/common_test/src/ct_master_status.erl +++ b/lib/common_test/src/ct_master_status.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2006-2017. All Rights Reserved. +%% Copyright Ericsson AB 2006-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,12 +18,12 @@ %% %CopyrightEnd% %% -%%% @doc Logging functionality for Common Test Master. +%%% doc Logging functionality for Common Test Master. %%% -%%%

This module keeps a list of {Node,Status} +%%% This module keeps a list of {Node,Status} %%% tuples. It is possible to anytime during a test run get %%% a snapshot of the test status. The module is an event -%%% handler for the master event manager.

+%%% handler for the master event manager. -module(ct_master_status). -behaviour(gen_event). diff --git a/lib/common_test/src/ct_release_test.erl b/lib/common_test/src/ct_release_test.erl index 4af9afb45b..60d17f43dc 100644 --- a/lib/common_test/src/ct_release_test.erl +++ b/lib/common_test/src/ct_release_test.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2014-2017. All Rights Reserved. +%% Copyright Ericsson AB 2014-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,7 +18,7 @@ %% %CopyrightEnd% %% %%----------------------------------------------------------------- -%% @doc EXPERIMENTAL support for testing of upgrade. +%% EXPERIMENTAL support for testing of upgrade. %% %% This is a library module containing support for test of release %% related activities in one or more applications. Currenty it @@ -27,7 +27,7 @@ %% == Configuration == %% %% In order to find version numbers of applications to upgrade from, -%% `{@module}' needs to access and start old OTP +%% ct_release_test needs to access and start old OTP %% releases. A `common_test' configuration file can be used for %% specifying the location of such releases, for example: %% @@ -39,48 +39,45 @@ %% The configuration file should preferably point out the latest patch %% level on each major release. %% -%% If no such configuration file is given, {@link init/1} will return -%% `{skip,Reason}' and any attempt at running {@link upgrade/4} +%% If no such configuration file is given, init/1 will return +%% {skip,Reason} and any attempt at running upgrade/4 %% will fail. %% %% == Callback functions == %% -%% The following functions should be exported from a {@module} +%% The following functions should be exported from a ct_release_test %% callback module. %% %% All callback functions are called on the node where the upgrade is %% executed. %% -%%
-%%
Module:upgrade_init(CtData,State) -> NewState
-%%
Types: +%% Module:upgrade_init(CtData,State) -> NewState +%% Types: %% -%% CtData = {@link ct_data()}
-%% State = NewState = cb_state() +%% CtData = ct_data() +%% State = NewState = cb_state() %% %% Initialyze system before upgrade test starts. %% %% This function is called before the upgrade is started. All -%% applications given in {@link upgrade/4} are already started by +%% applications given in upgrade/4 are already started by %% the boot script, so this callback is intended for additional %% initialization, if necessary. %% -%% CtData is an opaque data structure which shall be used -%% in any call to ct_release_test inside the callback. +%% CtData is an opaque data structure which shall be used +%% in any call to ct_release_test inside the callback. %% %% Example: %% -%% ``` %% upgrade_init(CtData,State) -> %% {ok,{FromVsn,ToVsn}} = ct_release_test:get_app_vsns(CtData,myapp), -%% open_connection(State).''' -%%
+%% open_connection(State). %% -%%
Module:upgrade_upgraded(CtData,State) -> NewState
-%%
Types: +%% Module:upgrade_upgraded(CtData,State) -> NewState +%% Types: %% -%% CtData = {@link ct_data()}
-%% State = NewState = cb_state() +%% CtData = ct_data() +%% State = NewState = cb_state() %% %% Check that upgrade was successful. %% @@ -89,21 +86,19 @@ %% been made permanent. It allows application specific checks to %% ensure that the upgrade was successful. %% -%% CtData is an opaque data structure which shall be used -%% in any call to ct_release_test inside the callback. +%% CtData is an opaque data structure which shall be used +%% in any call to ct_release_test inside the callback. %% %% Example: %% -%% ``` %% upgrade_upgraded(CtData,State) -> -%% check_connection_still_open(State).''' -%%
+%% check_connection_still_open(State). %% -%%
Module:upgrade_downgraded(CtData,State) -> NewState
-%%
Types: +%% Module:upgrade_downgraded(CtData,State) -> NewState +%% Types: %% -%% CtData = {@link ct_data()}
-%% State = NewState = cb_state() +%% CtData = ct_data() +%% State = NewState = cb_state() %% %% Check that downgrade was successful. %% @@ -112,17 +107,13 @@ %% made permanent. It allows application specific checks to ensure %% that the downgrade was successful. %% -%% CtData is an opaque data structure which shall be used -%% in any call to ct_release_test inside the callback. +%% CtData is an opaque data structure which shall be used +%% in any call to ct_release_test inside the callback. %% %% Example: %% -%% ``` %% upgrade_downgraded(CtData,State) -> -%% check_connection_closed(State).''' -%%
-%%
-%% @end +%% check_connection_closed(State). %%----------------------------------------------------------------- -module(ct_release_test). @@ -152,7 +143,7 @@ Config :: config(), Result :: config() | SkipOrFail, SkipOrFail :: {skip,Reason} | {fail,Reason}. -%% @doc Initialize `{@module}'. +%% Initialize ct_release_test. %% %% This function can be called from any of the %% `init_per_*' functions in the test suite. It updates @@ -168,9 +159,8 @@ %% %% Example: %% -%% ``` %% init_per_suite(Config) -> -%% ct_release_test:init(Config).''' +%% ct_release_test:init(Config). %% init(Config) -> try init_upgrade_test() of @@ -194,47 +184,42 @@ init(Config) -> Callback :: {module(),InitState}, InitState :: cb_state(), Config :: config(). -%% @doc Test upgrade of the given application(s). +%% Test upgrade of the given application(s). %% %% This function can be called from a test case. It requires that -%% `Config' has been initialized by calling {@link -%% init/1} prior to this, for example from `init_per_suite/1'. +%% `Config' has been initialized by calling +%% init/1 prior to this, for example from `init_per_suite/1'. %% %% Upgrade tests are performed as follows: %% -%%
    -%%
  1. Figure out which OTP release to test upgrade +%% Figure out which OTP release to test upgrade %% from. Start a node running that release and find the %% application versions on that node. Terminate the -%% node.
    2. -%%
  2. Figure out all dependencies for the applications under -%% test.
    3. -%%
  3. Create a release containing the core +%% node. +%% Figure out all dependencies for the applications under +%% test. +%% Create a release containing the core %% applications `kernel', `stdlib' and `sasl' %% in addition to the application(s) under test and all %% dependencies of these. The versions of the applications %% under test will be the ones found on the OTP release to %% upgrade from. The versions of all other applications will %% be those found on the current node, i.e. the common_test -%% node. This is the "From"-release.
    4. -%%
  4. Create another release containing the same +%% node. This is the "From"-release. +%% Create another release containing the same %% applications as in the previous step, but with all %% application versions taken from the current node. This is -%% the "To"-release.
    5. -%%
  5. Install the "From"-release and start a new node -%% running this release.
    6. -%%
  6. Perform the upgrade test and allow customized +%% the "To"-release. +%% Install the "From"-release and start a new node +%% running this release. +%% Perform the upgrade test and allow customized %% control by using callbacks: -%%
      -%%
    1. Callback: `upgrade_init/2'
      2. -%%
    2. Unpack the new release
      3. -%%
    3. Install the new release
      4. -%%
    4. Callback: `upgrade_upgraded/2'
      5. -%%
    5. Install the original release
      6. -%%
    6. Callback: `upgrade_downgraded/2'
      7. -%%
    -%%
    7. -%%
+%% Callback: `upgrade_init/2' +%% Unpack the new release +%% Install the new release +%% Callback: `upgrade_upgraded/2' +%% Install the original release +%% Callback: `upgrade_downgraded/2' %% %% `App' or `Apps' %% specifies the applications under test, i.e. the applications @@ -244,27 +229,25 @@ init(Config) -> %% %% `Level' specifies which OTP release to %% pick the "From" versions from. -%%
-%%
major
-%%
From verions are picked from the previous major +%% major +%% From verions are picked from the previous major %% release. For example, if the test is run on an OTP-17 -%% node, `{@module}' will pick the application +%% node, ct_release_test will pick the application %% "From" versions from an OTP installation running OTP -%% R16B.
+%% R16B. %% -%%
minor
-%%
From verions are picked from the current major +%% minor +%% From verions are picked from the current major %% release. For example, if the test is run on an OTP-17 -%% node, `{@module}' will pick the application +%% node, ct_release_test will pick the application %% "From" versions from an OTP installation running an -%% earlier patch level of OTP-17.
-%%
+%% earlier patch level of OTP-17. %% %% The application "To" versions are allways picked from the %% current node, i.e. the common_test node. %% %% `Callback' specifies the module (normally the -%% test suite) which implements the {@section Callback functions}, and +%% test suite) which implements the Callback functions, and %% the initial value of the `State' variable used in these %% functions. %% @@ -273,10 +256,8 @@ init(Config) -> %% %% Example: %% -%% ``` %% minor_upgrade(Config) -> %% ct_release_test:upgrade(ssl,minor,{?MODULE,[]},Config). -%% ''' %% upgrade(App,Level,Callback,Config) when is_atom(App) -> upgrade([App],Level,Callback,Config); @@ -318,10 +299,10 @@ upgrade(Apps,Level,Callback,Config) -> -spec cleanup(Config) -> Result when Config :: config(), Result :: config(). -%% @doc Clean up after tests. +%% Clean up after tests. %% %% This function shall be called from the `end_per_*' function -%% complementing the `init_per_*' function where {@link init/1} +%% complementing the `init_per_*' function where init/1 %% is called. %% %% It cleans up after the test, for example kills hanging @@ -329,9 +310,8 @@ upgrade(Apps,Level,Callback,Config) -> %% %% Example: %% -%% ``` %% end_per_suite(Config) -> -%% ct_release_test:cleanup(Config).''' +%% ct_release_test:cleanup(Config). %% cleanup(Config) -> AllNodes = [node_name(?testnode)|nodes()], @@ -352,15 +332,15 @@ cleanup(Config) -> From :: string(), To :: string(), Reason :: {app_not_found,App}. -%% @doc Get versions involved in this upgrade for the given application. +%% Get versions involved in this upgrade for the given application. %% %% This function can be called from inside any of the callback %% functions. It returns the old (From) and new (To) versions involved %% in the upgrade/downgrade test for the given application. %% -%% CtData must be the first argument received in the +%% CtData must be the first argument received in the %% calling callback function - an opaque data structure set by -%% ct_release_tests. +%% ct_release_tests. get_app_vsns(#ct_data{from=FromApps,to=ToApps},App) -> case {lists:keyfind(App,1,FromApps),lists:keyfind(App,1,ToApps)} of {{App,FromVsn,_},{App,ToVsn,_}} -> @@ -380,16 +360,16 @@ get_app_vsns(#ct_data{from=FromApps,to=ToApps},App) -> Down :: [Instr], Instr :: term(), Reason :: {app_not_found,App} | {vsn_not_found,{App,From}}. -%% @doc Get appup instructions for the given application. +%% Get appup instructions for the given application. %% %% This function can be called from inside any of the callback %% functions. It reads the appup file for the given application and %% returns the instructions for upgrade and downgrade for the versions %% in the test. %% -%% CtData must be the first argument received in the +%% CtData must be the first argument received in the %% calling callback function - an opaque data structure set by -%% ct_release_tests. +%% ct_release_tests. %% %% See reference manual for appup files for types definitions for the %% instructions. diff --git a/lib/common_test/src/ct_repeat.erl b/lib/common_test/src/ct_repeat.erl index 177ef37d1f..8b1c7d47bb 100644 --- a/lib/common_test/src/ct_repeat.erl +++ b/lib/common_test/src/ct_repeat.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2007-2017. All Rights Reserved. +%% Copyright Ericsson AB 2007-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,14 +18,14 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework module that handles repeated test runs +%%% doc Common Test Framework module that handles repeated test runs %%% -%%%

This module exports functions for repeating tests. The following +%%% This module exports functions for repeating tests. The following %%% start flags (or equivalent ct:run_test/1 options) are supported: %%% -until , StopTime = YYMoMoDDHHMMSS | HHMMSS %%% -duration , DurTime = HHMMSS %%% -force_stop [skip_rest] -%%% -repeat , N = integer()

+%%% -repeat , N = integer() -module(ct_repeat). diff --git a/lib/common_test/src/ct_util.erl b/lib/common_test/src/ct_util.erl index e904bb1e7c..d8fd401a64 100644 --- a/lib/common_test/src/ct_util.erl +++ b/lib/common_test/src/ct_util.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2003-2017. All Rights Reserved. +%% Copyright Ericsson AB 2003-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,11 +18,11 @@ %% %CopyrightEnd% %% -%%% @doc Common Test Framework Utilities. +%%% Common Test Framework Utilities. %%% -%%%

This is a support module for the Common Test Framework. It +%%% This is a support module for the Common Test Framework. It %%% implements the process ct_util_server which acts like a data -%%% holder for suite, configuration and connection data.

+%%% holder for suite, configuration and connection data. %%% -module(ct_util). @@ -83,20 +83,20 @@ %%%----------------------------------------------------------------- start() -> start(normal, ".", ?default_verbosity). -%%% @spec start(Mode) -> Pid | exit(Error) +%%% -spec start(Mode) -> Pid | exit(Error) %%% Mode = normal | interactive %%% Pid = pid() %%% -%%% @doc Start start the ct_util_server process +%%% Start start the ct_util_server process %%% (tool-internal use only). %%% -%%%

This function is called from ct_run.erl. It starts and initiates -%%% the ct_util_server

+%%% This function is called from ct_run.erl. It starts and initiates +%%% the ct_util_server %%% -%%%

Returns the process identity of the -%%% ct_util_server.

+%%% Returns the process identity of the +%%% ct_util_server. %%% -%%% @see ct +%%% See ct. start(LogDir) when is_list(LogDir) -> start(normal, LogDir, ?default_verbosity); start(Mode) -> @@ -520,19 +520,19 @@ get_key_from_name(Name)-> ct_config:get_key_from_name(Name). %%%----------------------------------------------------------------- -%%% @spec register_connection(TargetName,Address,Callback,Handle) -> +%%% -spec register_connection(TargetName,Address,Callback,Handle) -> %%% ok | {error,Reason} %%% TargetName = ct:target_name() %%% Address = term() %%% Callback = atom() %%% Handle = term %%% -%%% @doc Register a new connection (tool-internal use only). +%%% Register a new connection (tool-internal use only). %%% -%%%

This function can be called when a new connection is +%%% This function can be called when a new connection is %%% established. The connection data is stored in the connection %%% table, and ct_util will close all registered connections when the -%%% test is finished by calling Callback:close/1.

+%%% test is finished by calling Callback:close/1. register_connection(TargetName,Address,Callback,Handle) -> %% If TargetName is a registered alias for a config %% variable, use it as reference for the connection, @@ -553,28 +553,28 @@ register_connection(TargetName,Address,Callback,Handle) -> ok. %%%----------------------------------------------------------------- -%%% @spec unregister_connection(Handle) -> ok +%%% -spec unregister_connection(Handle) -> ok %%% Handle = term %%% -%%% @doc Unregister a connection (tool-internal use only). +%%% Unregister a connection (tool-internal use only). %%% -%%%

This function should be called when a registered connection is +%%% This function should be called when a registered connection is %%% closed. It removes the connection data from the connection -%%% table.

+%%% table. unregister_connection(Handle) -> ets:delete(?conn_table,Handle), ok. %%%----------------------------------------------------------------- -%%% @spec does_connection_exist(TargetName,Address,Callback) -> +%%% -spec does_connection_exist(TargetName,Address,Callback) -> %%% {ok,Handle} | false %%% TargetName = ct:target_name() %%% Address = address %%% Callback = atom() %%% Handle = term() %%% -%%% @doc Check if a connection already exists. +%%% Check if a connection already exists. does_connection_exist(TargetName,Address,Callback) -> case ct_config:get_key_from_name(TargetName) of {ok,_Key} -> @@ -594,7 +594,7 @@ does_connection_exist(TargetName,Address,Callback) -> end. %%%----------------------------------------------------------------- -%%% @spec get_connection(TargetName,Callback) -> +%%% -spec get_connection(TargetName,Callback) -> %%% {ok,Connection} | {error,Reason} %%% TargetName = ct:target_name() %%% Callback = atom() @@ -602,8 +602,8 @@ does_connection_exist(TargetName,Address,Callback) -> %%% Handle = term() %%% Address = term() %%% -%%% @doc Return the connection for Callback on the -%%% given target (TargetName). +%%% Return the connection for Callback on the +%%% given target (TargetName). get_connection(TargetName,Callback) -> %% check that TargetName is a registered alias case ct_config:get_key_from_name(TargetName) of @@ -624,7 +624,7 @@ get_connection(TargetName,Callback) -> end. %%%----------------------------------------------------------------- -%%% @spec get_connections(ConnPid) -> +%%% -spec get_connections(ConnPid) -> %%% {ok,Connections} | {error,Reason} %%% Connections = [Connection] %%% Connection = {TargetName,Handle,Callback,Address} @@ -633,8 +633,8 @@ get_connection(TargetName,Callback) -> %%% Callback = atom() %%% Address = term() %%% -%%% @doc Get data for all connections associated with a particular -%%% connection pid (see Callback:init/3). +%%% Get data for all connections associated with a particular +%%% connection pid (see Callback:init/3). get_connections(ConnPid) -> Conns = ets:tab2list(?conn_table), lists:flatmap(fun(#conn{targetref=TargetName, @@ -654,8 +654,7 @@ get_connections(ConnPid) -> end, Conns). %%%----------------------------------------------------------------- -%%% @hidden -%%% @equiv ct:get_target_name/1 +%%% Equivalent to ct:get_target_name/1 get_target_name(Handle) -> case ets:select(?conn_table,[{#conn{handle=Handle,targetref='$1',_='_'}, [], @@ -667,17 +666,14 @@ get_target_name(Handle) -> end. %%%----------------------------------------------------------------- -%%% @spec close_connections() -> ok +%%% -spec close_connections() -> ok %%% -%%% @doc Close all open connections. +%%% Close all open connections. close_connections() -> close_connections(ets:tab2list(?conn_table)), ok. %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc override_silence_all_connections() -> Protocols = [telnet,ftp,rpc,snmp,ssh], override_silence_connections(Protocols), @@ -738,12 +734,12 @@ reset_silent_connections() -> %%%----------------------------------------------------------------- -%%% @spec stop(Info) -> ok +%%% -spec stop(Info) -> ok %%% -%%% @doc Stop the ct_util_server and close all existing connections +%%% Stop the ct_util_server and close all existing connections %%% (tool-internal use only). %%% -%%% @see ct +%%% See ct. stop(Info) -> case whereis(ct_util_server) of undefined -> @@ -757,26 +753,25 @@ stop(Info) -> end. %%%----------------------------------------------------------------- -%%% @spec update_last_run_index() -> ok +%%% -spec update_last_run_index() -> ok %%% -%%% @doc Update ct_run.<timestamp>/index.html +%%% Update ct_run./index.html %%% (tool-internal use only). update_last_run_index() -> call(update_last_run_index). %%%----------------------------------------------------------------- -%%% @spec get_mode() -> Mode +%%% -spec get_mode() -> Mode %%% Mode = normal | interactive %%% -%%% @doc Return the current mode of the ct_util_server +%%% Return the current mode of the ct_util_server %%% (tool-internal use only). get_mode() -> call(get_mode). %%%----------------------------------------------------------------- -%%% @hidden -%%% @equiv ct:listenv/1 +%%% Equivalent to ct:listenv/1 listenv(Telnet) -> case ct_telnet:send(Telnet,"listenv") of ok -> @@ -790,8 +785,7 @@ listenv(Telnet) -> end. %%%----------------------------------------------------------------- -%%% @hidden -%%% @equiv ct:parse_table/1 +%%% Equivalent to ct:parse_table/1 parse_table(Data) -> {Heading, Rest} = get_headings(Data), Lines = parse_row(Rest,[],size(Heading)), @@ -831,16 +825,10 @@ remove_space([],Acc) -> %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc is_test_dir(Dir) -> lists:last(string:lexemes(filename:basename(Dir), "_")) == "test". %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc get_testdir(Dir, all) -> Abs = abs_name(Dir), case is_test_dir(Abs) of @@ -884,9 +872,6 @@ get_testdir(Dir, _) -> get_testdir(Dir, all). %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc get_attached(TCPid) -> case dbg_iserver:safe_call({get_attpid,TCPid}) of {ok,AttPid} when is_pid(AttPid) -> @@ -896,9 +881,6 @@ get_attached(TCPid) -> end. %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc kill_attached(undefined,_AttPid) -> ok; kill_attached(_TCPid,undefined) -> @@ -913,9 +895,6 @@ kill_attached(TCPid,AttPid) -> %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc warn_duplicates(Suites) -> Warn = fun(Mod) -> @@ -934,9 +913,6 @@ warn_duplicates(Suites) -> ok. %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc mark_process() -> mark_process(system). @@ -998,9 +974,6 @@ remaining_test_procs() -> {TestProcs, SharedGL, OtherGLs}. %%%----------------------------------------------------------------- -%%% @spec -%%% -%%% @doc get_profile_data() -> get_profile_data(all). diff --git a/lib/common_test/src/cth_log_redirect.erl b/lib/common_test/src/cth_log_redirect.erl index 417ea615a3..68742ab0ee 100644 --- a/lib/common_test/src/cth_log_redirect.erl +++ b/lib/common_test/src/cth_log_redirect.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2017. All Rights Reserved. +%% Copyright Ericsson AB 2011-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -19,11 +19,9 @@ %% -module(cth_log_redirect). -%%% @doc Common Test Framework functions handling test specifications. +%%% Common Test Framework functions handling test specifications. %%% -%%%

This module redirects sasl and error logger info to common test log.

-%%% @end - +%%% This module redirects sasl and error logger info to common test log. %% CTH Callbacks -export([id/1, init/2, diff --git a/lib/common_test/src/cth_surefire.erl b/lib/common_test/src/cth_surefire.erl index 4407ff56c1..b0742717ae 100644 --- a/lib/common_test/src/cth_surefire.erl +++ b/lib/common_test/src/cth_surefire.erl @@ -1,7 +1,7 @@ %%-------------------------------------------------------------------- %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2012-2017. All Rights Reserved. +%% Copyright Ericsson AB 2012-2018. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,10 +18,10 @@ %% %CopyrightEnd% %%-------------------------------------------------------------------- -%%% @doc Common Test Framework functions handling test specifications. +%%% Common Test Framework functions handling test specifications. %%% -%%%

This module creates a junit report of the test run if plugged in -%%% as a suite_callback.

+%%% This module creates a junit report of the test run if plugged in +%%% as a suite_callback. -module(cth_surefire). -- cgit v1.2.3