From 6a5c264882058cf0786aba4418079b8552eea1cb Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Wed, 2 Apr 2014 02:11:43 +0200 Subject: Document changes in the CT hooks API and the event message protocol OTP-11732 --- lib/common_test/doc/src/ct_hooks.xml | 50 ++++++++++++++--------- lib/common_test/doc/src/event_handler_chapter.xml | 29 ++++++++----- lib/common_test/src/ct_framework.erl | 2 +- lib/test_server/doc/src/test_server_ctrl.xml | 11 +++-- 4 files changed, 56 insertions(+), 36 deletions(-) (limited to 'lib') diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml index 859ff9df14..cab6dfea51 100644 --- a/lib/common_test/doc/src/ct_hooks.xml +++ b/lib/common_test/doc/src/ct_hooks.xml @@ -450,12 +450,15 @@ - Module:on_tc_fail(TestcaseName, Reason, CTHState) -> + Module:on_tc_fail(TestName, Reason, CTHState) -> NewCTHState Called after the CTH scope ends - TestcaseName = init_per_suite | end_per_suite | - init_per_group | end_per_group | atom() + TestName = init_per_suite | end_per_suite | + {init_per_group,GroupName} | {end_per_group,GroupName} | + {FuncName,GroupName} | FuncName + FuncName = atom() + GroupName = atom() Reason = term() CTHState = NewCTHState = term() @@ -463,14 +466,16 @@

OPTIONAL

-

This function is called whenever a testcase fails. - It is called after the post function has been called for - the testcase which failed. i.e. - if init_per_suite fails this function is called after +

This function is called whenever a test case (or config function) + fails. It is called after the post function has been called for + the failed test case. I.e. if init_per_suite fails, this function + is called after - post_init_per_suite, and if a testcase fails it is called + post_init_per_suite, and if a test case fails, it is called after - post_end_per_testcase.

+ post_end_per_testcase. If the failed test case belongs + to a test case group, the first argument is a tuple + {FuncName,GroupName}, otherwise simply the function name.

The data which comes with the Reason follows the same format as the FailReason @@ -481,12 +486,14 @@ - Module:on_tc_skip(TestcaseName, Reason, CTHState) -> + Module:on_tc_skip(TestName, Reason, CTHState) -> NewCTHState Called after the CTH scope ends - TestcaseName = end_per_suite | {init_per_group,GroupName} | - {end_per_group,GroupName} | atom() + TestName = init_per_suite | end_per_suite | + {init_per_group,GroupName} | {end_per_group,GroupName} | + {FuncName,GroupName} | FuncName + FuncName = atom() GroupName = atom() Reason = {tc_auto_skip | tc_user_skip, term()} CTHState = NewCTHState = term() @@ -495,14 +502,17 @@

OPTIONAL

-

This function is called whenever a testcase is skipped. - It is called after the post function has been called for the - testcase which was skipped. - i.e. if init_per_group is skipped this function is called after - post_init_per_group - , and if a testcase is skipped it is called after - post_end_per_testcase - .

+

This function is called whenever a test case (or config function) + is skipped. It is called after the post function has been called + for the skipped test case. I.e. if init_per_group is skipped, this + function is called after + + post_init_per_group, and if a test case is skipped, + it is called after + + post_end_per_testcase. If the skipped test case belongs to a + test case group, the first argument is a tuple {FuncName,GroupName}, + otherwise simply the function name.

The data which comes with the Reason follows the same format as tc_auto_skip diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index 47d0ba59fb..45f01c12ec 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -227,11 +227,13 @@ - #event{name = tc_auto_skip, data = {Suite,Func,Reason}} + #event{name = tc_auto_skip, data = {Suite,TestName,Reason}}

Suite = atom(), the name of the suite.

-

Func = atom() | {end_per_group,GroupName}, the name of the test case - or configuration function.

-

GroupName = atom(), name of the group.

+

TestName = init_per_suite | end_per_suite | + {init_per_group,GroupName} | {end_per_group,GroupName} | + {FuncName,GroupName} | FuncName

+

FuncName = atom(), the name of the test case or configuration function.

+

GroupName = atom(), the name of the test case group.

Reason = {failed,FailReason} | {require_failed_in_suite0,RequireInfo}, reason for auto skipping Func.

@@ -252,21 +254,26 @@ init_per_group, a failed require in suite/0, or a failed test case in a sequence. Note that this event is never received as a result of a test case getting skipped because of init_per_testcase failing, since that information is carried with - the tc_done event. + the tc_done event. If a failed test case belongs to a test case group, the second + data element is a tuple {FuncName,GroupName}, otherwise simply the function name.

- + - #event{name = tc_user_skip, data = {Suite,Func,Comment}} + #event{name = tc_user_skip, data = {Suite,TestName,Comment}}

Suite = atom(), the name of the suite.

-

Func = atom() | {end_per_group,GroupName}, the name of the test case - or configuration function.

-

GroupName = atom(), name of the group.

+

TestName = init_per_suite | end_per_suite | + {init_per_group,GroupName} | {end_per_group,GroupName} | + {FuncName,GroupName} | FuncName

+

FuncName = atom(), the name of the test case or configuration function.

+

GroupName = atom(), the name of the test case group.

Comment = string(), reason for skipping the test case.

This event specifies that a test case has been skipped by the user. It is only ever received if the skip was declared in a test specification. Otherwise, user skip information is received as a {skipped,SkipReason} - result in the tc_done event for the test case. + result in the tc_done event for the test case. If a skipped test case belongs + to a test case group, the second data element is a tuple {FuncName,GroupName}, + otherwise simply the function name.

#event{name = test_stats, data = {Ok,Failed,Skipped}} diff --git a/lib/common_test/src/ct_framework.erl b/lib/common_test/src/ct_framework.erl index 7d577462b0..9ef917a507 100644 --- a/lib/common_test/src/ct_framework.erl +++ b/lib/common_test/src/ct_framework.erl @@ -1274,7 +1274,7 @@ report(What,Data) -> ct_util:set_testdata({What,Data}), ok; tc_start -> - %% Data = {Suite,{Func,GroupName}},LogFileName} + %% Data = {{Suite,{Func,GroupName}},LogFileName} Data1 = case Data of {{Suite,{Func,undefined}},LFN} -> {{Suite,Func},LFN}; _ -> Data diff --git a/lib/test_server/doc/src/test_server_ctrl.xml b/lib/test_server/doc/src/test_server_ctrl.xml index f4aae724e0..0cda531716 100644 --- a/lib/test_server/doc/src/test_server_ctrl.xml +++ b/lib/test_server/doc/src/test_server_ctrl.xml @@ -773,11 +773,14 @@ test_server_ctrl:cross_cover_analyse(Level,[{s1,S1LogDir},{s2,S2LogDir}])

What = tests_start, Data = {Name,NumCases}

What = loginfo, Data = [{topdir,TestRootDir},{rundir,CurrLogDir}]

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

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

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

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

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

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

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

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

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

What = framework_error, Data = {{FWMod,FWFunc},Error}

+

Note that for a test case function that doesn't belong to a group, + GroupName has value undefined, otherwise the name of the test + case group.

 -- cgit v1.2.3