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 +- 3 files changed, 49 insertions(+), 32 deletions(-) (limited to 'lib/common_test') 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 -- cgit v1.2.3