Convenience Method expectAllExist()

Sometimes you need your AskUI workflow to adapt to variations in your User Interface (UI) when it is executed. This includes for example popups that may or may not appear or small changes in your UI depending on the state of the system.

In an earlier blog post about Conditional Execution we showed you how to execute different AskUI instructions depending on the (non-)existence of an element.

But what if you want to check for the existence of multiple elements at once? You have to write multiple instructions, which is a tedious process.

This is why we implemented the convenience method expectAllExist() which takes an array of descriptions and checks for their existence.

Prerequisites

• AskUI installed in version >0.20.0

The API

The method expectAllExist() takes an array of element specifications and returns an object with an accumulated boolean allExist which is true when all elements have been detected. And, second, the element specifications with an additional property exists which is true when the individual element has been detected.

async expectAllExist(
    query: ElementExistsQuery[]):
  ): Promise<ExpectAllExistResult>;

// Validate existence
const exists = await aui.expectAllExist([...]);
exists.allExist // true when every element exists

// Check which elements do not exist
// with the elements property
const nonExistentElements = exists.elements.filter((e) => e.exists===false)

We will demonstrate the capabilities of expectAllExist() on our AskUI Practice Page. You can follow along if you like.

Example 1: Expect a Single Text Element

Let us start with the most common use case: Checking for the existence of a text element.

const textElement = 
  await aui.expectAllExist([
    {
      type: 'text',
      text: {
        value: 'Switch to Dark',
        matching: 'similar' // similar, exact, regex
      }
    },
  ]);

When you log the returned object it will look like this:

console.log(textElement)
{
  allExist: true, // Every searched element exists
  elements: [
    {
      type: 'text',
      text: {
        value: 'Switch to Dark',
        matching: 'similar'
      },
      exists: true // Particular element exists
    }
  ]
}

Now you can go ahead and do, or not do, something with the knowledge that it exists 😊.

Example 2: Expect a Complex Element with a Relation

The next thing we want to check is the button with the label CE that is right of the text %. We do it like this:

await aui.expectAllExist(
  [
    {
      type: 'button',
      text: {
        value: 'CE',
        matching: 'similar'
      },
      relation: {
        type: 'rightOf',
        text: '%'
      }
    },
  ]
);

Example 3: Expect Multiple Elements

For the last example, you have to switch to the Register tab of the practice page.

We will check for the existence of the text Name:, the checkbox with the label Developer and last but not least the button with the label Submit that is below the text Profile.

await aui.expectExistence(
    [
      {
        type: 'text',
        text: {
          value: 'Name',
          matching: 'similar'
        }
      },
      {
        type: 'checkbox',
        relation: {
          type: 'rightOf',
          text: 'Profile:'
        }
      },
      {
        type: 'button',
        relation: {
          type: 'contains',
          text: 'Switch'
        }
      }
    ]
  );

Limitations

The new convenience method only works for elements of type text, button, checkbox, switch, textfield and element. Additionally it has a limitation for textfield when used in conjunction with a relation. Read below on what to pay attention to.

Unsupported Elements

We currently do not support the following element types: container, icon, image, otherElement, special and table.

Use only Relation for Switch, Checkbox, Textfield

Textfields, Switches and Checkboxes do not have a text label inside them naturally. Specifying a text property for these elements will lead to a not detected element. Please only the relation property as shown in the following example:

// Will only match for textfield that
// is below the text register
const textfield =
  await aui.expectAllExist([
    {
      type: 'textfield',
      relation: {
        type: 'below',
        text: 'Register'
      }
    }
  ]);

Conclusion

Expecting the existence of multiple elements can be a real drag if you do not use expectAllExist(). This new convenience method will help you to write more maintainable AskUI workflows and also prevent RSI hopefully.

If you have questions or need support, do not hesitate to join our Community.