How to expect() - The Pitfalls

May 29, 2024

Academy

A person in a sitting yoga pose with arms above head watching the sunrise. The person is center of the picture. Headline is expect() and and() and or() subtitles are on the left and right of the person.

Selecting elements visually is pretty cool and all. But once you start to build a serious workflow it is not enough.

You also need:

Checking if elements are actually there
Check for multiple elements to be there
Check if either a element is there or another one is there

This is where expect(), and() and or() get on stage to shine.

But they are not always as intuitive to use as one might think.

That is why this blog post will go into detail about all the common pitfalls - we know of - you can run into and how to avoid them.

How to Use expect()

The usage of expect() seems "_simple_" and has the following structure for its syntax (Check the full API docs):

-- CODE language-ts line-numbers -- expect().<your element-description>.(exists()|notExists())

Pitfall 1 - Forgetting exists()/notExists() and/or exec()

Correct usage of expect() needs you to use exists() or notExists() and also conclude your instruction with exec() like this:

-- CODE language-ts line-numbers -- await aui.expect().text('Log in') .exists() // mandatory .exec(); // mandatory await aui.expect().text('Log in') .notExists() // mandatory .exec(); // mandatory

Something that happens often is that expect() is used but exists()/notExists() is missing. While this code compiles, the instruction does not lead to an execution that checks for the (non-)existence of an element:

-- CODE language-ts line-numbers -- // Compiles but does nothing when executed await aui.expect().text('Get a demo')

But even if you do add an exists()|notExists() it still does not lead to an execution as the exec() is missing:

-- CODE language-ts line-numbers -- // Missing exec() -> Does nothing when executed await aui.expect().text('Log in').exists()

Because of this we implemented an ESLint rule to check for the correct usage of expect(), so you do not have to search for this two subtle bugs any more! The ESLint rule is available with version 1.3.0 of the npm-package @askui/eslint-plugin-askui (Check the README for more information). It is shipped by default when a new AskUI project with version 0.18.0 is initialized.

You can not use expect() with and() - What You Should Do Instead

Intuitively you would think you can check if multiple elements exist with one instruction by using and():

-- CODE language-ts line-numbers -- // Will always fail! await aui.expect().text('Log in') .and() .button().withText('Sign Up') .exists() .exec();

But this will always fail as you actually expect an element to have the text Log in and the element to also be a button with the text Sign Up which can never be true.

The solution to this problem is to use multiple expect() instructions:

-- CODE language-ts line-numbers -- await aui.expect().text('Log in') .exists() .exec(); await aui.expect().button().withText('Sign Up') .exists() .exec();

How to Use expect() Together With or()

Checking if at least one of multiple elements is on the screen works with or(). In the following example we expect one of three buttons to be there:

-- CODE language-ts line-numbers -- // Will not fail if at least one of the // three buttons is detected await aui.expect().button().withText('Log in') .or() .button().withText('Get a demo') .or() .button().withText('Sign Up') .exists() .exec();

Expect Fails but I Want to Continue the Workflow

Sometimes you want to continue your workflow or do something if an element is not there. But when an expect() fails it fails the whole workflow run by throwing an exception. You can work around this by using a try/catch. In the catch-block you define your recovery or alternative:

-- CODE language-ts line-numbers -- try { await aui.expect().button().withText('Sign Up') .exists() .exec(); } catch (error) { // Recover by reloading the application for example await aui.pressTwoKeys('command', 'r').exec(); await aui.expect().button().withText('Sign Up') .exists() .exec(); }

Conclusion

AskUIs expressive syntax that nearly reads like natural language looks simple enough to write at first. But like with everything the key to success lies in the nuances.

We hope you learned some of those regarding the expect() command with this blog post. If not, we are more than happy to help you out in our Community.

Johannes Dienst

May 29, 2024

How to expect() - The Pitfalls

How to Use expect()

Pitfall 1 - Forgetting exists()/notExists() and/or exec()

You can not use expect() with and() - What You Should Do Instead

How to Use expect() Together With or()

Expect Fails but I Want to Continue the Workflow

Conclusion

More to explore

Relational Selectors: Intersection Area

Conditional Execution in AskUI Workflows

Convenience Methods - Update TypeScript ADK 0.18.0