55.6 Automatic creation of procedure call definitions

Procedure call definitions are required when you want to convert node sequences into procedure calls. They can be created automatically. To do so, select one or more procedures or packages, open the popup menu via right-click, and choose »Additional node operations«-»Create procedure call definition«.

After activating the function, the file name in which the created definitions are to be saved is requested in an input dialog, unless it is specified in the doctag @prec/definitions in the Procedures root node.

The definitions are created in the same Package structure as the corresponding procedures.

The generated definition node contains the name of the procedure. If the procedure contains no recordable nodes at all, no valid definition can be created. In this case the definition node is disabled and a corresponding note is written into its code. Any problems that occur during analysis of the procedure are reported in the comment of the definition node.

To create a definition, QF-Test analyzes the steps of the procedure one after the other and descends recursively into all relevant child nodes. It checks whether a particular node is relevant for the definition. If so, the specifications that sufficiently describe the node are transferred to the definition. It also checks whether the node contains variables that are relevant as procedure call parameters during later node conversion. These are also entered in the definition. Control structures such as If, Try, and Loop are analyzed and represented as corresponding groups in the definition. The automated process can be controlled more precisely using the doctags described in "Doctags for controlling automatic definition creation".

Note The automated creation of definition nodes is designed for node conversion directly after a recording. This means, for example, that nodes which cannot be recorded or which a user is unlikely to record are not written into the definition or are marked as optional.

55.6.1 Definition-relevant nodes

Since the automated creation of definition nodes is designed for node conversion directly after recording, only nodes that can be recorded are added to the definition. These include event nodes such as Mouse event, Text input, and Key event, as well as check nodes. Nodes that cannot be recorded or disabled nodes are skipped.

In addition, nodes can be explicitly excluded via the doctag @prec/ignore, and node sequences including their child nodes via the doctags @prec/ignore/start / @prec/ignore/end.

A procedure can be excluded from generating its own definition using @prec/duplicate, but its nodes are still expanded when the procedure is called from another procedure. With @prec/ignore, the procedure is skipped in all cases.

55.6.2 Mandatory and optional nodes

When deciding whether a node is marked mandatory or optional in the definition, the system evaluates whether a user would also manually perform the action that a node represents in a procedure. It is assumed that this is the case for mouse clicks, as long as they are not in a "Conditional structures". For input nodes, the system checks whether they contain variables in recording-relevant attributes. If so, the text input is marked as mandatory and the variable is entered as a parameter for the procedure call. If they contain no variable, they are marked as optional. The text is then entered as the expected value in the definition. Check nodes are only considered relevant if recording-relevant attributes contain variables.

This automated behavior can be overridden with "Doctags for controlling automatic definition creation": Check nodes and Wait for component to appear nodes can be unconditionally marked as relevant for the definition using the doctag @prec/addNode. To mark a single node and all its child nodes as optional, use @prec/optional, for entire node ranges use @prec/optional/start and @prec/optional/end. The end of a procedure implicitly closes an open optional range.

55.6.3 Resolving procedure calls

If the procedure contains calls to further procedures, QF-Test descends into the called procedure and adds its recordable nodes to the definition. Recursive calls are detected and skipped to avoid infinite loops. Variables passed in a procedure call are forwarded along the call hierarchy, so that the variable name ultimately used in the definition is the one visible at the level of the procedure call being defined.

55.6.4 Conditional structures

The branches of If and Try structures are translated together with their Else, Elseif, and Catch blocks into a choice group - that is, a set of alternative blocks of which one must match. Identical blocks are merged so that branches differing only in their optional flag are kept only once. If only a single block contains content relevant to the definition, that block becomes optional instead of forming a choice. The content of a Finally block is always treated as mandatory and appended after the choice group.

55.6.5 Priority

Each definition is assigned a priority (priority) with regard to the later order of definition evaluation, derived from the number of its mandatory and optional nodes (see Mapping procedure structures). This gives more specific definitions precedence over more general ones. Each mandatory node increases the priority by 10, each optional node by 1. The calculated value can be overridden or adjusted using the doctag @prec/priority, where a leading "+" or "-" adds or subtracts from the calculated value, and a plain number replaces it, see Flag for priority.

55.6.6 Using substitute procedures for generating definitions

Some procedures perform a simple action, but for some technical issues the simple action needs to be implemented in a complex way. In cases like that you can tell the automatic generator not to analyze the complex procedure, but to use a substitute procedure from which to derive the procedure call definition.

The substitute procedures need to be placed in an own test suite, in a package with the name "known procedures". The package structure within that package must correspond to the package structure of the original procedure. The substitute procedures will be used when creating a procedure call definition for the procedure itself, and also when the procedure is called from within other procedures. When a substitute procedure is used during definition creation, this is noted in the comment of the definition node. The file name is specified in the doctag @prec/substituteProcedures in the Procedures root node.

55.6.7 Doctags for controlling automatic definition creation

The following doctags control the automatic creation of definitions for procedure call recording. You can use them to set or override specific values for the created definition.

55.6.7.1 Flags for optional nodes

If you want to mark one or more nodes as optional for conversion, you can use one of the following doctags.

For more complex procedures, a user will likely not record all recordable events when performing the corresponding actions. In this case you can mark the steps that the user may or may not record as optional. @prec/optional/start marks the first in a series of optional steps, @prec/optional/end in the same procedure marks the last one. The last node of a procedure has an implicit @prec/optional/end.

If you only want to mark a specific step as optional, use @prec/optional. If this node has child nodes, they also become optional.

@prec/optional/start and @prec/optional/end

All nodes between the marked nodes - including the marked nodes themselves - are added to the optional node group of the procedure call definition. If you only specify @prec/optional/start, the current node and all subsequent sibling nodes up to the end of the procedure are added to the optional group.

@prec/optional

The node and all its child nodes are added to the optional group.

55.6.7.2 Flags for attributes

@prec/component/id/ignore

The component specified in the node must be ignored for the definition, e.g. when Ctrl-Enter or ESC are not restricted to a specific component. Values specified in the doctags @prec/condition or @prec/scope are transferred to the procedure call definition.

@prec/attributes/id/ignore

The QF-Test component ID specified in the node must be ignored for the definition. Other component recognition criteria are written into the procedure call definition. Useful when duplicate components (but with different QF-Test component ID) exist in different (procedure) test suites.

@prec/component/id myQF-TestComponentId

The QF-Test component ID is specified as a variable, e.g. $(node), and the automated process cannot determine which component it refers to. In practice, however, the procedure is always executed for a specific component, typically with different indexes. The doctag allows specifying the component - without index. The doctag is ignored if the variable is defined in a procedure call.

The automated process creates an entry in the set procedure call parameters section: variable name: <componentid>, so that when the Procedure call is later generated, the full QF-Test component ID including indexes is added to the parameter list. The QF-Test component ID or SmartID specified in the doctag is entered in the component section.

@prec/scope

The QF-Test component ID or SmartID of a container component. If a QF-Test component ID or SmartID is specified for the component itself, the scope is only added to the YAML code if the option OPT_RECORD_COMPONENT_NAME_OVERRIDE is set to VAL_NAME_OVERRIDE_EVERYTHING.

@prec/attributes/xxx

Attributes set during the recording can be used for the definition. The automated process adds attribute values as follows:

1. Check whether it is a variable. If so, and the value is not the default value an entry is created in the set procedure call parameters section: variable name: <placeholder for the corresponding attribute>.
2. If a corresponding doctag is present, an entry for the attribute with the doctag's value is created in the attributes section.
3. If neither 1 nor 2 apply, an entry for the attribute with the attribute value from the corresponding node is created in the attributes section - unless it is one of the attributes for which adding the value is not useful, such as X or Y in Mouse events.

Attributes cannot be inherited unless this is specified differently for certain attributes.

@prec/attributes/client

The doctag is inherited from nodes in procedures or packages. Inner doctags override outer values.

@prec/VariableIsNoIndex

If the QF-Test component ID contains an embedded variable such as MyComponent$(suffix), QF-Test normally tries to extract this as a sub-index variable pair (separator and index). If the variable is part of the QF-Test component ID itself and not a sub-index, mark the node with this doctag.

@prec/component/name myComponentName

The specified name is added to the component section of the definition. Useful for nodes whose QF-Test component ID is only a variable. Otherwise the value specified in the node is overridden.

The doctag is inherited. Doctags from child nodes override values from parent nodes.

@prec/component/class myComponentClass

The specified class is added to the component section of the definition. Useful for nodes whose QF-Test component ID is a variable, so the Class name of the Component cannot be determined. Any value already determined by the automated process is overridden.

Use the doctag @prec/component/class if the component class should be ignored.

The doctag is inherited. Doctags from child nodes override values from parent nodes.

@prec/component/engine technology

The technology for the node: awt, android, fx, iOS, pdf, swt, web.

The doctag is inherited. When written to a Package node, it applies to all procedures in the Package. Inner doctags override outer values.

@prec/component/feature myComponentFeature

The specified Feature is added to the component section of the definition. Useful for nodes whose QF-Test component ID is a variable, so the Feature of the Component cannot be determined. Any value already determined by the automated process is overridden.

The doctag is inherited. Doctags from child nodes override values from parent nodes.

@prec/component/extraFeatures myFeatureName myFeatureValue

The specified Extra feature is added under the extra features section within the component section of the definition. Useful for nodes whose QF-Test component ID is a variable, so the Extra feature of the Component cannot be determined. Any value already determined by the automated process is overridden.

If the doctag is written to a node with child nodes, the specified extra feature is added to all child nodes. Doctags from child nodes override values from parent nodes.

@prec/condition expression

If you want to use attributes in the definition for which no YAML entry is provided but a matching Placeholders is available, these can be specified in a condition. Multiple conditions are combined with a logical and. The doctag can be specified on the node in the procedure or on the corresponding Component node. It cannot be inherited and must be set directly on the node. The condition syntax must match the Script language.

@prec/component/state/selected value, @prec/component/state/checked value, @prec/component/state/enabled value, @prec/component/state/editable value, @prec/component/state/visible value

Adds a state condition to the node in the definition. The value must be true or false. Multiple state conditions as well as @prec/condition are combined with a logical and. The doctags cannot be inherited and must be specified directly on the node.

55.6.7.3 Flags for adding or ignoring nodes

If you explicitly want to include a node in a definition or skip it, or if an existing definition should not be overwritten, you can use the following doctags:

@prec/addNode

For non-parameterized Check nodes and Wait for component to appear nodes, except Window components, that would otherwise not be added to the procedure call definition. The doctag can be inherited.

@prec/ignore/start and @prec/ignore/end

All nodes between the marked nodes - including the marked nodes themselves - will not be added to the procedure call definition. If you only specify @prec/ignore/start, all nodes up to the end of the procedure are not added to the procedure call definition.

@prec/ignore

The node and all its child nodes will not be added to the procedure call definition. You do not need to mark non-recordable nodes or non-parameterized Check nodes. They will always be ignored. If you annotate a Procedure with it no definition will be created for the procedure and the child nodes will be skipped if called from another procedure.

@prec/duplicate

For Procedure nodes only: the automated process does not create an Procedure call definition for the procedure itself, but still considers the nodes in the procedure when it is called from another procedure.

@prec/noUpdate

The corresponding Procedure call definition is skipped during automatic update of definitions. This is marked with the index "0" in the results list. The doctag can be written to the Procedure or the Procedure call definition node. The behavior is the same.

55.6.7.4 Flags for variables

@prec/parameters/parametername value

Adds an entry for the specified parameter name/value pair in the set procedure call parameters section. The doctag can be used to replace forwarded variables. When the value does not contain a variable the doctag will be ignored and the acutal value will be written to the definition. Useful for attribute values where only part of an attribute is a variable.

The doctag can be inherited.

@prec/parameters/check <CHECKEDSTATE>

@prec/parameters/tableoption <NAME> - manual action required: remove the first part - used in OptionTable-$(tableoption)

55.6.7.5 Flag for priority

@prec/priority [+|-]number

For Procedure nodes only: this allows overriding or adjusting the Priority determined by the automated process: if a "+" precedes the value, the specified value is added to the automated value, with a leading "-" it is subtracted. Otherwise the automated value is replaced.

The doctag is inherited from nodes in procedures or packages. Inner doctags override outer values.