aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test
diff options
context:
space:
mode:
authorPeter Andersson <[email protected]>2014-04-02 02:11:43 +0200
committerPeter Andersson <[email protected]>2014-04-02 17:22:13 +0200
commit6a5c264882058cf0786aba4418079b8552eea1cb (patch)
tree94ff8599b49c68d1a8a898a2520661fe521f880e /lib/common_test
parent61faea7ded93df8d444adf7079a7be2cc9e0f176 (diff)
downloadotp-6a5c264882058cf0786aba4418079b8552eea1cb.tar.gz
otp-6a5c264882058cf0786aba4418079b8552eea1cb.tar.bz2
otp-6a5c264882058cf0786aba4418079b8552eea1cb.zip
Document changes in the CT hooks API and the event message protocol
OTP-11732
Diffstat (limited to 'lib/common_test')
-rw-r--r--lib/common_test/doc/src/ct_hooks.xml50
-rw-r--r--lib/common_test/doc/src/event_handler_chapter.xml29
-rw-r--r--lib/common_test/src/ct_framework.erl2
3 files changed, 49 insertions, 32 deletions
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 @@
</func>
<func>
- <name>Module:on_tc_fail(TestcaseName, Reason, CTHState) -&gt;
+ <name>Module:on_tc_fail(TestName, Reason, CTHState) -&gt;
NewCTHState</name>
<fsummary>Called after the CTH scope ends</fsummary>
<type>
- <v>TestcaseName = init_per_suite | end_per_suite |
- init_per_group | end_per_group | atom()</v>
+ <v>TestName = init_per_suite | end_per_suite |
+ {init_per_group,GroupName} | {end_per_group,GroupName} |
+ {FuncName,GroupName} | FuncName</v>
+ <v>FuncName = atom()</v>
+ <v>GroupName = atom()</v>
<v>Reason = term()</v>
<v>CTHState = NewCTHState = term()</v>
</type>
@@ -463,14 +466,16 @@
<desc>
<p> OPTIONAL </p>
- <p>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
+ <p>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
<seealso marker="#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, and if a testcase fails it is called
+ post_init_per_suite</seealso>, and if a test case fails, it is called
after <seealso marker="#Module:post_end_per_testcase-4">
- post_end_per_testcase</seealso>.</p>
+ post_end_per_testcase</seealso>. If the failed test case belongs
+ to a test case group, the first argument is a tuple
+ <c>{FuncName,GroupName}</c>, otherwise simply the function name.</p>
<p>The data which comes with the Reason follows the same format as the
<seealso marker="event_handler_chapter#failreason">FailReason
@@ -481,12 +486,14 @@
</func>
<func>
- <name>Module:on_tc_skip(TestcaseName, Reason, CTHState) -&gt;
+ <name>Module:on_tc_skip(TestName, Reason, CTHState) -&gt;
NewCTHState</name>
<fsummary>Called after the CTH scope ends</fsummary>
<type>
- <v>TestcaseName = end_per_suite | {init_per_group,GroupName} |
- {end_per_group,GroupName} | atom()</v>
+ <v>TestName = init_per_suite | end_per_suite |
+ {init_per_group,GroupName} | {end_per_group,GroupName} |
+ {FuncName,GroupName} | FuncName</v>
+ <v>FuncName = atom()</v>
<v>GroupName = atom()</v>
<v>Reason = {tc_auto_skip | tc_user_skip, term()}</v>
<v>CTHState = NewCTHState = term()</v>
@@ -495,14 +502,17 @@
<desc>
<p> OPTIONAL </p>
- <p>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
- <seealso marker="#Module:post_init_per_suite-4">post_init_per_group
- </seealso>, and if a testcase is skipped it is called after
- <seealso marker="#Module:post_end_per_testcase-4">post_end_per_testcase
- </seealso>.</p>
+ <p>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
+ <seealso marker="#Module:post_init_per_group-4">
+ post_init_per_group</seealso>, and if a test case is skipped,
+ it is called after
+ <seealso marker="#Module:post_end_per_testcase-4">
+ post_end_per_testcase</seealso>. If the skipped test case belongs to a
+ test case group, the first argument is a tuple <c>{FuncName,GroupName}</c>,
+ otherwise simply the function name.</p>
<p>The data which comes with the Reason follows the same format as
<seealso marker="event_handler_chapter#tc_auto_skip">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 @@
<item>
<marker id="tc_auto_skip"></marker>
- <c>#event{name = tc_auto_skip, data = {Suite,Func,Reason}}</c>
+ <c>#event{name = tc_auto_skip, data = {Suite,TestName,Reason}}</c>
<p><c>Suite = atom()</c>, the name of the suite.</p>
- <p><c>Func = atom() | {end_per_group,GroupName}</c>, the name of the test case
- or configuration function.</p>
- <p><c>GroupName = atom()</c>, name of the group.</p>
+ <p><c>TestName = init_per_suite | end_per_suite |
+ {init_per_group,GroupName} | {end_per_group,GroupName} |
+ {FuncName,GroupName} | FuncName</c></p>
+ <p><c>FuncName = atom()</c>, the name of the test case or configuration function.</p>
+ <p><c>GroupName = atom()</c>, the name of the test case group.</p>
<p><c>Reason = {failed,FailReason} |
{require_failed_in_suite0,RequireInfo}</c>,
reason for auto skipping <c>Func</c>.</p>
@@ -252,21 +254,26 @@
<c>init_per_group</c>, a failed <c>require</c> in <c>suite/0</c>, 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 <c>init_per_testcase</c> failing, since that information is carried with
- the <c>tc_done</c> event.
+ the <c>tc_done</c> event. If a failed test case belongs to a test case group, the second
+ data element is a tuple <c>{FuncName,GroupName}</c>, otherwise simply the function name.
</p></item>
-
+
<item>
<marker id="tc_user_skip"></marker>
- <c>#event{name = tc_user_skip, data = {Suite,Func,Comment}}</c>
+ <c>#event{name = tc_user_skip, data = {Suite,TestName,Comment}}</c>
<p><c>Suite = atom()</c>, the name of the suite.</p>
- <p><c>Func = atom() | {end_per_group,GroupName}</c>, the name of the test case
- or configuration function.</p>
- <p><c>GroupName = atom()</c>, name of the group.</p>
+ <p><c>TestName = init_per_suite | end_per_suite |
+ {init_per_group,GroupName} | {end_per_group,GroupName} |
+ {FuncName,GroupName} | FuncName</c></p>
+ <p><c>FuncName = atom()</c>, the name of the test case or configuration function.</p>
+ <p><c>GroupName = atom()</c>, the name of the test case group.</p>
<p><c>Comment = string()</c>, reason for skipping the test case.</p>
<p>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 <c>{skipped,SkipReason}</c>
- result in the <c>tc_done</c> event for the test case.
+ result in the <c>tc_done</c> event for the test case. If a skipped test case belongs
+ to a test case group, the second data element is a tuple <c>{FuncName,GroupName}</c>,
+ otherwise simply the function name.
</p></item>
<item><c>#event{name = test_stats, data = {Ok,Failed,Skipped}}</c>
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