Are You a New Programmer and Would Like to Test Your Windows Application or Existing Windows Application? Here Is a Guide to Help You Get Started. (The Beginner’s Edition)

Getting You Started with WinAppDriver

Are you a total beginner to programming just like I am, but you would still like to try out Microsoft’s tool for application testing? Well don’t worry, I got you covered. Below I will detail my experience with getting started with WinAppDriver and testing basic Windows application such as the calculator in Python and C#. This tool could be beneficial for developers that would like to test their software before production or launch. The purpose of this tutorial is to create easy steps to follow and enable you to use WinAppDriver. I once read a quote that says:

“If you want to learn something, read about it. If you want to understand something, write about it. If you want to master something, teach it.”

                                                                                                                                            - Yogi Bhajan

So here goes nothing 😊

Getting Started:

What is the Windows Application Driver?

Windows Application Driver is a user interface (UI) automation test service that uses Appium’s Webdriver Protocol. WinAppDriver makes it easy for automation test engineers or anyone to test their Windows application by enabling testing on your local PC machine as well as remote locations. It allows developers to detect and fix bugs in their products. Microsoft released the first version of WinAppDriver on March 30, 2016. WinAppDriver is in the Beta phase. Since its introduction, they have launched eight additional releases.

Pre-Requisites:

1. OS System: Windows 10 

2. Visual Studio Community 2017 and Visual Studio Code (Free.99) (You should download both, as you will need both the community and code version to run the examples in this tutorial)

3.      Pip ( Python package management system) 

P.S. execute the code in command prompt (cmd) for the installation)

OK, Let’s Get Started for Real (I pinky promise!):

Phase 1: Setting up WinAppDriver 

This where it gets exciting! Getting WinAppdriver to run on your machine is as great as the feeling someone would get after they climbed Mount Everest I suppose. (Just kidding)

First things first, navigate to the WinAppDriver Github, scroll to the bottom of the page and look at the README.md. This file has a ton of additional information about the driver, demos as well as information on how to create your test script in C#. In that same file, you will find instructions on how to download the executable (.exe) WinAppDriver. Follow the instructions listed.

Download the latest release of Windows Application Driver Installer (May 6, 2017) here: https://github.com/Microsoft/WinAppDriver/releases 

This what the release page looks like 

Run the WindowsApplicationDriver.msi and go through the Windows Application Driver Setup.

 I already had the driver installed on my computer, but I just wanted to show you what the installer interfaced resembled.

Note: You should install WinAppDriver on the machine where you will run your test. Also, the application you are testing should be installed on the machine as well. 

Once you have done that, come back to me. Personally, I would suggest downloading the WinAppDriver Github repository. It makes it easier when you are trying to run the sample test to have everything in one place. In this example, I downloaded the repository on my C drive. On the GitHub page, click on the Green button that says, “Clone or Download”

Here is how I did it:

1. Copy the full URL in the " Clone with HTTPS " dialog box.

2. Open command prompt and run the following code

git clone https://github.com/Microsoft/WinAppDriver.git

Command prompt view 

Once you have done that, let the show begin. 

In the following steps, I will teach you how to run the WinAppDriver on your machine.

1. In your command prompt, Run the following command to move to the directory where the executable file is located. 

cd \Program Files (x86)\Windows Application Driver

NOTE:  Unless you changed the directory of the Windows Application Driver, this should be the same on your Windows 10 machine. 

2. As a beginner, I always check my directory, to verify the name of the executable and to see what’s in the folder I am navigating to. 

C:\Program Files (x86)\Windows Application Driver>dir

3.      After you have searched the directory, run the following commands to execute the WinAppdriver.exe

C:\Program Files (x86)\Windows Application Driver>winappdriver.exe

NOTE: At first, I got an error saying I could not run the winappdriver.exe because it could be only be executed in developer’s mode. I would recommend enabling your device for developer’s mode before moving any further with this tutorial.

WARNING: After you completed that step, run the command above. You may get an error that states “Windows Application Driver Beta, listening for requests at HTTP://127.0.0.1.4723/ Address HTTP://127.0.0.1.4723/ is already in use. Failed to initialize: 0 X 80004005”

Don’t Panic! In my case, another driver was already listening on port 4723. Navigate to your web browser and type Localhost:4723/Sessions, this should return a JSON that tells you what application is listening or using the port.

If an application is listening, you will get a message that looks like this:

I would suggest exiting out of the application or in my case uninstalling the app if it’s not needed.

Once you have done that, reload the WinAppDriver.exe by running the command in the cmd. You should get a message that says, “Windows Application Driver Beta listening for request at HTTP://127.0.0.1.4723/.” 

NOTE: Do NOT press ENTER or else you will exit out of the WinAppDriver.

If you want to verify that you have fixed the issue, navigate to your web browser and go to Localhost:4723/Sessions. This time around, it should return a message that looks like this: 

If you've just managed to get through the first phase, pat yourself on the back because you deserve it. Phase 1 enabled us to run the WinAppDriver correctly. In phase 2, we will be running the calculator sample test to see whether the driver can identify the elements for our calculator and returns a pass or fail for the test.

Phase 2: Running the calculator test

Now open a new command prompt, navigate to the folder where your WinAppDriver samples are located. In this example, I placed my WinAppDriver samples in a folder on my C drive.

Ex: C:\Github\WinAppDriver

Then get the directory

Ex: C:\Github\WinAppDriver> dir

It should look something like this if you have downloaded the complete WinAppDriver file from GitHub 

Once the directory is listed, I go to the location of the sample test I would like to run. For this example, I will be running a calculator test on C# and Python.

First up C#:

Ex. C:\GitHub\WinAppDriver\Samples\C#\CalculatorTest>CalculatorTest.sln

The command above should open Visual Studio Community 2017, Once that opens, you will see three panels. In Solution Explorer (Right Panel), open the BasicScenerio.cs then go to Test Explorer (Left Panel) and run the test by click on Run All. 

After the test runs, look at the command prompt window where the WinAppDriver is loaded. You will get a "report" during your test, and WinApp driver will create a session that logs the activities of the test. During this, you will be able to see whether or not a test passed or failed the criteria you had listed in your code. Your session will look like the image below if you passed all of the tests: 

and if any failures occur, you will get something that looks like this 

This feature enables automation engineers to debug their code.  n my case, the failure happened because I stopped the test when I moved my mouse, exited out of the calculator app and Visual studio while it was trying to find an element. I would suggest that while the test runs, to not move your mouse so that the driver can find the elements. You can also look in visual studio in the test explorer panel to see if your test is green (passed) or red (failed)

Python Test

In your command prompt,

EX. C:\GitHub\WinAppDriver\Samples\Python\CalculatorTest> code CalculatorTest.py

The command will open your python test in whatever code editor you chose, my editor of choice is Visual Studio Code.



Once the code is opened in VS, I press F5 to run the code, which then executes the test. Just like in the C# example, do not touch your mouse if you are running this locally because the test can break. Once the test is complete, it will log any failures in your problems at the bottom of the window.

Congratulations! You made it to the summit, you have conquered Mt. Everest.

Conclusion:

In my humble opinion, the experience wasn't as painful as I thought it was going to be. If anything, it was a great learning opportunity for me. As a complete beginner, I must say it took me a bit of effort to figure out how to make WinAppDriver work properly. I would not say it was intuitive, but part of that stems from the fact that I am not a programmer and that's okay. A gotcha moment occurred after I downloaded the Windows Application Driver, I tried to run the WinAppDriver.exe by just clicking and opening the executable, but it kept closing. I am not going to lie after an hour of trying to troubleshoot; I  had begun to wonder if I had a virus or if my computer stopped working. It turns out that WinAppDriver is so fast that it will open a window and provide you with an error message but closes quickly and before you can read the error message the window is gone. Once I figure out how to properly run WinAppDriver, running the sample test was the easiest part to me.  After running the sample test, some questions plagued me. How come I must load the WinAppDriver.exe in command prompt whenever I run a test? Is there a way for me to program it into my code so that whenever I run any test, it automatically opens WinAppDriver for me? Apart from a few hiccups, the experience itself was great. It inspired me to try and build my sample test using Python.  Next, I will create a WordPad.exe sample test. I hope you enjoyed reading this blog. If not, that's okay as well; I will survive (Gloria Gaynor's voice). LOL. 

If you are interested in learning more about the WinAppDriver Project, check out the links below:

https://channel9.msdn.com/events/Connect/2016/202 (8min overview with demos)

https://channel9.msdn.com/events/Build/2016/Panel-Engineering-Quality (With Jonathan Lipps!)

https://channel9.msdn.com/events/Build/2016/P499 (Longer discussion)

https://www.youtube.com/watch?v=XAJVpvaEchY (c# demo with calculator sample walkthrough)

Follow me on twitter @Janemarette

Feel free to add comments and any additional tips you have on UI automation testing.