Windows UI testing with Legerity

Last Updated on 2022-07-15 by James Croft

Testing at the application’s UI level is often an afterthought for most projects. These tests usually put your application under the testing of how it would be used by a physical user.

Talking to developers, I found that the reason for this is that it’s often hard to start building UI tests because of the effort that’s required to just get going. That’s why I created Legerity, a .NET UI testing framework that sits on top of Appium & Selenium.

The aim of Legerity

Legerity is designed to make application UI testing easier with .NET by providing out-of-the-box element wrappers for core platform controls. Doing this takes out all of the repetitive queries that you would have to write in order to get to the elements you might want to locate.

While this article will explore scenarios for UI testing with Windows apps, Legerity is built with both Android and iOS apps in mind. I’m also investigating the options of how this may benefit UI testing with web components too.

What’s available for Windows apps?

Legerity has a set of core UWP controls that are there to ease the development of your UI tests. They surface up properties and actions of the controls within your tests to make it easier for you to work with them.

Here’s a comprehensive list of the available controls for UWP apps today.

Writing Windows UI tests with Legerity

Before writing your Windows UI tests, you’ll need to be able to run them. Windows applications are automatically run by your tests using the Windows Application Driver. The WinAppDriver supports testing UWP, WinForms, WPF, and classic Win32 applications on Windows 10 PCs.

Getting going with Legerity is simple. You’ll need to add the following NuGet package references to your .NET Core UI testing project.

<PackageReference Include="Appium.WebDriver" Version="4.1.1" />
<PackageReference Include="Legerity" Version="0.2.20155.7" />

To clarify, the Appium WebDriver package here provides the base for writing your UI tests.

Once installed, I recommend you create a base test class that will be inherited by all of your test classes. The base class is responsible for launching your application on the initialization of a test run and will stop it on a cleanup. Depending on the testing framework of choice, you may need to implement attributes on your methods to ensure they are called correctly when run. All examples shown here will be using the Microsoft Testing Framework (MSTest).

Below is a good base class for your tests.

Simply the class has an Initialize method called when a test is run. It also contains a Cleanup method called when a test has finished.

Initialize uses the Legerity AppManager to start the application. Passing an instance of WindowsAppManagerOptions to the AppManager with your application’s ID and the URL for the WinAppDriver running on your machine.

When your UI test runs, this will launch the application based on that ID using the WinAppDriver instance from the provided URL.

Once running, you can easily access the driver for your application based on the AppManager.WindowsApp property.

You can now start writing your tests, taking advantage of the Windows element wrappers for core platform controls. Here’s an example of how you might access a CalendarView element and set the date value.

FindElement in this example is an Appium method for retrieving an Appium WindowsElement using a By query. All of the Legerity elements are convertible from the WindowsElement to a Legerity one without direct casting.

To do this, you simply need to explicitly provide the Legerity element type on the variable declared. If you need to access the Appium WindowsElement, you can find this in the wrapper element as the Element property.

Exploring more of Legerity

By far the best source of out-of-the-box Windows UI elements in a single app is Microsoft’s XAML Controls Gallery. Built by the WinUI team, this app is a comprehensive sample which you can use to explore the capabilities of Windows controls.

I used this application as the base for building out the Windows elements for Legerity. To ensure that they work as intended, the Legerity project on GitHub also contains a sample UI testing project built with it for the XAML Controls Gallery.

If you have the app installed and clone the Legerity repo, you can easily run the tests to explore more of the capabilities of the framework. Included in this sample is the use of the page object pattern which I will cover in another post on UI testing.