WinAppDriver

Selenium driver for WinForms applications

Any contributions are welcomed :)

This project is using

• Windows Automation
• Nancy as the webserver
• XPathParser for parsing XPath expressions (https://github.com/quamotion/XPathParser)
• Selenium.WebDriver.3.141.0 to get the internals of web driver (commands for Nancy endpoints for example)
• windowsphonedriver (https://github.com/forcedotcom/windowsphonedriver) for the basic infrastructure (commands & command handlers)

Why another driver, when there already is https://github.com/Microsoft/WinAppDriver? The app I'm testing is quite large with many elements, and that driver was timing out after 60 seconds on some XPath queries (see this issue), and after putting everything together, the query finished under 2 seconds.

Installation

Currently, there is no installer. Clone the repository and build the executable from the sources.

Selenium

Client driver version

Latest client driver version 3.141.0.0 must be used when calling the server.

Which Selenium commands are implemented?

• acceptAlert
  • default captions to locate the accept button are Ok and Yes, additional captions can be added by setting acceptAlertButtonCaptions capability with a semicolon separated list of values
• actions
• clearElement
• clickElement
• close
• describeElement
• dismissAlert
  • default captions to locate the accept button are Cancel and No, additional captions can be added by setting dismissAlertButtonCaptions capability with a semicolon separated list of values
• elementEquals
• executeAsyncScript
• executeScript
• findChildElement
• findChildElements
• findElement
• findElements
• getActiveElement
• getAlertText
• getCurrentWindowHandle
• getElementAttribute
• getElementLocation
• getElementLocationOnceScrolledIntoView
• getElementSize
• getElementTagName
• getElementText
• getElementValueOfCssProperty
• getSessionCapabilities
• getSessionList
• getTitle
• getWindowHandles
• getWindowPosition
• getWindowRect/getWindowSize
• implicitlyWait
• isElementDisplayed
• isElementEnabled
• isElementSelected
• maximizeWindow
• mouseClick
• mouseDoubleClick
• mouseDown
• mouseMoveTo
• mouseUp
• newSession
• quit
• screenshot
• sendKeysToActiveElement
• sendKeysToElement
• setAlertValue
• setTimeout
• setWindowPosition
• setWindowSize
• status
• submitElement
• switchToWindow
• touchDoubleTap
• touchDown
• touchFlick
• touchLongPress
• touchMove
• touchScroll
• touchSingleTap
• touchUp
• uploadFile

Unsupported Selenium commands

• addCookie
• deleteAllCookies
• deleteCookie
• get
• getCookies
• getCurrentUrl
• getOrientation
• getPageSource
• goBack
• goForward
• refresh
• setOrientation
• setScriptTimeout
• switchToFrame

XPath support:

• axes
  • Ancestor
  • AncestorOrSelf
  • Attribute
  • Child
  • Descendant
  • DescendantOrSelf
  • Following
  • FollowingSibling
  • Namespace
  • Parent
  • Preceding
  • PrecedingSibling
  • Self
  • Root
• predicates
  • position predicate //node[3]
  • attribute predicate //node[@attribute = 'X']
• operators
  • Or
  • And
  • Eq
  • Ne
  • Lt
  • Le
  • Gt
  • Ge
  • Plus
  • Minus
  • Multiply
  • Divide
  • Modulo
  • UnaryMinus
  • Union
• functions (https://developer.mozilla.org/en-US/docs/Web/XPath/Functions)
  • boolean()
  • ceiling()
  • choose()
  • concat()
  • contains()
  • count()
  • current() XSLT-specific
  • document() XSLT-specific
  • element-available()
  • false()
  • floor()
  • format-number() XSLT-specific
  • function-available()
  • generate-id() XSLT-specific
  • id() (partially supported)
  • key() XSLT-specific
  • lang()
  • last()
  • local-name()
  • name()
  • namespace-uri()
  • normalize-space()
  • not()
  • number()
  • position()
  • round()
  • starts-with()
  • string()
  • string-length()
  • substring()
  • substring-after()
  • substring-before()
  • sum()
  • system-property() XSLT-specific
  • translate()
  • true()
  • unparsed-entity-url() XSLT-specific (not supported)

Appium Support

Only this Appium command is implemented

• closeApp

How to create a session

Add a reference to Selenium.WebDriver v3.141.0 (https://www.nuget.org/packages/Selenium.WebDriver/3.141.0) and you are ready to go.

The driver can either start the system under test process or attach to a running process. Use capabilities to define the process to attach to.

When no command-line argument is provided, the server will be launched at default IP address http://127.0.0.1:4444.

Desired capabilities

Following capabilities are supported:

• mode - start (default value) or attach
• processId - id of the process to attach to
• processName - name of the process to attach to
• exePath or app - path to the executable to start the process (arguments cannot be provided at the moment)
• mainWindowTitle - regular expression to help the WinAppDriver narrow down the process to attach to

Creating session

public static RemoteWebDriver CreateSessionByStartingTheApplication()
{
  DesiredCapabilities desktopCapabilities = new DesiredCapabilities();
  desktopCapabilities.SetCapability("app", "<name of the program to start>");  
  // or "exePath" desktopCapabilities.SetCapability("exePath", "<path to the executable to start the process>");  
  // following capabilities should be provided for UWP applications like Calculator or Clocks & Alarms 
  // optional - to identify the process
  desktopCapabilities.SetCapability("processName", "<name of the process>"); 
  // optional - to identify the main window
  desktopCapabilities.SetCapability("mainWindowTitle", "<name of the process>");  
  return new RemoteWebDriver(
    new CommandExec(new Uri("http://127.0.0.1:4444"), 
    TimeSpan.FromSeconds(60)), 
    desktopCapabilities);
}

public static RemoteWebDriver CreateSessionByAttachingToRunningProcess()
{
  DesiredCapabilities desktopCapabilities = new DesiredCapabilities();
  desktopCapabilities.SetCapability("mode", "attach");
  // attach to process using process name
  desktopCapabilities.SetCapability("processName", "<name of the process to attach to>");
  // with (optional)
  desktopCapabilities.SetCapability("windowTitle", "<regular expression to narrow down the list of matching processes>");
  // or attach to process using process id
  desktopCapabilities.SetCapability("processId", "<id of the process to attach to>");
  
  return new RemoteWebDriver(
    new CommandExec(new Uri("http://127.0.0.1:4444"), 
    TimeSpan.FromSeconds(60)), 
    desktopCapabilities);
}

Recommended element location is using XPath expression (though with a limited expression support)

var webBrowser = session.FindElement(By.XPath("//Pane[@AutomationId='webBrowser']"));

Element location mechanisms that are supported

• XPath
• Id, i.e. UI automation element automation id
• CSS class (limited)
  • tag name, for example TextBox
  • id, for example #id
• Class name, i.e. UI automation element class name
• Tag name
• Accessibility id, i.e. UI automation element automation id
• Name, i.e. UI automation element name

Windows in the Win application are not like windows in the browser. The windows (ControlType.Window) can be nested inside the control tree, for example in a Tab element.

Window can be either located using XPath expression var window = session.FindElement(By.XPath("/Window/Pane/Window[@AutomationId='WindowName']")); or by switching to it session.SwitchTo().Window("WindowName");, in the first example you will get the element reference, in the other the internal context is switched to new window and elements cached during the following operations can be disposed when window is cloded session.Close().

Note that element wrappers like OpenQA.Selenium.Support.UI.SelectElement do not work because internally select and option elements are expected.

Note

There is quite an ugly hack which bypasses the need to switch windows when searching for a child window using XPath expression. By default, the search starts at the root element of a window - the main window or the window the user switched to - and the search for a child window was failing since it was not a direct child of the current root. The fix starts the search for a window at the top level.