From dfd80f7cea795bfb3a35eaea2c0bc98960002aa2 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 19 Feb 2010 18:11:35 +0000 Subject: The R13B04 release --- lib/test_server/doc/src/test_server_ctrl.xml | 109 +++++++++++++++++++-------- 1 file changed, 76 insertions(+), 33 deletions(-) (limited to 'lib/test_server/doc/src/test_server_ctrl.xml') diff --git a/lib/test_server/doc/src/test_server_ctrl.xml b/lib/test_server/doc/src/test_server_ctrl.xml index 42c965b496..0ed5f88544 100644 --- a/lib/test_server/doc/src/test_server_ctrl.xml +++ b/lib/test_server/doc/src/test_server_ctrl.xml @@ -24,7 +24,7 @@ The Test Server Controller - Siri Hansen + Siri Hansen, Peter Andersson @@ -649,8 +649,13 @@ Optional, if not given the test server controller node Get subcases. Mod = atom() + Test suite name. Func = atom() - TestCaseList = [,SubCase] + Name of test case. + TestCaseList = [SubCase] + List of test cases. + SubCase = atom() + Name of a case.

This function is called before a test case is started. The @@ -660,36 +665,72 @@ Optional, if not given the test server controller node - init_tc(Mod,Func,Args) -> {ok,Args} - Preparation for a test case. + init_tc(Mod,Func,Args0) -> {ok,Args1} | {skip,ReasonToSkip} | {auto_skip,ReasonToSkip} | {fail,ReasonToFail} + Preparation for a test case or configuration function. Mod = atom() + Test suite name. Func = atom() - Args = [tuple()] - Normally Args = [Config] + Name of test case or configuration function. + Args0 = Args1 = [tuple()] + Normally Args = [Config] + ReasonToSkip = term() + Reason to skip the test case or configuration function. + ReasonToFail = term() + Reason to fail the test case or configuration function. -

This function is called when a test case is started. It is - called on the process executing the test case function - (Mod:Func). Typical use of this function can be to alter - the input parameters to the test case function (Args) or - to set properties for the executing process.

+

This function is called before a test case or configuration + function starts. It is called on the process executing the function + Mod:Func. Typical use of this function can be to alter + the input parameters to the test case function (Args) or + to set properties for the executing process.

+

By returning {skip,Reason}, Func gets skipped. + Func also gets skipped if {auto_skip,Reason} is returned, + but then gets an auto skipped status (rather than user skipped).

+

To fail Func immediately instead of executing it, return + {fail,ReasonToFail}.

 - end_tc(Mod,Func,Args) -> ok - Cleanup after a test case. + end_tc(Mod,Func,Status) -> ok | {fail,ReasonToFail} + Cleanup after a test case or configuration function. Mod = atom() + Test suite name. Func = atom() + Name of test case or configuration function. + Status = {Result,Args} | {TCPid,Result,Args} + The status of the test case or configuration function. + ReasonToFail = term() + Reason to fail the test case or configuration function. + Result = ok | Skip | Fail + The final result of the test case or configuration function. + TCPid = pid() + Pid of the process executing Func + Skip = {skip,SkipReason} + SkipReason = term() | {failed,{Mod,init_per_testcase,term()}} + Reason why the function was skipped. + Fail = {error,term()} | {'EXIT',term()} | {timetrap_timeout,integer()} | + {testcase_aborted,term()} | testcase_aborted_or_killed | + {failed,term()} | {failed,{Mod,end_per_testcase,term()}} + Reason why the function failed. Args = [tuple()] - Normally Args = [Config] + Normally Args = [Config] -

This function is called when a test case is completed. It is - called on the process where the test case function - (Mod:Func) was executed. Typical use of this function can - be to clean up stuff done by init_tc/3.

+

This function is called when a test case, or a configuration function, + is finished. It is normally called on the process where the function + Mod:Func has been executing, but if not, the pid of the test + case process is passed with the Status argument.

+

Typical use of the end_tc/3 function can be to clean up + after init_tc/3.

+

If Func is a test case, it is possible to analyse the value of + Result to verify that init_per_testcase/2 and + end_per_testcase/2 executed successfully.

+

It is possible with end_tc/3 to fail an otherwise successful + test case, by returning {fail,ReasonToFail}. The test case Func + will be logged as failed with the provided term as reason.

 @@ -700,37 +741,39 @@ Optional, if not given the test server controller node Data = term() -

This function is called in order to keep the framework upto - date about the progress of the test. This is useful e.g. if the - framework implements a GUI where the progress information is - constantly updated. The following can be reported: -

-

What = tests_start, Data = {Name,NumCases}

-What = tests_done, Data = {Ok,Failed,Skipped}

-What = tc_start, Data = {Mod,Func}

-What = tc_done, Data = {Mod,Func,Result}

+

This function is called in order to keep the framework up-to-date with + the progress of the test. This is useful e.g. if the + framework implements a GUI where the progress information is + constantly updated. The following can be reported: +

+

What = tests_start, Data = {Name,NumCases}

+ What = tests_done, Data = {Ok,Failed,{UserSkipped,AutoSkipped}}

+ What = tc_start, Data = {Mod,Func}

+ What = tc_done, Data = {Mod,Func,Result}

+ What = tc_user_skip, Data = {Mod,Func,Comment}

+ What = tc_auto_skip, Data = {Mod,Func,Comment}

 - error_notification(Mod, Case, Args, Error) -> ok - Inform framework of crashing testcase. + error_notification(Mod, Func, Args, Error) -> ok + Inform framework of crashing testcase or configuration function. Mod = atom() Test suite name. - Case = atom() - Name of test case function. + Func = atom() + Name of test case or configuration function. Args = [tuple()] Normally Args = [Config] Error = {Reason,Location} Reason = term() Reason for termination. - Location = unknown | [{Mod,Case,Line}] + Location = unknown | [{Mod,Func,Line}] Last known position in Mod before termination. Line = integer() Line number in file Mod.erl. -

This function is called as the result of testcase Mod:Case failing +

This function is called as the result of function Mod:Func failing with Reason at Location. The function is intended mainly to aid specific logging or error handling in the framework application. Note that for Location to have relevant values (i.e. other than unknown), -- cgit v1.2.3