Automate Windows Calculator (UWP) with Appium 2

Drive Windows UWP apps with Appium 2.

In a previous article, I went through how to automate iOS apps with Appium. In this article, we will drive a Windows app with Appium 2 (currently in beta). The sample app for today is the Windows Calculator, a Universal Windows Platform (UWP) app.

Running the UWP automated test in TestWise

Now, I’ll share a step-by-step guide to doing the same on your machine.

Table of Contents:
· Set up Appium Server
· Set Up Appium Client
· First Appium Desktop Automated Script
· First Appium Desktop Automated Test

Set up Appium Server

Appium works as client-server architecture. The server needs to be running to receive instructions from the client(s).

1. Install the Appium server

Make sure you have Node.js installed with the version above 18.

Then, on the command line, install the Appium server with:

> npm install -g appium@next

2. Install the Appium Driver for Windows — WinAppDriver

Appium server drives an app via external driver software. The driver for Windows desktop native apps is called WinAppDriver.

Run the command below to install the WinAppDriver.

> appium driver install windows

Run appium driver list, to verify that windows is installed correctly.

> appium driver list
√ Listing available drivers
- windows@2.3.5 [installed (NPM)]
...

3. Enable Developer mode

Windows Developer mode allows Appium to control other applications. Make sure you have developer mode enabled in your settings.

Open the Settings app and go to Update & Security > For Developers (alternatively, just search for “Use developer features” in the windows search bar).

Set the switch for “Developer Mode” to enabled.

4. Start up the Appium server

Run appium in a command window and leave it open. The output should look like this:

> appium
[Appium] Welcome to Appium v2.0.0-beta.52
[Appium] Attempting to load driver windows...
[debug] [Appium] Requiring driver at C:\Users\ME\node_modules\appium-windows-driver
[Appium] Appium REST http interface listener started on 0.0.0.0:4723
[Appium] Available drivers:
[Appium]   - windows@2.3.5 (automationName 'Windows')
[Appium] No plugins have been installed. Use the "appium plugin" command to install
the one(s) you want to use.

Set Up Appium Client

The client here means automated tests + appium client library, in the same language. The choices are Ruby, Java, C#, Javascript and Python. Like my previous article, I will use Ruby, the best scripting language for test automation.

To install Ruby, download the Windows Ruby Installer and follow the installation wizard.

Verify Ruby was installed correctly by running ruby -v on the command line.

Install the Ruby Appium client library, appium_lib .

> gem install --no-document appium_lib

Verify appium_lib was installed with:

> gem list appium

*** LOCAL GEMS ***
appium_lib (12.1.3)
appium_lib_core (5.7.0)

First Appium Desktop Automated Script

Now, we can start to write our first automated script and verify the above steps all worked correctly.

Save the below into a file named simple_calc.rb .

require 'appium_lib'

opts = {
  caps: {
    automationName: "windows",
    platformName: "Windows",
    deviceName: "Dell",
    app: "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"
  },
  appium_lib: {
    server_url: "http://127.0.0.1:4723"
  } 
}

driver = Appium::Driver.new(opts).start_driver

driver.find_element(:name, "One").click
driver.find_element(:name, "Plus").click
driver.find_element(:name, "Three").click
driver.find_element(:name, "Equals").click
result = driver.find_element(:accessibility_id, "CalculatorResults").text
puts result

Readers, who have worked with Selenium WebDriver for web test automation, will find the syntax very familiar. Yes, they are. This is one of The Benefits of Using WebDriver, a W3C standard, in Test Automation.

Run it on the command line with ruby simple_calc.rb. The output should look like below:

> ruby simple_calc.rb
Display is 4

On the desktop, you should also see the Calculator app open and the calculation of 1 + 3.

A brief explanation of the above script:

opts = {
  caps: {
    automationName: "windows",
    platformName: "Windows",
    deviceName: "Dell",
    app: "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"
  },
  appium_lib: {
    server_url: "http://127.0.0.1:4723" # port appium server is running on
  } 
}

opts stores the options for Appium to start up the Calculator app. These options contain some capabilities (caps) which include:

• automationName (driver)
• platformName (OS/platform)
• deviceName (this is mostly optional, but the name of your device).
• app (specify which app to drive)

UWPs have a unique App ID for identification. Calculator’s appID is Microsoft.WindowsCalculator_8wekyb3d8bbwe!App.

To find a UWP’s App ID, run the following in Windows Powershell (I used Calculator as an example, but you can replace it with any application name):

> Get-AppxPackage | out-string -stream | select-string Calculator

Name              : Microsoft.WindowsCalculator
PackageFullName   : Microsoft.WindowsCalculator_11.2210.0.0_x64__8wekyb3d8bbwe
InstallLocation   : C:\Program Files\WindowsApps\Microsoft.WindowsCalculator_11.2210.0.0_x64__8wekyb3d8bbwe
PackageFamilyName : Microsoft.WindowsCalculator_8wekyb3d8bbwe

The final App ID is the PackageFamilyName + !App.

First Appium Desktop Automated Test

The previous script is an automation script, not a test script because it lacks assertions. We can easily convert it to a test script in the RSpec framework (version 3.8 has over 208 million downloads).

Install the RSpec gem from a command window:

> gem install rspec

The below test script (named calc_spec.rb) opens the Calculator app, does a simple addition (1 + 3) and asserts the result.

require 'appium_lib'
require 'rspec'

describe "Appium Windows UWP App - Calculator" do
  before(:all) do
    opts = {
      caps: {
        automationName: "windows",
        platformName: "Windows",
        deviceName: "Dell",
        app: "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App"
      },
      appium_lib: {
        server_url: "http://127.0.0.1:4723"
      } 
    }
    @driver = Appium::Driver.new(opts).start_driver
  end

  after(:all) do
    @driver.quit
  end

  it "Simple Addition" do
    @driver.find_element(:name, "One").click
    @driver.find_element(:name, "Plus").click
    @driver.find_element(:name, "Three").click
    @driver.find_element(:name, "Equals").click
    result = @driver.find_element(:accessibility_id, "CalculatorResults").text
    expect(result).to eq("Display is 4")
  end
end

Run the test script in TestWise (a testing IDE) like in the video, or from the command line with:

> rspec calc_spec.rb