The WinAppDriver linkage function uses the UIAutomation interface provided by the Nexacro Platform 17 to read or write properties of apps running in NRE and to support methodological execution by specifying parameters. You can write unit tests and test using UI automation testing tools, such as Selenium.

In this chapter, we will look at the steps to install the WinAppDriver, create basic C# and Java projects in Visual Studio and Eclipse, and connect them to the Nexacro Platform apps.

Configuring the WinAppDriver Linkage

Installing the WinAppDriver

Installing the Development Tools

Unit test projects can be created using the C# or Java languages.

Installing Visual Studio

In the case of using the C# language and Visual Studio not being installed, you can install the development tool provided for free.

Installing Eclipse

In the case of using the Java language and Eclipse not being installed, you can install the development tool provided for free.

Creating & Running a Unit Test

Creating & Deploying the Nexacro Platform App

Create and deploy a simple Nexacro Platform app.

Place only the Button component and the Edit component on the screen.

When the Button component onclick event occurs, change the value property value in the Edit component.

this.Button00_onclick = function(obj:nexacro.Button,e:nexacro.ClickEventInfo)
{
	this.Edit00.set_value("BUTTON CLICK");
};

Set the Update Type to "Local" so that it can run without a server connection.

Creating a Unit Test Project

Creating a Unit Test Project in Visual Studio

Select the menu [Project > Manage NuGet Package] and then enter "Appium" in the search window to check the Appium WebDriver library in the search results. Click the [Install] button to install the library.

Modify the settings related to the Nexacro Platform app through the code below. Modify the pathway where the app is installed, the path to the nexacro.exe executable file, and the nexacro.exe execution option to match the actual installation path.

http://127.0.0.1:4723/

C:\\Program Files\\nexacro\\17\\app0201

C:\\Program Files\\nexacro\\17\\app0201\\nexacro.exe

-k 'UnitTest' -s 'C:\\Program Files\\nexacro\\17\\app0201\\app0201\\start.json'

using System;
using System.Threading;
using System.Diagnostics;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using OpenQA.Selenium.Appium.Windows;
using OpenQA.Selenium.Remote;

namespace UnitTestProject1
{
	[TestClass]
	public class NexaTestSession
	{
		// winappdriver url
		protected const string WindowsApplicationDriverUrl = "http://127.0.0.1:4723/";
		// app path
		private const string NexacroAppDr = "C:\\Program Files\\nexacro\\17\\app0201";
		// nexacro.exe path
		private const string NexacroAppId = "C:\\Program Files\\nexacro\\17\\app0201\\nexacro.exe";
		// nexacro.exe argument
		private const string NexacroAppAg = "-k 'UnitTest' -s 'C:\\Program Files\\nexacro\\17\\app0201\\app0201\\start.json'";
		// search root
		private const string FindNexacro = "Root";
		// OS/Device
		private const string TestOs = "Windows";
		private const string TestDevice = "WindowsPC";

		// Session Object : WindowsDriver 
		protected static WindowsDriver<WindowsElement> session;

		// WinAppDriver Session Create
		[ClassInitialize]
		public static void Setup(TestContext context)
		{
			// Launch a new instance of nexacro application or find nexacro application
		}

		// WinAppDriver Session Delete
		public static void TearDown()
		{
            // Close the application and delete the session
            if (session != null)
            {
                // Close Session – Close Application
                session.Close();
                // Quit Session
                session.Quit();
                // Delete Session
                session = null;
            }
		}

		[TestMethod]
		public void Test_Session()
		{
            Debug.WriteLine("session:" + session);
            Debug.WriteLine("session.SessionId:" + session.SessionId);
		}
	}
}

Modify the Setup method in the code above as follows.

// WinAppDriver Session Create
[ClassInitialize]
public static void Setup(TestContext context)
{
	// Launch a new instance of nexacro application or find nexacro application
	if (session == null)
	{
		// Create a new session to launch nexacro application
		DesiredCapabilities appCapabilities = new DesiredCapabilities();
		TimeSpan time = new TimeSpan(0, 0, 10);

		// Launch Nexacro
		appCapabilities.SetCapability("app", NexacroAppId);
		appCapabilities.SetCapability("appArguments", NexacroAppAg);
		appCapabilities.SetCapability("appWorkingDir", NexacroAppDr);
		appCapabilities.SetCapability("platformName", TestOs);
		appCapabilities.SetCapability("deviceName", TestDevice);

		// Request Remote WinAppDriver Service
	session = new WindowsDriver<WindowsElement>(new Uri(WindowsApplicationDriverUrl), appCapabilities, time);

		// Set implicit timeout to 1.5 seconds to make element search to retry every 500 ms for at most three times
		session.Manage().Timeouts().ImplicitlyWait(TimeSpan.FromSeconds(0.5));
		Thread.Sleep(TimeSpan.FromSeconds(1.0));
	}
}

You can check the access information and session being created on the console screen where the WinAppDriver was executed.

Creating the Unit Test Project in Eclipse

Modify the settings related to the Nexacro Platform app in the code below. Modify the pathway where the app is installed, the pathway to the nexacro.exe executable file, and the nexacro.exe execution option to match the actual installation pathway.

http://127.0.0.1:4723/

C:\\Program Files (x86)\\nexacro\\17\\app0201

C:\\Program Files (x86)\\nexacro\\17\\app0201\\nexacro.exe

-k 'UnitTest' -s 'C:\\Program Files (x86)\\nexacro\\17\\app0201\\app0201\\start.json'

import org.junit.*;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebElement;
import io.appium.java_client.windows.WindowsDriver;
import java.util.concurrent.TimeUnit;
import java.net.URL;

public class UnitTest {

	// winappdriver url
	private String WindowsApplicationDriverUrl = "http://127.0.0.1:4723/";
	// app path
	private String NexacroAppDr = "C:\\Program Files (x86)\\nexacro\\17\\app0201";
	// nexacro.exe path
	private String NexacroAppId = "C:\\Program Files (x86)\\nexacro\\17\\app0201\\nexacro.exe";
	// nexacro.exe argument
	private String NexacroAppAg = "-k 'UnitTest' -s 'C:\\Program Files (x86)\\nexacro\\17\\app0201\\app0201\\start.json'";
	// search root
	// private String FindNexacro = "Root";

	// OS/Device
	private String TestOs = "Windows";
	private String TestDevice = "WindowsPC";

	// Session Object : WindowsDriver
	private static WindowsDriver<RemoteWebElement> session = null;
	

	@Before
	public void setUp() throws Exception {
		// Launch a new instance of nexacro application or find nexacro application
	}

	@After
	public void tearDown() throws Exception {
		if (session != null) {
			// Nexacro17Session.quit();
		}
	}

	@Test
    public void Test_01_Session()
    {
        System.out.println("session : " + session);
		System.out.println("session.SessionId : " + session.getSessionId());        
    }
}

Modify the Setup method in the code above as follows.

@Before
public void setUp() throws Exception {
	// Launch a new instance of nexacro application or find nexacro application
	try {
		// Create a new session to launch nexacro application
		DesiredCapabilities appCapabilities = new DesiredCapabilities();

		appCapabilities.setCapability("app", NexacroAppId);
		appCapabilities.setCapability("appArguments", NexacroAppAg);
		appCapabilities.setCapability("appWorkingDir", NexacroAppDr);
		appCapabilities.setCapability("platformName", TestOs);
		appCapabilities.setCapability("deviceName", TestDevice);

		// Request Remote WinAppDriver Service
		session = new WindowsDriver<RemoteWebElement>(new URL(WindowsApplicationDriverUrl), appCapabilities);
		session.manage().timeouts().implicitlyWait(1, TimeUnit.SECONDS);

	} catch (Exception e) {
		e.printStackTrace();
	} finally {
	}
}

You can check the access information and session being created on the console screen where the WinAppDriver was executed.

Running the Unit Test

Find the Button component in the current session and then process the mouse click command.

$r_title(C#)
[TestMethod]
public void Test_Button()
{
	WindowsElement element = session.FindElementByAccessibilityId("mainframe.WorkFrame.form.Button00");
	Assert.IsNotNull(element);
	Thread.Sleep(TimeSpan.FromSeconds(0.1));
	element.Click();
}

$r_title(Java)
@Test
public void Test_Button() throws Exception {
	WebElement element = session.findElementByAccessibilityId("mainframe.WorkFrame.form.Button00");
	Assert.assertNotNull(element);
	Thread.sleep(1000);
	element.click();
}

Checking the AccessibilityId Property Value

To access the component or control, the FindElementByAccessibilityId method is used, and you need to check the AccessibilityId property value at this time.

Checking the Component Property Value

The method to access the component itself placed on the form is as follows.

[MainFrame id property value].[ChildFrame id property value].form.[Component id property value]

To get the element of the Button component with the id property value being "Button00", write the following code.

$r_title(C#)

WindowsElement element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Button00");

Components placed in the Div component can be accessed as follows.

$r_title(C#)

WindowsElement element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Div00.form.CheckBox00");

Checking the Control & the Item Property Values

For example, the dropbutton of the Combo component placed in the Div component can generate the element as below.

$r_title(C#)

WindowsElement element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Div00.form.Combo00.dropbutton");

To proceed with the unit test, you need to expand the dropdown list of the Combo component and then select the item. To expand the dropdown list, you need to access the ButtonControl in the Combo component and then check the property value of the control.

The control property value can be checked in the component overview by running Help (shortcut key F1) in the Nexacro Studio. You can check that the id property value of the button clicked to expand the dropdown list in the Combo component is "dropbutton".

Checking the Property Value with Inspect

However, it does not tell you how to access Item 3 after expanding the dropdown list. In this case, you can use the tool called "Inspect". "Inspect" can be found in the installation pathway if Windows SDK is installed.

Various information is displayed, and the item to be used as the AccessibilityId property value among them is "AutomationId".

When selecting the 2^nd item from the dropdown list, you can generate the element as shown below.

$r_title(C#)

WindowsElement element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Div00.form.Combo00.combolist.item_1");

The element corresponding to the item can be accessed after the dropdown list is expanded. If you try to access the item before expanding the list, then it will be processed as a test failure.

In the test code, find the dropbutton element first, process the mouse click event, and then access the desired item when the dropdown list is expanded.

$r_title(C#)

[TestMethod]
public void Test_00_FindElementItem()
{
	WindowsElement element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Div00.form.Combo00.dropbutton");
	Assert.IsNotNull(element);
	element.Click();
	Thread.Sleep(TimeSpan.FromSeconds(0.1));
	WindowsElement elementItem = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Div00.form.Combo00.combolist.item_1");
	Assert.IsNotNull(elementItem);
	Debug.WriteLine("elementItem.Text:" + elementItem.Text);
}

Running the Demo Unit Test by Feature

You can download the Nexacro Platform app installation file and the Java and C# sample files to run demos by feature.

https://github.com/TOBESOFT-DOCS/sample_nexacroplatform_17_winappdriver

You can see 2 folders and 1 installation file.

C:\Program Files (x86)\nexacro\17\app0201

Supported Interface

Session

Creating a Session

Create the session with the winappdriver information and then run the app.

session = new WindowsDriver(new Uri(WinAppDriverUrl), appCapabilities);

session = new WindowsDriver(new URL(WindowsApplicationDriverUrl), appCapabilities);

POST /session { …capabilities json data… }

Ending a Session

End the session and then close the app.

session.Quit();

session.quit();

DELETE /session/:session_id

Timeout

Setting a Timeout

Set the timeout value to be applied during the session operation.

session.Manage().Timeouts().ImplicitlyWait(TimeSpan.FromSeconds(0.5));

session.manage().timeouts().implicitlyWait(1, TimeUnit.SECONDS);

POST /session/:session_id/timeouts {"type":"implicit","ms":500.0}

Frame

Checking the Mainframe Information

Return the titletext property value of the MainFrame object.

session.Title;

session.getTitle();

GET /session/:sessionId/title

Window

Changing the Enabled Window

Change the current window. Windowhandle can be obtained from session.WindowHandles. For the initial execution, the MainFrame object is set as the current window.

session.SwitchTo().Window(session.WindowHandles[0]);

Set<String> handles = session.getWindowHandles();
Set handles = session.getWindowHandles();

POST /session/:sessionId/window {"name":"0x000A12BC"}

Ending the Enabled Window

End the current window.

session.Close();

session.close();

DELETE /session/:sessionId/window

Obtaining the Enabled Window Handle

Return the current window handle object.

handle = session.CurrentWindowHandle;

Handle = session.getWindowHandle();

GET /session/:sessionId/window_handle

Obtaining the Window Handle Array

Return all window handle objects as an array.

handlearray = session.WindowHandles;

Set handles = session.getWindowHandles();

GET /session/:sessionId/window_handles

Checking the Window Size Information

Return the window size in the form of the Size object.

session.Manage().Window.Size;

session.getWindowHandles().size()

GET /session/:sessionId/window/:windowHandle/size

Changing the Window Size

Change the window size.

session.Manage().Window.Size = new Size(width,height);

session.manage().window().setSize(new Dimension(width, height));

POST /session/:sessionId/window/:windowHandle/size

Checking the Window Position Information

Return the window position in the form of the Point object.

point = session.Manage().Window.Position;

point = session.manage().window().getPosition()

GET /session/:sessionId/window/:windowHandle/position

Changing the Window Position

Change the window coordinates.

session.Manage().Window.Position = new Point(left,top);

session.manage().window().setPosition(new Point(left, top))

POST /session/:sessionId/window/:windowHandle/position

Maximizing the Window

Maximize the window size.

session.Manage().Window.Maxmize();

session.manage().window().maximize();

POST /session/:sessionId/window/:windowHandle/maximize

Element

Element is the smallest unit of the WinAppDriver operation. In the Nexacro Platform, nexacro Element, which is the element of components and controls, is processed as Element.

ControlElement surrounds the component and Elements, such as ContainerElement, InputElement, IconTextElement, TextElement, are located inside. In the case of the Button component, it is configured as follows.

Obtaining the Element

Return the ControlElement object of the component and control.

element = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.Button00");

element = session.findElementByAccessibilityId("mainframe.ChildFrame00.form.Button00");

POST /session/:sessionId/element 
{ "using":"accessibilityid", "value":"mainframe.ChildFrame00.form.Button00" }

$r_title(C#)
// When specifying parent null: nexacro.open("openframe", url, null, ...) 
nexaButton00 = session.FindElementByAccessibilityId("openframe.form.Button00");

// When specifying parent frame: nexacro.open("openframe", url, ownerframe, ...)
nexaButton00 = session.FindElementByAccessibilityId("mainframe.ChildFrame00.openframe.form.Button00");

Obtaining the Element Array

Return the ControlElement object list of component and control as an array value.

element = session.FindElementsByAccessibilityId("mainframe.ChildFrame00.form.Button00");

element = session.findElementsByAccessibilityId("mainframe.ChildFrame00.form.Button00");

POST /session/:sessionId/elements 
{ "using":"accessibilityid", "value":"mainframe.ChildFrame00.form.Button00" }

Checking the Element id Value

Return the id value of the WinAppDriver Element.

id = element.Id;

id = element.getTagName()

GET /session/:sessionId/element/:id/name

Checking the Text Information Displayed on Element

Return the text value of Element.

text = element.Text;

text = element.getText();

GET /session/:sessionId/element/:id/text

Processing the Element Mouse Click Event

The mouse click event occurs at the center of the Element.

element.Click();

element.click();

POST /session/:sessionId/element/:id/click

$r_title(C#)

[TestMethod]
public void Test_10_MaskEditInput()
{
	WindowsElement nexaMaskEdit00 = session.FindElementByAccessibilityId("mainframe.ChildFrame00.form.MaskEdit00");
	Assert.IsNotNull(nexaMaskEdit00);
	Thread.Sleep(TimeSpan.FromSeconds(0.1));

	nexaMaskEdit00.Clear();
	nexaMaskEdit00.Click();
	nexaMaskEdit00.SendKeys(Keys.Control + "a");
	Thread.Sleep(TimeSpan.FromSeconds(0.1));
	nexaMaskEdit00.SendKeys("abcde1234"+Keys.Enter);
	Assert.AreEqual("abcde-1234", nexaMaskEdit00.Text);
}

Deleting the Element Input Value

Delete the input value of the component with the text editing area.

element.Clear();

element.clear();

POST /session/:sessionId/element/:id/clear

Passing the Keyboard Input Value to Element

Process the keyboard input value.

element.SendKeys(KeyString)

element.sendKeys(KeyString)

POST /session/:sessionId/element/:id/value

Checking Whether the Element is Selected

Return the Selected status value of the Element.

isSelected = element.Selected;

isSelected = element.isSelected();

GET /session/:sessionId/element/:id/selected

Checking Whether the Element Can be Used

Return the Enabled status value of the Element.

isEnabled = element.Enabled;

isEnabled = element.isEnabled();

GET /session/:sessionId/element/:id/enabled

Checking Whether the Element Screen is Displayed

Return whether the Element is displayed.

isDisplayed = element.Displayed;

isDisplayed = element.isDisplayed();

GET /session/:sessionId/element/:id/displayed

Checking the Element Size Information

Return the Element size in the form of the Size object.

size = element.Size;

size = element.getSize();

GET /session/:sessionId/element/:id/size

Checking the Element Position Information (Based on the Parent Element)

Return the Element position in the form of the Point object based on the parent Element.

size = element.Location;

size = element.getLocation();

GET /session/:sessionId/element/:id/location

Checking the Element Position Information (Based on the Screen)

Return the Element position in the form of the Point object based on the Screen.

size = element.LocationOnScreenOnceScrolledIntoView;

GET /session/:sessionId/element/:id/location_in_view

Obtaining the Enabled Element

Return the currently enabled Element.

element = session.SwitchTo().ActiveElement();

element = session.switchTo().activeElement();

GET /session/:sessionId/element/active

Comparing 2 Elements

Compare Elements to see if they are the same Element.

isEqual = element.Equals(element2);

isEqual = element.equals(element2);

GET /session/:sessionId/element/:id/equals

Checking the UIA Interface Attribute Value of the Element

Provide the attribute value of the UIA Interface of the Element.

element.GetAttribute("AutomationId");

element.getAttribute("AutomationId");

GET /session/:sessionId/element/:id/attribute/:name

ScreenShot

Obtaining the Window & Element Screenshot

Return the Screen window area or the Element as a Screenshot object.

Screenshot sessionshot = session.GetScreenshot();

Screenshot sessionshot = session.getScreenshotAs();

GET /session/:sessionId/screenshot 
GET /session/:sessionId/element/:id/screenshot

$r_title(Java)

FileHandler.copy(sessionshot, new File(System.getProperty("user.home")+"\\Downloads\\SessionScreenShot.png"));

Related Link Information

WebDriver Interface

http://www.w3.org/TR/webdriver1/
https://www.seleniumhq.org/projects/webdriver/
https://developer.mozilla.org/en-US/docs/Web/WebDriver

AppDriver Interface

https://github.com/Microsoft/WinAppDriver
https://appium.io/docs/en/drivers/windows/
https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/

UIA Interface

https://docs.microsoft.com/en-us/windows/desktop/WinAuto/entry-uiauto-win32
https://docs.microsoft.com/en-us/windows/desktop/winauto/testing-tools
https://en.wikipedia.org/wiki/Microsoft_UI_Automation

MSAA Interface

https://docs.microsoft.com/en-us/windows/desktop/WinAuto/microsoft-active-accessibility
https://docs.microsoft.com/en-us/windows/desktop/winauto/testing-tools
https://en.wikipedia.org/wiki/Microsoft_Active_Accessibility