From d67b4080fa2dd4622e7b03e60dd5ba49f76f31fb Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Fri, 30 Mar 2012 18:25:02 +0200 Subject: Document the new timetrap interface OTP-10039 --- lib/common_test/doc/src/common_test_app.xml | 28 ++++++--- lib/common_test/doc/src/write_test_chapter.xml | 81 +++++++++++++++++--------- 2 files changed, 74 insertions(+), 35 deletions(-) (limited to 'lib/common_test/doc') diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml index c7f6c7ce5c..6babdb93af 100644 --- a/lib/common_test/doc/src/common_test_app.xml +++ b/lib/common_test/doc/src/common_test_app.xml @@ -187,9 +187,13 @@ test case is allowed to execute (including init_per_testcase/2 and end_per_testcase/2). If the timetrap time is exceeded, the test case fails with reason - timetrap_timeout. If a TimeFunc function is specified, - it will be called initially and must return a value on - TimeVal format.

+ timetrap_timeout. A TimeFunc function can be used to + set a new timetrap by returning a TimeVal. It may also be + used to trigger a timetrap timeout by, at some point, returning a + value other than a TimeVal. (See the + User's Guide + for details). +

The require tag specifies configuration variables that are required by test cases (and/or configuration functions) @@ -313,9 +317,12 @@ test case is allowed to execute (including init_per_testcase/2 and end_per_testcase/2). If the timetrap time is exceeded, the test case fails with reason - timetrap_timeout. If a TimeFunc function is specified, - it will be called initially and must return a value on - TimeVal format.

+ timetrap_timeout. A TimeFunc function can be used to + set a new timetrap by returning a TimeVal. It may also be + used to trigger a timetrap timeout by, at some point, returning a + value other than a TimeVal. (See the + User's Guide + for details).

The require tag specifies configuration variables that are required by test cases (and/or configuration functions) @@ -494,9 +501,12 @@ exceeded, the test case fails with reason timetrap_timeout. init_per_testcase/2 and end_per_testcase/2 are included in the - timetrap time. If a TimeFunc function is specified, - it will be called before the test case (or init_per_testcase/2) - and must return a value on TimeVal format.

+ timetrap time. A TimeFunc function can be used to + set a new timetrap by returning a TimeVal. It may also be + used to trigger a timetrap timeout by, at some point, returning a + value other than a TimeVal. (See the + User's Guide + for details).

The require tag specifies configuration variables that are required by the test case (and/or init/end_per_testcase/2). diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml index 09f4f8ed3b..7447bb7673 100644 --- a/lib/common_test/doc/src/write_test_chapter.xml +++ b/lib/common_test/doc/src/write_test_chapter.xml @@ -872,34 +872,63 @@ Timetrap timeouts

The default time limit for a test case is 30 minutes, unless a - timetrap is specified either by the suite info function - or a test case info function. The timetrap timeout value defined - in suite/0 is the value that will be used for each test case - in the suite (as well as for the configuration functions - init_per_suite/1 and end_per_suite). A timetrap timeout - value set with the test case info function will override the value set - by suite/0, but only for that particular test case.

-

It is also possible to set/reset a timetrap during test case (or - configuration function) execution. This is done by calling - ct:timetrap/1. This function will cancel the current timetrap - and start a new one.

+ timetrap is specified either by the suite-, group-, + or test case info function. The timetrap timeout value defined by + suite/0 is the value that will be used for each test case + in the suite (as well as for the configuration functions + init_per_suite/1, end_per_suite/1, init_per_group/2, + and end_per_group/2). A timetrap value defined by + group(GroupName) overrides one defined by suite() + and will be used for each test case in group GroupName, and any + of its sub-groups. If a timetrap value is defined by group/1 + for a sub-group, it overrides that of its higher level groups. Timetrap + values set by individual test cases (by means of the test case info + function) overrides both group- and suite- level timetraps.

+ +

It is also possible to dynamically set/reset a timetrap during the + excution of a test case, or configuration function. This is done by calling + ct:timetrap/1. This function cancels the current timetrap + and starts a new one (that stays active until timeout, or end of the + current function).

+

Timetrap values can be extended with a multiplier value specified at - startup with the multiply_timetraps option. It is also possible - to let Test Server decide to scale up timetrap timeout values - automatically, e.g. if tools such as cover or trace are running during - the test. This feature is disabled by default and can be enabled with - the scale_timetraps start option.

+ startup with the multiply_timetraps option. It is also possible + to let the test server decide to scale up timetrap timeout values + automatically, e.g. if tools such as cover or trace are running during + the test. This feature is disabled by default and can be enabled with + the scale_timetraps start option.

+

If a test case needs to suspend itself for a time that also gets - multipled by multiply_timetraps, and possibly scaled up if - scale_timetraps is enabled, the function ct:sleep/1 - may be called.

-

A function (fun or MFA) may be specified as timetrap value - in the suite- and test case info function, e.g:

-

{timetrap,{test_utils,get_timetrap_value,[?MODULE,system_start]}}

-

The function will be called initially by Common Test (before execution - of the suite or the test case) and must return a time value such as an - integer (millisec), or a {SecMinOrHourTag,Time} tuple. More - information can be found in the common_test reference manual.

+ multipled by multiply_timetraps (and possibly also scaled up if + scale_timetraps is enabled), the function ct:sleep/1 + may be used (instead of e.g. timer:sleep/1).

+ +

A function (fun/0 or MFA) may be specified as + timetrap value in the suite-, group- and test case info function, as + well as argument to the ct:timetrap/1 function. Examples:

+ +

{timetrap,{my_test_utils,timetrap,[?MODULE,system_start]}}

+

ct:timetrap(fun() -> my_timetrap(TestCaseName, Config) end)

+ +

The user timetrap function may be used for two things:

+ + To act as a timetrap - the timeout is triggered when the + function returns. + To return a timetrap time value (other than a function). + +

Before execution of the timetrap function (which is performed + on a parallel, dedicated timetrap process), Common Test cancels + any previously set timer for the test case or configuration function. + When the timetrap function returns, the timeout is triggered, unless + the return value is a valid timetrap time, such as an integer, + or a {SecMinOrHourTag,Time} tuple (see the + common_test reference manual for + details). If a time value is returned, a new timetrap is started + to generate a timeout after the specified time.

+ +

The user timetrap function may of course return a time value after a delay, + and if so, the effective timetrap time is the delay time plus the + returned time.

-- cgit v1.2.3