The Procedure Builder definition file

chapter 25

Placeholders

In the definition of procedures, packages and even in the nodes of the procedures, you can use placeholders. The following table shows all placeholders and their meaning:

PlaceholderDescription
<COMPID> The QF-Test ID of the component
<COMPNAME> The name of the component
<COMPFEATURE> The feature of the component
<COMPCLASS> The recorded class of the component
<COMPTKCLASS> The toolkit specific class of the component
<COMPSYSCLASS> The system class of the component
<COMPGENCLASS> The generic class of the component
<COMPEF-name-of-extra-feature> The value of the given extra feature
<CURRENTVALUE> The current value of the component, e.g. the text of a text-field or the current selection of a combo-box etc.
<CURRENTENABLEDSTATE> The current enabled state of the component
<CURRENTSELECTEDSTATE> The current selectable state of the component
<CURRENTEDITABLESTATE> The current editable state of the component
<PCOMPID> The QF-Test ID of the parent component
<PCOMPNAME> The name of the parent component
<PCOMPFEATURE> The feature of the parent component
<PCOMPCLASS> The class of the parent component
<PCOMPEF-name-of-extrafeature> The value of the given extra feature of the parent component
<GPCOMPID> The QF-Test ID of the grandparent component
<GPCOMPNAME> The name of the grandparent component
<GPCOMPFEATURE> The feature of the grandparent component
<GPCOMPCLASS> The class of the grandparent component
<GPCOMPEF-name-of-extrafeature> The value of the given extra feature of the grandparent component
<ENGINE> The engine's name, either 'awt', 'swt', 'web' or 'fx'.
<ENGINE2> The alternative engine's name, either 'swing', 'swt', 'web' or 'fx'.
Table 54.1:  Placeholders for component procedures

For procedures of container or composite components you can also use placeholders for the child components. Please see following table for those additional variables:

VariableDescription
<CCOMPID> The QF-Test ID of the child component
<CCOMPNAME> The name of the child component
<CCOMPFEATURE> The feature of the child component
<CCOMPCLASS> The recorded class of the child component
<CCOMPTKCLASS> The toolkit class of the child component
<CCOMPSYSCLASS> The system class of the child component
<CCOMPGENCLASS> The generic class of the child component
<CCOMPEF-name-of-extrafeature> The value of the given extra feature
<CCURRENTVALUE> The current value of the child component, e.g. the text of a text-field or the current selection of a combo-box etc.
<CCURRENTENABLEDSTATE> The current enabled state of the child component
<CCURRENTSELECTEDSTATE> The current selectable state of the child component
<CCURRENTEDITABLESTATE> The current editable state of the child component
Table 54.2:  Additional placeholders for container procedures

4.1.3+54.1.1
Fallback values for placeholders

In many projects procedure and parameter names will be generated using the placeholders COMPNAME, COMPFEATURE or COMPEF-qfs:label. Those placeholders are used because readable names or meaningful labels exist. But in some cases those placeholders cannot be filled by every component, e.g. a new implemented button has no meaningful name yet or QF-Test cannot determine a useful label for a textfield. In such cases you could consider implementing resolvers but those need to be stable and robust again. Instead you can specify so called fallback values for any placeholder now. The values of those fallback definition will be used whenever the actual placeholder has no value.

You can specify them in the 'Comment' attribute of the configured 'Package' and 'Procedure' nodes. Therefore, you need to write @fallback_ and then the name of the placeholder. Afterwards you define the fallback placeholders. So, a placeholder for COMPNAME looks like @fallback_COMPNAME COMPFEATURE. You can see that the value of the placeholder COMPFEATURE will be taken into account, if no value for COMPNAME could be detected. You can also specify several fallback placeholders using a comma separated list like @fallback_COMPEF-qfs:label COMPFEATURE,COMPNAME.

Conditions for Package and Procedure Definition

You can influence the creation of packages and procedures via using the 'Comment' attribute of the 'Package' or 'Procedure' node.

Comment-AttributeDescription
@ABSOLUTECALL This doctag can be used in procedures generating procedure calls via @FORCHILDREN when you do not want QF-Test to prefix the specified procedure call by procbuilder.
@CONDITION Specifies a dedicated condition for creating packages or procedures. You can define conditions as Jython, Groovy, JavaScript or regular expression. Please see below for further details.
@EXCEPT Specifies, whether the package or the procedure should be defined for a certain class or not. This construct might be useful, if you define a package or procedure for an abstract class and the procedures should not be created for all of its descendants.
@FORCECREATION This doctag can be used in procedures generating procedure calls via @FORCHILDREN when you want QF-Test to create the procedure call once in the procedure, irrespective of child components.
@FORCHILDREN When you set this doctag for 'Procedure' nodes you can specify 'Procedure calls' in the body of the 'Procedure' where you prefix the 'Procedure name' by the class name of the child components for which the 'Procedure call' should be created. When generating the procedures, QF-Test will create the respective 'Procedure call' for each component matching the class the 'Procedure call' was prefixed with. Example: If you place a 'Procedure call' with the 'Procedure name' TextField.setText in a procedure flagged with @FORCHILDREN QF-Test will generate a 'Procedure' node with 'Procedure calls' to setText for each child component with the 'Class name' TextField.
@NOTINHERIT If this value is set, then this package or procedure is only defined for the exact class and not for its descendants.
@SUBITEM This value is only valid for menu actions up-to-now. If this flag is set, then the according package or procedure will be created for sub-items on the second level of a menu only.
@SWTSTYLE Evaluate the style attribute of a given SWT-button. This SWT specific attribute sometimes is needed because SWT distinguishes between check-boxes, buttons or radio-buttons only via the style attribute. For SWT-buttons you can define something like @SWTSTYLE=PUSH or @SWTSTYLE=RADIO for radio buttons.
Table 54.3:  Comment attributes for procedure creation

Interpretation of the Component Hierarchy

It might be interesting to make use of the component-hierarchy in the package structure. This approach allows the tester to locate the component-specific procedures quite easy. If you want to create component-hierarchy packages, you can use two placeholders in the package-names:

Hierarchy-PlaceholderDescription
<HIERARCHY> Create packages for the full component-hierarchy by using the 'QF-Test component ID'.
<HIERARCHY_NAME> Create packages for the full component-hierarchy by using the name of the component. If a component in the hierarchy has no name, the component won't get taken into account.
<HIERARCHY_FEATURE> Create packages for the full component-hierarchy by using the recorded feature of the component. If a component in the hierarchy has no feature, the component won't get taken into account.
<IHIERARCHY> Create packages only for interesting components in the component-hierarchy by using the 'QF-Test component ID'. An interesting component is a component with a feature.
<IHIERARCHY_NAME> Create packages only for interesting components in the component-hierarchy by using the name of the component. An interesting component is a component with a feature.
<IHIERARCHY_FEATURE> Create packages only for interesting components in the component-hierarchy by using the feature of the component. An interesting component is a component with a feature.
<MHIERARCHY> Create packages only for menu components in the component-hierarchy by using the 'QF-Test component ID'. It only takes components into account, which act as menu or menu item.
<MHIERARCHY_NAME> Create packages only for menu components in the component-hierarchy by using the component-name. It only takes components into account, which act as menu or menu item. If no name is set, the component will be ignored.
<MHIERARCHY_FEATURE> Create packages only for menu components in the component-hierarchy by using the component-feature. It only takes components into account, which act as menu or menu item. If no feature is set, the component will be ignored.
Table 54.4:  Hierarchy placeholders

3.4+54.4
Details about the @CONDITION tag

Using the @CONDITION tag allows you to configure, whether a dedicated node should be created or not during creation time.

Such conditions might be used to check a certain name or for appearance of a dedicated letter in the feature. If this condition is not fulfilled, the node won't be created. You can use all known placeholders, e.g. <COMPID> or <CCOMPNAME>.

Value of ConditionMeaning
@CONDITION jython "<COMPFEATURE>".startswith("abc") Here we define a Jython condition, which will create the according node, if the feature of the current component starts with 'abc'. It is possible to use any string or comparing method of Jython.
@CONDITION groovy "<COMPFEATURE>".startsWith("abc") Here we define a Groovy condition, which will create the according node, if the feature of the current component starts with 'abc'. It is possible to use any string or comparing method of Groovy.
@CONDITION javascript "<COMPFEATURE>".startsWith("abc") Here we define a JavaScript condition, which will create the according node, if the feature of the current component starts with 'abc'. It is possible to use any string or comparing method of JavaScript.
@CONDITION regexp "<COMPFEATURE>" =~ "abc.*" Here we define a regular expression, which will create the according node, if the feature of the current component starts with 'abc'. It is possible to use all capabilities of Java regular expressions.
@CONDITION regexp "<COMPFEATURE>" !~ "abc.*" Here we define a regular expression condition, which will create the according node, if the feature of the current component does not start with 'abc'. It is possible to use all capabilities of Java regular expressions.
Table 54.5:  Samples for the @CONDITION tag

If you need more than one row, you have to use a '\` at the end of the first row.