UseCase - Custom Identifier

Relational Element Identifier with insideOf attribute

In modern app interfaces, elements are often nested within parent containers like cards, tabs, or dialogs. While a button or icon might not be unique on its own, its location within a specific container can be the key to identifying it. This is where the powerful insideOf relational identifier comes in.

The insideOf identifier allows you to precisely target an element by specifying that it must be located within a larger, uniquely identifiable parent element. This creates highly resilient and readable locators, especially in complex or dynamic layouts.

Example: Tap on "Search" icon, which is one of several icons in a navigation bar:

1. Identify the Ambiguity: When we attempt to click the "Search" icon, Finalrun highlights it with a red overlay. This indicates the icon itself doesn’t have enough unique properties to be targeted reliably on its own.

2. Open the Identifier Window: Clicking the element opens the "Confirm element for the tap action" window, where we can build a custom identifier.

3. Use a Suggested Identifier: Finalrun's suggestion engine is smart enough to analyze the layout. Notice the first suggestion: "Image with id... inside container id:nav_tab_search...". This indicates a perfect use case for insideOf.

4. Analyze the insideOf Structure: Selecting this suggestion reveals the JSON identifier. Let's break down the key parts:

   • The Target: The primary properties { "id": "navigation_bar_item_icon_view", "type": "image" } describe the element we want to tap—in this case, an image with a specific ID.

   • The Container: The insideOf block { "id": "nav_tab_search" } acts as a filter. It tells Finalrun: "Don't just find any image with that ID; find the one that is a descendant of the container with the ID nav_tab_search."

{
  "id": "navigation_bar_item_icon_view",
  "type": "image",
  "insideOf": {
    "id": "nav_tab_search"
  }
}

1. Test and Confirm: Before confirming, use the Test button to verify that the combination of the target element and its container uniquely highlights the correct "Search" icon. Once verified, click Confirm to add the robust, new test step.

Relational Element Identifier with insideOf and containsDescendants attribute

What happens when the element you want to tap is not unique, and its direct parent container isn't unique either? This common scenario in dynamic UIs requires a more sophisticated targeting strategy. By combining insideOf with containsDescendants, you can create an exceptionally precise identifier that first locates a container by identifying its unique child content, and then finds your target element within that container.

In this example, we will tap the "close" icon inside the "Donate" container. The icon itself is generic, so we'll anchor it to the unique "Donate" text.

1. Identify the Ambiguity: When attempting to tap the "close" icon (an image), Finalrun marks it with a red overlay. It is not unique. Furthermore, simply looking for its parent container isn't enough, as there may be other similar containers on the screen.

2. Use a Suggested Identifier: Clicking the icon opens the "Confirm element" window. Finalrun's top suggestion intelligently constructs an identifier using both insideOf and containsDescendants.

3. Deconstruct the Identifier: Let's examine how this powerful identifier is built:

   • The Target (image): The identifier starts by describing our ultimate target—an { "type": "image" }.

   • The Container (insideOf): Next, it specifies that this image must be insideOf a container with the ID main_drawer_donate_container. But how does it find the correct container?

   • The Anchor (containsDescendants): This is the crucial part. The containsDescendants property tells Finalrun to identify the container by confirming it contains a specific child element—in this case, an element with { "text": "Donate" }.

   • The Relative Locator (rightOf): As an additional layer of precision, the identifier specifies the target image is to the rightOf the "Donate" text element.

{
  "type": "image",
  "insideOf": {
    "id": "main_drawer_donate_container",
    "containsDescendants": [
      {
        "text": "Donate"
      }
    ]
  },
  "rightOf": {
    "text": "Donate"
  }
}

1. Test and Finalize: Click the Test button to watch Finalrun flawlessly highlight the correct "close" icon. Confirm the step to lock in your robust new identifier.