50.1.2

The 'Install CustomWebResolver' node

The mapping of HTML objects to Generic classes is usually done via the 'Install CustomWebResolver' node.

7.0+ Before QF-Test version 7, this mapping was achieved by a call to the Procedure installCustomWebResolver and updateCustomWebResolverProperties from the qfs.qft standard library. These procedure calls should now be converted to a 'Install CustomWebResolver' node. Before conversion of the procedure call, the contained parameters are automatically checked to uncover possible invalid assignments and to facilitate the switch to the 'Install CustomWebResolver' node. If your procedure call contains variables, you must provide a run log during conversion which contains the desired variable values. If your procedure call contains invalid entries as comments, you may have to remove them before conversion or put them back in the desired location after conversion.

If you used the Quickstart Wizard from the »Extras« menu to create the setup sequence for your web application, as recommended, you will find the 'Install CustomWebResolver' node in the last 'Sequence' node. You should configure this node as required for your application.

		Figure 50.2:  Installing the 'CustomWebResolver' in the 'Setup' node of the Quickstart Wizard

Please find general information about component recognition in Recognition of web components and toolkits as well as in General configuration.

In the following chapters, the syntax used by the 'Install CustomWebResolver' node and the available configuration categories are explained.

Note Please note changes in the 'Install CustomWebResolver' node are likely to also change the recognition criteria for a GUI element. Thus they may deviate from the recognition criteria of 'Component' nodes already recorded. Therefore, you should update existing 'Component' nodes as described in Update 'Components'. Ideally, the configuration of the 'Install CustomWebResolver' node should be done before setting up the tests. Nodes recorded during the configuration phase should be deleted altogether.

50.1.2.1

'Install CustomWebResolver' node – Syntax

The 'Install CustomWebResolver' node is configured in a text area using the YAML syntax. Knowledge of the basic functionality of YAML is neccessary, but it will be explained where neccessary below.

On the top level there are the configuration categories (see the following sections). These are written on their own line and are followed by a colon (dictionary keys). On the second level, the entries each start on a new line, beginning with a hyphen (list items). Further levels are indicated via indentation.

To facilitate working with the YAML configuration, various templates can be inserted via the toolbar above the editor.

		Figure 50.3:  'CustomWebResolver' configuration templates

The menu, which can be opened via the edit button next to the line numbers, is context-sensitive. It contains any available actions for the respective line of configuration. If you work with this menu, you will always have the full overview of available actions and automatically achieve the correct syntax.

If you followed Quickstart your application to create the startup sequence and left the framework selection on the default setting, you will receive a configuration with two categories and two entries on the second level, plus a few explanatory comments:

		Figure 50.4:  'CustomWebResolver' with a template for genericClasses

In the following configuration, the line after the category genericClasses was selected and then the edit menu to the left of the line numbers was used to insert a template for a generic class (comments removed for brevity).

		Figure 50.5:  'CustomWebResolver' with two generic classes

In the next step, the generic class List was entered, as well as the CSS class datalist. HTML elements with this CSS class will now be assigned this generic class during component recognition. This process was repeated for the generic class Item:ListItem. It will be assigned to each GUI element with the HTML tag LI. Normally, only elements with this tag that are inside a List component should be considered. Therefore, the next step is to use the edit button and choose the entry "Add ancestor". As you can see, the syntax for the entry changes: As soon as more than one characteristic is needed for the mapping, the first mapping is moved to the next level with the appropriate prefix, and the additional characteristic is added to the same level.

		Figure 50.6:  'CustomWebResolver' with more complex mapping

50.1.2.2

'CustomWebResolver' configuration categories

Every 'CustomWebResolver' is based on a globally defined default configuration with a set of generally applicable rules. You can inspect part of these defaults in the included library qftest-8.0.1/include/qfs-resolvers.qft in the procedure qfs.web.cwr.helpers.default.

You can find a complete list of all available configuration categories in QF-Test in the 'Install CustomWebResolver' node behind the "New mapping" button.

The following sections briefly introduce the most important configuration categories. Please keep in mind that all functionality of the different categories can be explored via the context-sensitive edit button . Not every possible permutation of the syntax is described here.

50.1.2.3

Configuration category base

Contains the short name of the base resolver which serves as the foundation of the configuration:

• autodetect: automatic detection of the framework used. Falls back to custom if no supported framework was detected.
• custom: No framework should be used as a basis for the configuration. In this case, base can also be omitted completely.

• The short name of the framework, for example vaadin:
  The mappings shipped with QF-Test in qftest-8.0.1/include/qfs-resolvers.qft for the respective framework are used. In your configuration, these can be supplemented with your own mappings.

  You can find the short names of each supported framework in the table table 50.7. If you create a setup sequence with the Quickstart Wizard and choose a framework, its short name is inserted here.

  You can also use the full name of a procedure as a short name. This procedure should contain you own base resolver for the application under test. It is also possible to create multiple procedures and orchestrate them freely in one 'Install CustomWebResolver' node. You can even combine them with a base resolver predefined by QF-Test, but the predefined resolver must usually be at the start of the list. The configurations will then be applied in the given order.

  	base: - vaadin - myResolvers.Panels - myResolvers.otherClasses
  		Example 50.1:   List of base resolvers

50.1.2.4

Configuration category genericClasses

In this category, the recognition criteria are defined, on the basis of which a specific generic class is assigned to a GUI element. The respective properties of the generic classes are explained in chapter 60.

Generic classes can receive a type extension. It is used for the mapping of some HTML elements. For example, Item:ListItem refers to a list item, Button:ComboBoxButton refers to a button that opens a combo box. Type extensions are also interesting because you can define you own types. The example in 'CustomWebResolver' – Tables uses this technique.

Note When using a class with a type extension in a SmartID, the colon before any custom type extension must be escaped with a backslash, see SmartID syntax for 'Class name'.

The given entries are evaluated from top to bottom, and for each HTML element the topmost matching generic class is used. The only exception to this rule are entries with ancestor, which are always evaluated first.

The tag name and the attributes of an HTML element are the most basic elements of component recognition. The class attribute has a special role. It contains the CSS classes that influence the display of the GUI element in the browser and are thus often characteristic of a particular GUI element class.

'Install CustomWebResolver' offers ways to create mappings for each of these cases:

CSS class

The CSS class refers to an entry in the attribute class of the GUI element. Please note that multiple classes can be separated by spaces in the attribute, but only individual classes are considered here.

Simple mapping: The CSS class is entered on the same line as the generic class.

	genericClasses: - Button: btn
		Example 50.2:   Simple mapping of a CSS class to a generic class

In the example, only HTML elements with the CSS class btn receive the generic class Button.

Mapping with multiple criteria: The CSS class is indented in a line below the generic class and prefixed with css:.

	genericClasses: - Button: css: btn tag: DIV
		Example 50.3:   Mapping CSS class and tag name to a generic class

In the example, only HTML elements with the CSS class btn and the HTML tag name DIV receive the generic class Button.

It is also possible to specify multiple CSS classes at once. Only one of the given CSS classes has to match.

	genericClasses: - Button: css: - btn - button
		Example 50.4:   Mapping multiple CSS classes to a generic class

HTML tag name

Simple mapping: The tag name is added in angled brackets after the generic class.

	genericClasses: - TableCell: <TD>
		Example 50.5:   Simple mapping of a tag name to a generic class

In the example only HTML elements with the tag TD receive the generic class TableCell.

Mapping with multiple criteria: The tag name is indented in a line below the generic class and prefixed with tag:.

	genericClasses: - TableCell: tag: TD ancestor: TableRow
		Example 50.6:   Mapping a tag name with an ancestor to a generic class

In the example, only HTML elements with the tag TD receive the generic class Button if they are inside a GUI element with the class TableRow.

It is also possible to specify multiple HTML tag names at once. Only one of the given names has to match.

	genericClasses: - Button: tag: - CUSTOM-BUTTON - BUTTON
		Example 50.7:   Mapping multiple HTML tag names to a generic class

HTML attribute

Simple mapping: The attribute name, an equals sign and the attribute value are added after the generic class.

	genericClasses: - TableRow: role=datarow
		Example 50.8:   Simple mapping of an attribute to a generic class

In the example, only HTML elements with the attribute role and the value datarow are assigned the generic class TableRow.

Mapping with multiple criteria: Indented below the generic class a line is added for the attribute name with the prefix attribute: and for the attribute value with the prefix attributeValue:.

	genericClasses: - TableRow: attribute: role attributeValue: datarow
		Example 50.9:   Mapping an attribute value to a generic class

In the example, only HTML elements with the attribute role and the value datarow receive the generic class TableRow.

Note The class attribute can also be used here. However, then the entire value of the attribute must match for the mapping to apply. For example, if two CSS classes must be present and the others are to be ignored, a regular expression can be used. This is also an example for an additional level of indentation.

	genericClasses: - TableRow: attribute: class attributeValue: value: (^|.*\s)btn(\s.*|$) regex: true
		Example 50.10:   Mapping an attribute value to a generic class

Ancestor

To make a mapping additionally dependent on the existence of a specific parent element, ancestor: is used.

Simple mapping: The class of the container is added with the prefix ancestor:.

	genericClasses: - TableRow: tag: TR ancestor: Table
		Example 50.11:   Simple ancestor mapping

In the example, only HTML elements with the HTML tag TR receive the generic class TableRow if they lie anywhere within an element with the generic class "Table".

Mapping with multiple criteria: Indented below the prefix ancestor: follow one or more of the attributes type:, level: and className:.

Available values for type: are ancestor (arbitrary nesting), parent (direct parent element) and interestingparent (directly inside the QF-Test parent element determined by node.getInterestingParent()).

	genericClasses: - TableRow: tag: TR ancestor: type: ancestor level: 2 className: Table
		Example 50.12:   Complex ancestor mapping

In the example, only HTML elements with the HTML tag TR receive the generic class TableRow which are two levels deep inside an element with the generic class "Table".

The attributes css: and attributeName: can be combined with tag:, but not with each other.

If HTML elements with different recognition criteria should receive the same generic class, two entries for that class need to be added:

genericClasses:
- TableRow:
    attribute: role
    attributeValue: datarow
- TableRow:
    tag: TR
    ancestor: Table

Noteancestor: is also available in many other configuration parameters. Check the edit menu for the entry "Add ancestor".

50.1.2.5

Configuration category ignoreTags

A list of class names or tags for which to ignore nodes when creating the parent hierarchy of a node. To distinguish tags from class names, tags must be written in uppercase letters or between angle brackets.

In the following example, all DIV and TBODY nodes not mapped to a generic class and not interacted with directly will be ignored.

ignoreTags:
- <DIV>
- <TBODY>

50.1.2.6

Configuration category ignoreByAttributes

A list of HTML attributes and values for which to ignore nodes when creating the parent hierarchy of a node:

ignoreByAttributes:
- id: container

50.1.2.7

Configuration category autoIdPatterns

A list of patterns specifying ids generated automatically by a framework. If the id attribute matches the pattern the value will not be used for the 'Name' attribute of the component:

autoIdPatterns:
- myAutoId
- value: auto.*
  regex: true

50.1.2.8

Configuration category customIdAttributes

A list of attribute names which can act as id for a component. Keep in mind that you need to include the attribute "id" here if you only want to augment the default QF-Test behavior.

The following example will make the attribute myid be used for ID resolution.

customIdAttributes:
- myid

50.1.2.9

Configuration category interestingByAttributes

A list of attribute names and values telling QF-Test to create a node in the component tree for the respective GUI object.

interestingByAttributes:
- id: container
- id: header

50.1.2.10

Configuration category attributesToQftFeature

A list of attributes where the values will be used for the 'Feature' attribute of the QF-Test component.

50.1.2.11

Configuration category redirectClasses

In this category you can configure for individual generic classes if events should be redirected to elements of that class or if an ancestor element should be recorded instead. You can also define multiple rules to achieve different behavior depending on the class of the parent element.

Entries are evaluated from top to bottom, and only the first matching entry is applied.

Use carefully. When in doubt, contact the QF-Test support team.

50.1.2.12

Configuration category documentJS

Define JavaScript code to be injected into the web page. Can be used to inject custom JavaScript functions or run certain code after every page load.

In the following example, pay attention to the syntax for multiline strings in YAML. Injected JavaScript code should not contain any empty lines to avoid conflicts with the YAML syntax.

documentJS: |-
  window.hello = function() {
      console.log("Hello World");
  }
  hello();

50.1.2.13

Configuration category attributesToQftName

A list of attributes which will be used for the 'Name' attribute of components.

50.1.2.14

Configuration category nonTrivialClasses

A list of CSS classes of HTML-Elements which shouldn't be ignored by QF-Test. Trivial nodes are usually I, FONT, BOLD etc. If you want to keep them, you need to activate them here specifying a proper CSS class.

Use carefully. When in doubt, contact the QF-Test support team.

50.1.2.15

Configuration category browserHardClickClasses

A list of QF-Test classes whose components should always receive hard or semi-hard events during playback. For example, the entry Button will play back hard clicks on buttons. Can also be limited to certain browsers.

50.1.2.16

Configuration category treeResolver

This category bundles configuration options which control how QF-Test handles tree nodes in Tree and TreeTable. Use this category if QF-Test has trouble differentiating levels of hierarchy in trees, expanding individual tree nodes or reading the correct text content of tree nodes in your application.

In rare cases when the parameters provided for the category might not be enough please refer to The TreeIndentationResolver Interface.

50.1.2.17

Configuration category treetableResolver

This category bundles configuration options which control how QF-Test handles tree nodes in TreeTable components. You can for example define the index of table columns in your application a tree can be located, in case QF-Test cannot find it automatically.

Last update: 9/10/2024 Copyright © 1999-2024 Quality First Software GmbH