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/write_test_chapter.xml | 81 +++++++++++++++++---------
1 file changed, 55 insertions(+), 26 deletions(-)
(limited to 'lib/common_test/doc/src/write_test_chapter.xml')
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.