Convenience Methods - Update TypeScript ADK 0.18.0

May 10, 2024

The image features three teabags hanging against a dark background on the right side, symbolizing variety or brewing new ideas. On the left side, a maroon background contains white text that reads: "Convenience Methods – Update TypeScript ADK 0.18.0." Above the text is a rounded rectangle with the word "Academy." The design communicates an educational or informative update related to the TypeScript ADK version 0.18.0.

In an earlier blog post we explained how convenience methods could be used to write more expressive AskUI code.

Those were based on common use cases we noticed and already brought improvements.

But we also discovered they needed to be more streamlined and include relations, to be useful in every scenario. That is why we went back to the drawing board to redesign the API and also include more elements like switches and checkboxes.

We think this update will be very useful for your efficiency!

Prerequisites

AskUI installed and configured on your system (Windows, Linux, macOS)
Check package.json for askui in version 0.18.0

The Idea Behind the Update

We wanted to have a more expressive method signature with better code completion. Also the method signatures should be more alike, so using does not feel like "Oh I have to read the docs every time!?".

That is why we chose to use objects with properties, so you can leverage "names" for parameters and also better Intellisense. Generally, the objects look nearly the same for every method and now also include an optional relation, so you can target elements that normally have a label or text nearest to them in some way:

Example: await aui.clickCheckbox({label: 'Toggle', relation: {type: 'leftOf'}})

Breaking Changes

We introduced two breaking changes for existing convenience methods clickText() and clickButton(). This was necessary to align the method signatures with the newly implemented convenience methods presented later in this post.

clickText()

What it does: Clicks a text.

What does it solve: More concise code for clicking a specific text.

API docs for clickText()

-- CODE language-ts line-numbers -- await aui.clickText('Hello World'); // Now await aui.clickText({text: 'Hello World', type: 'similar'}); // Example with full parameters await aui.clickText({ text: 'TERMINAL', type: "exact", // possible values: similar, exact, regex relation: { type: 'leftOf', text: 'PORTS' } })

clickButton()

What it does: Clicks a button that has a text on it.

What does it solve: More concise code for clicking a button.

API docs for clickButton()

-- CODE language-ts line-numbers -- // Before await aui.click().button().withText('Submit').exec(); // Now await aui.clickButton({label: 'Submit'}); // Example with full parameters await aui.clickButton({ label: 'Click', relation: { type: 'leftOf', text: 'Choose a ticket' } })

clickCheckbox()

What it does: Clicks a checkbox that has a label nearest to it.

What does it solve: More concise code for finding and clicking a checkbox.

API docs for clickCheckbox()

Example code:

-- CODE language-ts line-numbers -- // Do not do this await aui.click().checkbox().rightOf().text('Agree').exec(); // Do this instead await aui.clickCheckbox({ label: 'agree', relation: { type: 'rightOf' } });

clickSwitch

What it does: Clicks a switch that has a label nearest to it.

What does it solve: More concise code for finding and clicking a switch.

API docs for clickSwitch()

Example code:

-- CODE language-ts line-numbers -- // Do not do this await aui.click().switch().rightOf().text('Turn off').exec(); // Do this instead await aui.clickSwitch({ label: 'Turn off', relation: { type: 'rightOf' } });

typeIntoTextfield()

What it does: Types text into a textfield which is specified in relation to a label.

What does it solve: More concise code for typing text into a textfield, where the textfield can be specified through a relation.

API docs for typeIntoTextfield()

Example code:

-- CODE language-ts line-numbers -- // Do not do this await aui.typeIn('Hello World!').textfield().nearestTo().text('Notes').exec(); // Do this instead // Finds the textfield nearest to the label 'Email' await aui.typeIntoTextfield({ textToWrite: 'Hello World', relation: { label: 'Notes' } }); // Finds the textfield above/below a label 'Password' await aui.typeIntoTextfield({ textToWrite: 'Hello World', relation: { type: 'above', label: 'Password' } });

Conclusion

The update for the convenience methods unifies most of the common use cases. It also introduces objects as parameters that feel like named parameters.

Please let us know if you find them useful or if you need a convenience method for a specific purpose.

Johannes Dienst

May 10, 2024

Convenience Methods - Update TypeScript ADK 0.18.0

Prerequisites

The Idea Behind the Update

Breaking Changes

clickText()

clickButton()

clickCheckbox()

clickSwitch

typeIntoTextfield()

Conclusion

More to explore

Mastering the Art of Automating UI Testing

Website Testing Tools: A Vital Component of Quality Assurance

Automating Quality: How Automated Web Testing Transforms Software Development