Archive for the 'White' Category

Published by breki on 21 Apr 2008

White Facade – Fluent Interface For Writing Tests Using White

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:

Kosmos1

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

Kosmos2

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

Kosmos3

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

Kosmos4

Test Code

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

[Test]
public void OpenProject()
{
   facade.ClickMenu ("File", "Open Project…")
      .FileDialog ("Open Kosmos Project File",
         @”D:\MyStuff\projects\OsmUtils\trunk\Data\Kosmos\KosmosProjectExample1.xml")
      .MainWindow ().ModalDialog ("Loading Kosmos Project")
      .MainWindow().Menu ("View", "Zoom In").AssertIsEnabled (true)
      .ClickMenu ("View", "Zoom In")
      .ClickMenu ("View", "Zoom Out")
      .ClickMenu ("View", "Zoom All");
}

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):

[Test]
public void OpenProjectCanceled ()
{
   facade.ClickMenu ("File", "Open Project…")
      .FileDialog ("Open Kosmos Project File",
         @”D:\MyStuff\projects\OsmUtils\trunk\Data\Kosmos\KosmosProjectExample1.xml")
      .MainWindow().ModalDialog ("Loading Kosmos Project").Button ("Cancel").Click()
      .MainWindow ().Menu ("View", "Zoom In").AssertIsEnabled (false);
}

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:

WhiteFacade facade = WhiteFacade.Run (applicationFilePath);

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.

Published by breki on 19 Apr 2008

Using White To Test Kosmos GUI

After a few weeks of work on my new framework for multidocument interfaces called BrekiViews (yes, I know I promised to write a little about it, but I just didn’t have enough time and concentration to put the brainstorms in my head into some coherent words) and refactoring Kosmos code to use it, I’m finally able to show some basic stuff in the new Kosmos GUI application. It’s all pretty simple at the moment, I got just one menu item working: File | Open Project. But I wanted to use this opportunity and start using White from ThoughtWorks to write automated GUI tests, since I was looking forward to trying the White out.

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:

mainWindow.Keyboard.HoldKey (KeyboardInput.SpecialKeys.CONTROL);
mainWindow.Keyboard.Enter ("o");

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

mainWindow.Keyboard.LeaveKey (KeyboardInput.SpecialKeys.CONTROL);

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:

   [TestFixture]
    public class BasicTests
    {
        [Test]
        public void OpenProject()
        {
            Menu fileMenu = mainWindow.MenuBar.MenuItem ("File");
            fileMenu.Click();
            Menu openProjectMenu = fileMenu.SubMenu ("Open Project…");
            openProjectMenu.Click();
        }

        [SetUp]
        public void Setup()
        {
            application = Application.Launch (@”..\..\..\Kosmos.Gui\bin\Debug\Kosmos.Gui.exe");
            mainWindow = application.GetWindow ("Kosmos GUI", InitializeOption.NoCache);

            Assert.IsNotNull(mainWindow);
            Assert.IsTrue (mainWindow.DisplayState == DisplayState.Restored);
        }

        [TearDown]
        public void Teardown()
        {
            application.Kill();
        }

        private Application application;
        private Window mainWindow;
    }

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

WhiteFacade.Run(kosmosGuiPath).Press ("Ctrl+O")

or

WhiteFacade.Run(kosmosGuiPath).ClickMenu ("File", "Open Project…")

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.