A few days ago I wrote about my first experiences in using White. I mentioned I wanted to create a facade around the White API in order to avoid constantly retyping the same code for common use cases. Since fluent interfaces are in fashion now, I decided to create a fluent facade. Just joking, of course.

I’ll present the facade through a few tests of a Kosmos GUI, which is currently under construction. Kosmos GUI is a MDI application for displaying maps from OpenStreetMap geo data. You have to load a Kosmos project, which contains information about where to find the data and how to render it. So after starting the application, the first user action would typically be to open the project:

After clicking the File|Open Project menu item, a dialog for selecting the Kosmos project file appears:

One you have selected the project file, a progress box is shown with an option to cancel the operation:

If you let it finish, a map appears and some additional menu items are now available:

Test Code

Here’s a sample test case which goes through the above steps:

After loading the project the test case executes some of the zoom functions available in the menu. And here’s a test case which cancels the project loading (and then checks that the View|Zoom In menu item is still not enabled):

Hopefully the code is self-explanatory. The basic idea is for the facade to remember the current window or other UI element to perform actions on. You can change the active window at any moment. The facade is also supplied with some basic assertion methods useful in the test code (they throw InvalidOperationExceptions, so you can use them with any unit test framework).

Oh I almost forgot. This is how you instantiate the facade:

And if the facade does not offer enough for you, you can always access the underlying White’s Application object through facade.Application property.

Download

You can download the latest version of the WhiteFacade class from here. I have to warn you though: the class is in its infancy and will evolve through my effort on testing Kosmos GUI. It provides only for some basic use cases, but I think those common cases represent the majority of the GUI test code. I just wanted to give you an idea on how to make writing GUI test code as painless as possible.

Documentation (Or The Lack Of It)

Unfortunately, the first impressions aren’t that good. The worst problem is lack of documentation. There are some pages written on the project’s CodePlex page and I also stumbled on a few posts which have some more examples on how to use it, but in general the API is undocumented. NDoc documentation that comes in the latest release just contains the API reference, without any human-generated documentation. It even states that it’s based on .NET Framework 1.1, which was obviously autogenerated and is probably wrong, since the API includes generics. I haven’t checked the source code directly though, maybe there is something there.

Yes I know, it’s an open source project and I shouldn’t expect too much, but I still think that such a project for which the whole purpose is to be used through an API should contain at least some documentation. Otherwise you spend a lot of time experimenting with the API to achieve the results.

Keyboard Problems

Like most other UI testing frameworks, White too suffers from quirks. I wanted to start the “Open Project” menu action using the keyboard shortcut, so I tried with:

Which ended up forcing me to restart the computer, since the OS started acting very funny, as if the Ctrl key was still being pressed. I guess I should have added

to unpress the Ctrl key, but I’m not sure, since I couldn’t find any documentation on using the keyboard in White. Anyway, a helper method that would accept a shortcut as a string (something like KeyboardInput.Press (“Ctrl+O”) would be very helpful).

Clicking The Menus

After abandoning the keyboard approach, I tried to start “Open Project” by clicking on the menu item. I did some experimenting and finally managed to write a basic test, here’s the whole test fixture:

White Facade

From my experience with other UI testing frameworks, if you intend to do more than a few simple UI tests it is a good idea to create some sort of a facade around the testing API. This way you simplify the interface to common use cases you typically use and eliminate any nasty quirks (like memory or resource leaks). Bil Simser has done something to that affect for White, although I don’t support his views on (not) using Setup and Teardown methods in unit tests.

Even better: why not implement a fluent inteface facade? Something like

or

would be much nicer than the above code, don’t you think? Okey, I’m oversimplifying, I know , but I will try to do something in the direction of a fluent interface facade, since I don’t intend to abandon the White just yet.