40.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 24.1). You can pass parameters to a procedure in the form of variable definitions (see chapter 6).

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.

40.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:

		Figure 40.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 6). 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 button.

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

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

40.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 24.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:

		Figure 40.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 "Select procedure" button above the attribute 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}.

6.1+ The name of the variable shows in the test suite tree - in blue when it is a global variable, in black when it is local.

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 topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

'Variable definitions'

This is where you define the parameter values for the 'Procedure' (see chapter 6). 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 button.

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

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

40.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:

		Figure 40.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 button.

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

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

40.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:

		Figure 40.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 button.

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

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

40.5.5

'Procedures'

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

Contained in: Root node

Children:'Package', 'Procedure'

Execution: Cannot be executed.

Attributes:

		Figure 40.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 button.

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

If you enter text in the comment field of a 'Component' node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

Last update: 3/13/2024 Copyright © 1999-2024 Quality First Software GmbH