table of contents
other versions
- jessie 1:17.3-dfsg-4+deb8u2
- jessie-backports 1:19.2.1+dfsg-2+deb9u1~bpo8+1
- stretch 1:19.2.1+dfsg-2+deb9u2
- testing 1:21.2.5+dfsg-1
- unstable 1:21.2.6+dfsg-1
- experimental 1:22.0~rc1+dfsg-1
ct_hooks(3erl) | Erlang Module Definition | ct_hooks(3erl) |
NAME¶
ct_hooks - A callback interface on top of Common TestDESCRIPTION¶
The Common Test Hook (henceforth called CTH) framework allows extensions of the default behaviour of Common Test by means of callbacks before and after all test suite calls. It is meant for advanced users of Common Test which want to abstract out behaviour which is common to multiple test suites. In brief, Common Test Hooks allows you to:- *
- Manipulate the runtime config before each suite configuration call
- *
- Manipulate the return of all suite configuration calls and in extension the result of the test themselves.
Note:
See the Example CTH in the User's Guide for a minimal example of a CTH.
CALLBACK FUNCTIONS¶
The following functions define the callback interface for a Common Test Hook.EXPORTS¶
Module:init(Id, Opts) -> {ok, State} | {ok, State, Priority}
Types:
Id = reference() | term()
Opts = term()
State = term()
Priority = integer()
MANDATORY
Always called before any other callback function. Use this to initiate any
common state. It should return a state for this CTH.
Id is the return value of id/1, or a reference (created
using make_ref/0) if id/1 is not implemented.
Priority is the relative priority of this hook. Hooks with a lower
priority will be executed first. If no priority is given, it will be set to 0.
For details about when init is called see scope in the User's
Guide.
Module:pre_init_per_suite(SuiteName, InitData, CTHState) -> Result
Types:
SuiteName = atom()
InitData = Config | SkipOrFail
Config = NewConfig = [{Key,Value}]
CTHState = NewCTHState = term()
Result = {Return, NewCTHState}
Return = NewConfig | SkipOrFail
SkipOrFail = {fail, Reason} | {skip, Reason}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called before init_per_suite if it exists. It typically
contains initialization/logging which needs to be done before init_per_suite
is called. If {skip,Reason} or {fail,Reason} is returned,
init_per_suite and all test cases of the suite will be skipped and Reason
printed in the overview log of the suite.
SuiteName is the name of the suite to be run.
InitData is the original config list of the test suite, or a
SkipOrFail tuple if a previous CTH has returned this.
CTHState is the current internal state of the CTH.
Return is the result of the init_per_suite function. If it is
{skip,Reason} or {fail,Reason} init_per_suite will never
be called, instead the initiation is considered to be skipped/failed
respectively. If a NewConfig list is returned, init_per_suite
will be called with that NewConfig list. See Pre Hooks in the
User's Guide for more details.
Note that this function is only called if the CTH has been added before
init_per_suite is run, see CTH Scoping in the User's Guide for
details.
Module:post_init_per_suite(SuiteName, Config, Return, CTHState) ->
Result
Types:
SuiteName = atom()
Config = [{Key,Value}]
Return = NewReturn = Config | SkipOrFail | term()
SkipOrFail = {fail, Reason} | {skip, Reason} | term()
CTHState = NewCTHState = term()
Result = {NewReturn, NewCTHState}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called after init_per_suite if it exists. It typically
contains extra checks to make sure that all the correct dependencies have been
started correctly.
Return is what init_per_suite returned, i.e. {fail,Reason},
{skip,Reason}, a Config list or a term describing how init_per_suite
failed.
NewReturn is the possibly modified return value of init_per_suite
. It is here possible to recover from a failure in init_per_suite
by returning the ConfigList with the tc_status element removed.
See Post Hooks in the User's Guide for more details.
CTHState is the current internal state of the CTH.
Note that this function is only called if the CTH has been added before or in
init_per_suite, see CTH Scoping in the User's Guide for details.
Module:pre_init_per_group(GroupName, InitData, CTHState) -> Result
Types:
GroupName = atom()
InitData = Config | SkipOrFail
Config = NewConfig = [{Key,Value}]
CTHState = NewCTHState = term()
Result = {NewConfig | SkipOrFail, NewCTHState}
SkipOrFail = {fail,Reason} | {skip, Reason}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called before init_per_group if it exists. It behaves
the same way as pre_init_per_suite, but for the init_per_group
instead.
Module:post_init_per_group(GroupName, Config, Return, CTHState) ->
Result
Types:
GroupName = atom()
Config = [{Key,Value}]
Return = NewReturn = Config | SkipOrFail | term()
SkipOrFail = {fail,Reason} | {skip, Reason}
CTHState = NewCTHState = term()
Result = {NewReturn, NewCTHState}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called after init_per_group if it exists. It behaves
the same way as post_init_per_suite, but for the
init_per_group instead.
Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) ->
Result
Types:
TestcaseName = atom()
InitData = Config | SkipOrFail
Config = NewConfig = [{Key,Value}]
CTHState = NewCTHState = term()
Result = {NewConfig | SkipOrFail, NewCTHState}
SkipOrFail = {fail,Reason} | {skip, Reason}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called before init_per_testcase if it exists. It
behaves the same way as pre_init_per_suite, but for the
init_per_testcase function instead.
Note that it is not possible to add CTH's here right now, that feature might be
added later, but it would right now break backwards compatibility.
Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) ->
Result
Types:
TestcaseName = atom()
Config = [{Key,Value}]
Return = NewReturn = Config | SkipOrFail | term()
SkipOrFail = {fail,Reason} | {skip, Reason}
CTHState = NewCTHState = term()
Result = {NewReturn, NewCTHState}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called after end_per_testcase if it exists. It behaves
the same way as post_init_per_suite, but for the
end_per_testcase function instead.
Module:pre_end_per_group(GroupName, EndData, CTHState) -> Result
Types:
GroupName = atom()
EndData = Config | SkipOrFail
Config = NewConfig = [{Key,Value}]
CTHState = NewCTHState = term()
Result = {NewConfig | SkipOrFail, NewCTHState}
SkipOrFail = {fail,Reason} | {skip, Reason}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called before end_per_group if it exists. It behaves
the same way as pre_init_per_suite, but for the end_per_group
function instead.
Module:post_end_per_group(GroupName, Config, Return, CTHState) ->
Result
Types:
GroupName = atom()
Config = [{Key,Value}]
Return = NewReturn = Config | SkipOrFail | term()
SkipOrFail = {fail,Reason} | {skip, Reason}
CTHState = NewCTHState = term()
Result = {NewReturn, NewCTHState}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called after end_per_group if it exists. It behaves the
same way as post_init_per_suite, but for the end_per_group
function instead.
Module:pre_end_per_suite(SuiteName, EndData, CTHState) -> Result
Types:
SuiteName = atom()
EndData = Config | SkipOrFail
Config = NewConfig = [{Key,Value}]
CTHState = NewCTHState = term()
Result = {NewConfig | SkipOrFail, NewCTHState}
SkipOrFail = {fail,Reason} | {skip, Reason}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called before end_per_suite if it exists. It behaves
the same way as pre_init_per_suite, but for the end_per_suite
function instead.
Module:post_end_per_suite(SuiteName, Config, Return, CTHState) ->
Result
Types:
SuiteName = atom()
Config = [{Key,Value}]
Return = NewReturn = Config | SkipOrFail | term()
SkipOrFail = {fail,Reason} | {skip, Reason}
CTHState = NewCTHState = term()
Result = {NewReturn, NewCTHState}
Key = atom()
Value = term()
Reason = term()
OPTIONAL
This function is called after end_per_suite if it exists. It behaves the
same way as post_init_per_suite, but for the end_per_suite
function instead.
Module:on_tc_fail(TestName, Reason, CTHState) -> NewCTHState
Types:
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()
OPTIONAL
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 test case fails, it is called after
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 in the tc_done event. See Event Handling in
the User's Guide for details.
Module:on_tc_skip(TestName, Reason, CTHState) -> NewCTHState
Types:
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()
OPTIONAL
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
and tc_user_skip events. See Event Handling in the User's
Guide for details.
Module:terminate(CTHState)
Types:
CTHState = term()
OPTIONAL
This function is called at the end of a CTH's scope.
Module:id(Opts) -> Id
Types:
Opts = term()
Id = term()
OPTIONAL
The Id is used to uniquely identify a CTH instance, if two CTH's return
the same Id the second CTH is ignored and subsequent calls to the CTH
will only be made to the first instance. For more information see
Installing a CTH in the User's Guide.
This function should NOT have any side effects as it might be called multiple
times by Common Test.
If not implemented the CTH will act as if this function returned a call to
make_ref/0.
common_test 1.8.2 | Ericsson AB |