Status: Validated

Desktop Studio Recognition Guide


Desktop Studio includes an internal recognition process.

The goal is to allow offline validation of the recognition criteria that are set when pages and items are declared.

The recognition process implements the same recognition rules as those implemented by each driver.

This recognition process allows users to verify page recognition and item recognition for each page capture.


When you select a page in the Project Tree, Desktop Studio tries to automatically recognize it on the current capture.
In the same way, when you change the current capture, Desktop Studio tries to recognize the selected page on this new capture.

The page is highlighted:

  • In green if it has been recognised
  • In red if it is unrecognized
  • In black if no recognition has been tried

Page recognition means:

  • Testing whether the declared pages are recognized,
  • Testing whether the page's selected root item (if any) matches its recognized root item.

Page recognition can fail for the following reasons:

  • The page doesn't have declared recognition criteria,
  • A preceding declared page matches the capture,
  • The capture doesn't match the page's criteria,
  • A 'MustExist' item is not recognized in the capture (or a MustNotExist item is recognized).


Using the Recognition Tool Window

Recognition Tool Window can be used to help investigate recognition results.

The page tab displays the application's page structure.

Each element is displayed in one of the following way:

Recognized Application
Unrecognized Application
Recognized Page
Unrecognized Page
Untested Page

The number of tests displayed beside each page name is the recognition cost (in number of tests).


Example 1

Page Tab Display In this example, the Recognition Process, applied to a 'pTabPage1' Page Capture, gives the following results:

  • The 'ApplicationCRMWin' application (1) is recognized (highlighed in green),
  • The 'pTabControl1' page (2) is recognized (highlighed in green),
  • The 'pTabPage1' page (3) has not been recognized (highlighed in red),
  • The 'pTabPage2' page (4) has been tested but is not recognized (grayed with more than 0 tests).

In this case, the 'pTabPage1' page is highlighted in red, because recognition is performed on one of its captures and the page has not been recognized.
The 'pTabPage2' page is only grayed, because, even if it has not been recognized, recognition is not performed on one of its captures.


Example 2

Page Tab Display In this example, the recognition process, applied to a 'pMonAffichage' page capture, gives the following results:

  • The 'Mantis' application (1) is recognized (highlighed in green),
  • The 'pLogin' page (2) has been tested but is not recognized (grayed with more than 0 tests),
  • The 'pMonAffichage' page (3) is recognized (highlighed in green),
  • The following pages (4) have not been tested (grayed with 0 tests)
    These pages have not been tested, since the preceding 'pMonAffichage' page is not recognized.

Note the recognition cost (in test number) displayed near each page name:

  • The 'pLogin' page (2) recognition cost is 1,
  • The 'pMonAffichage' page (3) recognition cost is 112 (due to MustExist Objects),
  • The following pages (4) recognition cost is 0 (no recognition has been attempted).

The cost is especially important when using the UIAutomation driver. In this case, the driver can be very slow, especially when the recognition cost is very high.


Using the Tree Display

Tree Display

When investigating the declaration of subpages, it can be useful to use the Tree Display.

This view displays all the recognized pages.

As a subpage can only be recognized in its parent-page subtree, using the Tree Display can be helpful when trying to determinate why a subpage is not recognized.


When you select an item in the project tree, Desktop Studio tries to automatically recognize it on its selected capture.
For an item, the selected capture is the page capture in which it has been pointed and declared (if any).
For more details, see Associate Items with Components in the Page Capture.

Note that if a page is selected in the Project Tree, recognition is performed on all the page's items recognition result.

Similarly, when you change the current capture, Desktop Studio tries to recognize the selected item on this capture.

The item node is highlighted:

  • In green if it has been recognized,
  • In red if it is unrecognized,
  • In black if no recognition has been attempted.

Item test recognition means:

  • Testing that the declared item is recognized (at least one captured component matches the item recognition criteria),
  • Testing that the item pointed component (if any) matches its recognized component.

The reasons an item could not be recognized in a capture are:

  • The item doesn't have declared recognition criteria,
  • No capture component matches the item's criteria.


Choose the Current Capture for Recognition

When several captures have been created for a page, it is possible to manually select the capture used for recognition by selecting its tab (1, 2, 3, and so on) in the Capture Selector.

But when selecting an item in the project tree, the current capture is automatically set to the one where the item was pointed.

It is possible to disable this behavior by locking the current capture using the button.


Using the Screen Display

The main tool used for investigating recognition results is the Screen Display.

When an item is selected in the Project Tree, its pointed component (if any) is bordered with a blue rectangle.
Its recognized component(s), if any, are bordered with:

  • A green rectangle if it matches with the pointed component,
    As the two rectangles match, a green rectangle is displayed:
  • A red rectangle otherwise.
    As the two components don't match, two rectangles, one blue AND one red, are displayed:


Using the Recognition Tool Window

The Recognition Tool Window can be used to further investigate recognition results.

The item tab displays the selected item recognition result.

Each element is displayed in one of the following way:

Recognition succeeded
Pointed component matches recognized component
Recognized component with no pointed component
Pointed component with multiple recognized component.
One recognized component matches the pointed component
Recognition failed
Pointed component doesn't match recognized component
Pointed component with no recognized component
No pointed component with no recognized component
Pointed component with multiple recognized component.
No recognized component matches the pointed component

Note the recognition cost (in test number) displayed near each item name (for example, btAccueil [49 tests]).
This cost is especially important when using the UIAutomation driver. In this case, the driver can be very slow, especially when the recognition cost is very high.

Note also the 'index value' beside each multiple recognized component (for example: [2] or [1][1]).
This 'index value' indicates the index value that must be used to pilot each item instance (for example: oLigneAssigneToMe[2]).


Using the Tree Display

Tree Display

It can be useful to use the Tree Display to view the recognition results.
This display shows all of the recognized items inside the capture technical 'DOM' tree.