Timer

3.3.7 Timer

DESCRIPTION

Timer - Manage timers and timer groups. A timer allows measuring the time elapsed by a command, block of commands or a script, usually for performance testing purposes.

A typical task for a timer is to measure the time taken by an automated task or a piece of script code. This requires to create a timer and start it before the task begins and stop it at the end of the task. Timers are typically used together with the Report command which stores test results including the time data into an XML file:

Report perftesting.xml
Timer t1 start desc="My task #1 duration"
<task code>
Timer t1 stop

If the resulting XML file is viewed in a web browser, it displays a summary of script timers in the form of a simple table. For example, the script above will create:

Table of timers

The XML result file can be also reused as a source of reference data. In a typical scenario, one would execute the script above to get an XML with base timer data recorded against the application which hasn't been optimized. To verify performance improvements in later automated executions modify the script as follows:

Report perftesting2.xml
Timer load="perftesting.xml"

Timer t1 start desc="My task #1 duration"
<task code>
Timer t1 stop 

The "Timer load" command parses the input XML file and records the reference data for timers defined by the script (matching is based on timer names). Reference values may be alternatively also defined through the refvalue parameter; this allows to populate the reference data from another source, for example from an MS Excel sheet (see Excel) or a plain text or CSV file (see File). When the reference data is defined, the resulting XML will display actual timers with a comparison to the reference values as follows:

Table of timers

Important timer and timer group features:

• There's no explicit "create" command to create a timer or a timer group. Each object is created automatically when it is first specified.
• Timer and timer group names are case sensitive. For example "T1" and "t1" are two different names.
• The command accepts a single timer/group name or a comma-separated list of timers and/or groups. An object name, therefore, may not contain a comma.
• All timers and timer groups are also always global and they exist from the moment of creation until the end of script execution regardless of the place they were created at (main body, procedure, another script...).
• Timers can be started, stopped and restarted in any sequence. Restarting of a timer does not reset its value and it is treated as cumulative. To reset the timer value call the command with the "value=0" parameter.
• All running timers are stopped automatically when the script finishes.
• As the execution of scripts in GUI mode adds performance overhead (typically a few ms per measured command spent on rendering of GUI components), it is recommended to run the live scripts in CLI mode for better accuracy or timer data.

Each timer exposes its time value in milliseconds to the script in the form of a "TIMER<timerName>" variable. In the example above there will be the TIMER_t1 variable and the script may retrieve the current timer value through a variable call such as "{_TIMER_t1}". If the called variable starts with the reserved prefix of "_TIMER" but the name after it doesn't correspond to any existing timer name, it returns -1. This value may be used to test the existence of a timer.

Though timer variables can be modified through the Var or Eval commands, it has no effect on the timers themselves because their values are stored in an internal data structure. The variable is rather just a read-only copy of the internal value. To set the timer to a particular value using the value parameter.
Note that setting of a value of a running timer will stop it and to resume from the specified value the command must contain the "start" action.

For example, to make the t1 timer start from 1 second (1000ms) rather than from zero use:

Timer t1 start desc="My task duration" value="1000"

Another example shows how to create a new timer t2 with the value of timer t1 plus 1 second:

Timer t2 value="{_TIMER_t1}+1000"

As the value parameter also accepts a timer name, to create a plain copy of the t1 timer simply call:

Timer t2 value="t1"

The Timer command accepts either a single object (timer or timer group) or a comma separated list of timers (groups). To start the two timers defined above one may use:

Timer t1,t2 start

Timers may be optionally associated into groups. Grouping allows to organize timers in a logical way and perform bulk operations with them. A group should be understood as a plain list of timers equivalent to a comma-separated timer list; it has no status and it doesn't affect the appearance of test results. Grouping and ungrouping are achieved through the group and ungroup parameters which create and update groups. The following example creates two timers t1 and t2, associates them into a group called tgroup and starts/stops both timers using the group name:

Timer t1,t2 group=tgroup
Timer tgroup start
<task code>
Timer tgroup stop

To copy tgroup into a new group called tgroup2 call:

Timer tgroup group=tgroup2

One timer may be a member of multiple groups. Timers may be freely grouped or ungrouped at any time. To remove the t1 timer from both tgroup and tgroup2 use:

Timer t1 ungroup=tgroup,tgroup2

Alternatively to remove the timer from all groups use the ungroup parameter with an empty value:

Timer t1 ungroup= 

To cancel a group and remove all timers from it use the following command which should be understood as a request like "take all timers listed in group tgroup and remove them from tgroup".

Timer tgroup ungroup=tgroup

When a group name is used in the Timer command argument, it expands into a list of timers and all other operations specified by the command (start, stop, value/description setting...) are applied to each timer. The following example will create and group the two timers, set their value to 1 second (1000ms), set their description to "Performance test" and start them:

Timer t1,t2 group=tgroup
Timer tgroup start value=1000 desc="Performance test"

As you may have noticed, a single command may specify one or more operations. They are performed in the following order:

1. Resolve the argument into a list of timers and create those which do not exist yet
2. Set the value or any other attributes (such as description),
3. Ungroup if the ungroup parameter is present,
4. Group if the group parameter is present,
5. Load the reference data if the load parameter is present,
6. Start or stop the timers identified in the first step if the start or stop parameter is present.

This order allows fitting the example above into a single line of code. In terms of processing orders the command should be understood as a request like "create timers t1 and t2, set their value and description, group them into a group called tgroup and start them":

Timer t1,t2 start value=1000 desc="Performance test" group="tgroup"

SYNOPSIS

timer <name(s)> [start|stop]  [desc=<description>]  [value=<time_millis>]  [refvalue=<time_millis>]  [load=<XML_file>]  [group=<name(s)>]  [ungroup=<name(s)]
timer load=<XML_file>
* Red colour indicates obligatory parameters

OPTIONS

name(s)

- Timer or group name or a comma-separated list of names to apply the command to. A mixture of groups and timers is also allowed. If any of the specified names contains a space, the whole list must be enclosed in double-quotes. A unique name (or names) will create a new timer (timers). If the name corresponds to a group previously created by a command called with the group parameter, it is expanded into a list of timers currently present in that group.

start|stop

- Start or stop the specified timer(s) (optional). Starting of an already started timer or stopping of a stopped one has no effect and reports no error.

desc=<description>

- Optional timer description.

value=<time_millis>

- Initial timer value in milliseconds (optional). The value may refer to the name of an existing timer. The default value is zero. The setting of a value of a started timer will stop it and it is necessary to restart it.

refvalue=<time>

- Reference time value in milliseconds. Since T-Plan Robot version 3.1.2 the value may be any time value. The parameter plays no role during the script execution and it is used exclusively for reporting purposes. When the reference value is specified, the timer entry in the resulting XML file created by the Report command will contain the reference value as well as the relative difference (percentage) from the reference data. This functionality allows tracking performance changes across the testing of two application versions.

load=<XML_file>

- The parameter loads reference data from an XML file previously generated through the Report command. If the file is relative, it is resolved in the same way as the Report file (meaning against the output path specified by the _REPORT_DIR variable). The XML is parsed for timer data and if any of the timer names corresponds to a timer created in the current script, the XML timer value is set as a reference time of the current timer. Reference times as well the difference from the actually measured values are then written into the newly generated XML. See also the refvalue parameter above. Note that loading of reference data from XML has a priority over the refvalue parameter and it will overwrite its settings.

If the load operation is called from a Timer command operating over a set of timers (the first command form as is specified in the Synopsis above), it is applied just to the specified set and all other data from XML are discarded. To load reference data of all timers at once use the second command form of "Timer load=<XML_file>". As this command stores the reference data internally, and updates all already existing as well as the to-be-created timers, the global load operation may be called anywhere in the script (not necessarily at the script beginning).

group=<group(s)>

- A group or a comma-separated list of group names to associate the timer(s) with. If any of the specified group names contains a space, the whole list must be enclosed in double-quotes. A unique name (or names) will create a new group (groups). A group name may not be the same as name of an already existing timer. 

ungroup=<group(s)>

- A group or a comma-separated list of group names to remove the timer(s) from. If any of the specified group names contains a space, the whole list must be enclosed in double-quotes. If the specified timer(s) is a member of the specified group or groups, it is removed from there.

RETURNS

If the command employs the load parameter to read reference data from an XML file, it returns 0 (zero) when the XML is valid and contains at least one timer value. When the XML does not contain any timer data but the format is correct, the command returns 1 (one). If the file cannot be read or is not a valid XML file, the command returns the value of 2 (two).

Timer commands without the load parameter always return 0 (zero).

EXAMPLES

See the text above for examples.