Manual | Tutorial | Standard Library | Release Notes

Release Notes

36.5
Procedures

Procedures are a means to collect some of the basic building blocks of a test-suite like events and checks into a larger, reusable structure.

Procedures can be called from any other part of the test-suite and even from different suites (see section 20.1). You can pass parameters to a procedure in the form of variable definitions (see chapter 7).

A typical example would be a procedure that selects a menu item in a menu. Its parameters could be the client name of the SUT, the name of the menu and the name of the menu item.

36.5.1
'Procedure'

A 'Procedure' is a 'Sequence' that is executed from some other place by a 'Procedure call'.

The parameters of the procedure are not defined explicitly. Instead they are a consequence of the variable references in the children of the 'Procedure'. You may want to define fallback values for some or all of the parameters in the 'Variable definitions'. In any case it is a good idea to document the required parameters in the 'Comment' attribute.

A 'Procedure' can return a value to the calling node with the help of a 'Return' node. Without such a node a 'Procedure' implicitly returns the empty string.

Contained in: 'Package', 'Procedures'

Children: Any

Execution: The 'Procedure's' variables are bound as fallback values. The child nodes are executed one by one, then the fallback values are unbound again.

Attributes:

Procedure Attributes
Figure 36.20:  'Procedure' Attributes
'Name'

A 'Procedure' is identified by its name and the names of its 'Package' ancestors, so you should assign a name with a meaning that is easy to recognize and remember.

Variable: No

Restrictions: Must not be empty or contain the characters '.' or '#'.

'Variable definitions'

Here you can define default or fallback values for the 'Procedure's' parameters (see chapter 7). Defining these values also serves as documentation and is a valuable time-saver when using the dialog to select the 'Procedure' for the 'Procedure name' attribute of a 'Procedure call'. See subsection 2.2.5 about how to work with the table.

4.2+ In case you want to re-set the order of the parameters like they are sorted in the called procedure, you can select »Re-set parameter order«.

Variable: Variable names no, values yes

Restrictions: None

'Maximum error level'

When a warning, error or exception occurs during a test run, the state of the corresponding node of the run-log is set accordingly. This state is normally propagated to the parent node in a way that ensures that the error state of a run-log node represents the worst of its child nodes' states. Using this attribute, the maximum error state that the run-log node for a sequence will propagate, can be limited.

Note This value has no effect on the way exceptions are handled. It only affects the error states of the run-log nodes and by that the exit code of QF-Test when run in batch mode (see. section 1.7). It also has no effect on the creation of compact run-logs (see command line argument -compact). The node for a sequence in which a warning, error or exception occurs is never removed from a compact log, even if the error is not propagated due to the setting of this attribute.

Variable: No

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test-suite.

Note For detailed documentation, especially for 'Test-set', 'Test-case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the Edit row button.

You can trigger a special behavior of some nodes using doctags, please see Doctags.

Variable: Yes

Restrictions: None

36.5.2
'Procedure call'

This node calls a 'Procedure' in the same or a different test-suite, meaning that execution continues in the 'Procedure'. When the 'Procedure' is finished, the value returned by the 'Procedure' is bound to the variable defined in the 'Variable for return value' attribute and execution returns to the 'Procedure call' and thus to its parent node.

The name of the 'Procedure' to call is determined by its 'Name' and the 'Names' of its 'Package' parents. These are concatenated with a dot ('.') as separator, starting with the outermost 'Package' and ending in the 'Procedure's' name. Thus to call a 'Procedure' named expandNode in a 'Package' named tree that is itself a child of a 'Package' named main, set the 'Procedure name' attribute to main.tree.expandNode.

See section 20.1 about how to call a 'Procedure' in a different test-suite.

Contained in: All kinds of sequences.

Children: None

Execution: The 'Variable definitions' of the 'Procedure call' are bound, the target 'Procedure' is determined and execution passed to it. After the 'Procedure' returns, the 'Procedure call's' variables are unbound again.

Attributes:

Procedure call Attributes
Figure 36.21:  'Procedure call' Attributes
'Name'

The full name of the 'Procedure', created from the 'Names' of its 'Package' parents and its own 'Name', joined by a dot. The button brings up a dialog in which you can select the 'Procedure' interactively. By selecting the "Copy parameters" checkbox you can adopt the 'Procedure's' default values as parameters for the 'Procedure call' node to save typing.

Variable: Yes

Restrictions: Must not be empty.

'Variable for return value'

The value returned by the 'Procedure', either through a 'Return' node or the empty string, is bound to the variable defined in this optional attribute. Additionally, the most recent return value is always available as the special variable ${qftest:return}.

Variable: Yes

Restrictions: None

'Local variable'

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing 'Procedure', 'Dependency' or 'Test-case' node. If no such binding exists, a new binding is created in the currently executing 'Procedure', 'Dependency' or 'Test-case' node or, if there is no such node, in the global bindings. See chapter 7 for a detailed explanation of variable binding and lookup.

Variable: No

Restrictions: None

'Variable definitions'

This is where you define the parameter values for the 'Procedure' (see chapter 7). See subsection 2.2.5 about how to work with the table.

Variable: Variable names no, values yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test-suite.

Note For detailed documentation, especially for 'Test-set', 'Test-case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the Edit row button.

You can trigger a special behavior of some nodes using doctags, please see Doctags.

Variable: Yes

Restrictions: None

36.5.3
'Return'

This node can be used to return from a 'Procedure' prematurely and also to pass a return value to the calling node.

From a script, the same effect can be achieved by raising a ReturnException.

Contained in: All kinds of sequences.

Children: None

Execution: A ReturnException is thrown. If it is caught by a matching 'Procedure', the 'Procedure' is terminated and the return value passed to the caller. If the node is executed outside a Procedure it will lead to an error.

Attributes:

Return Attributes
Figure 36.22:  'Return' Attributes
'Return value'

The value to return from the 'Procedure'. May be empty in which case the empty string is returned.

Variable: Yes

Restrictions: None

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Delay before/after'

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test-suite.

Note For detailed documentation, especially for 'Test-set', 'Test-case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the Edit row button.

You can trigger a special behavior of some nodes using doctags, please see Doctags.

Variable: Yes

Restrictions: None

36.5.4
'Package'

The only use of 'Packages' is to structure the 'Procedures' of a test-suite. The 'Name' of a 'Package' is part of the 'Procedure's' fully qualified name, as required by a 'Procedure call'.

Contained in: 'Package', 'Procedures'

Children: 'Package', 'Procedure'

Execution: Cannot be executed.

Attributes:

Package Attributes
Figure 36.23:  'Package' Attributes
'Name'

The name of a 'Package' is part of the identification of the 'Procedures' it contains, so you should assign a name with a meaning that is easy to recognize and remember.

Variable: No

Restrictions: Must not be empty or contain the characters '.' or '#'.

'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Border for relative calls'

This flag determines whether relative procedure calls, test calls or dependency references are allowed within that certain node. Relative calls passing that border are not allowed. If that attribute is not specified in the hierarchy, no relative calls are allowed.

Variable: No

Restrictions: None

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test-suite.

Note For detailed documentation, especially for 'Test-set', 'Test-case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the Edit row button.

You can trigger a special behavior of some nodes using doctags, please see Doctags.

Variable: Yes

Restrictions: None

36.5.5
'Procedures'

This is the root of all 'Packages' and 'Procedures'.

Contained in: Root node

Children: 'Package', 'Procedure'

Execution: Cannot be executed.

Attributes:

Packages Attributes
Figure 36.24:  'Procedures' Attributes
'QF-Test ID'

At the moment the 'QF-Test ID' attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

'Border for relative calls'

This flag determines whether relative procedure calls, test calls or dependency references are allowed within that certain node. Relative calls passing that border are not allowed. If that attribute is not specified in the hierarchy, no relative calls are allowed.

Variable: No

Restrictions: None

'Comment'

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test-suite.

Note For detailed documentation, especially for 'Test-set', 'Test-case' or 'Procedure' nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing [Alt-Return] or by clicking the Edit row button.

You can trigger a special behavior of some nodes using doctags, please see Doctags.

Variable: Yes

Restrictions: None