1. Docs
  2. Use cases
  3. Use cases
  4. How do I test a Windows or macOS desktop application?

How do I test a Windows or macOS desktop application?

In SmartestQA a desktop application is tested in a DESKTOP project: the agent and Appium run on the Windows PC or Mac where the app is installed, you add the app in Desktop Configuration and record its controls with the Desktop Recorder. Dry runs and pipelines then run on that agent with Run on Your Agent.

10 min read Updated CustomersAdmins

In short

On this page you can

  • Test Windows apps (Store / UWP, Win32, WPF, WinForms) and macOS apps in one project type.
  • Record clicks and keys in the running app with the Desktop Recorder.
  • Keep several applications in one project and choose one per test case or pipeline.
  • Check controls with seven assertion types and read values into variables.
  • Run on a schedule on an agent on the machine with the app.

How to use it

  1. Prepare the machine: Node.js, Appium and the driver, then start the agent with its API key.
  2. Open Desktop Configuration, set Platform and click Save Configuration.
  3. Click Add application and fill the name and the app identifier or path.
  4. Click Desktop Recorder, click the controls in the app and save.
  5. Run a Dry Run, then a pipeline with Run on Your Agent.

The short answer#

Desktop apps are tested in a DESKTOP project, and DESKTOP projects cover Windows and macOS. A desktop application can be opened only on the machine where it is installed, so the SmartestQA agent and Appium run on that machine: a Windows PC for a Windows app, a Mac for a macOS app. On Windows the runner uses the Windows driver with WinAppDriver; on a Mac it uses Appium’s Mac2 driver, which works through Apple’s XCTest.

You describe the app once in Desktop Configuration, record its controls with the Desktop Recorder, and build test cases from desktop step types such as Click, Type Text, Press Key and Assert Text. Runs happen on agents only: a Dry Run lists the agents under Device (agent), and a pipeline offers Run on Your Agent only.

The problem this solves#

Many business applications are still desktop clients: an ERP client, a claims system, a point-of-sale program. A browser test tool cannot open them, so many teams test them by hand before each release, with the same clicks through the same windows every time.

Scripts are possible, but they need a driver, someone who knows it, and the machine where the app is installed. Such scripts often live on one person’s PC. What is missing is a way to record a desktop test instead of coding it, keep it next to the web and mobile tests, and run it on a schedule on the machine that has the app.

An example#

This is an illustration, not a customer story. A team at an insurer tests its Windows claims client, a WPF application, by hand before each release.

  1. On the test PC a tester follows the Local Desktop Setup tab. Its single PowerShell line installs Appium, the Windows driver and WinAppDriver, turns on Developer Mode and starts Appium. appium driver list --installed shows windows, and after the agent starts its dot turns green.
  2. In Desktop Configuration the tester keeps the Platform Windows (WinAppDriver) and clicks Save Configuration: “Desktop configuration saved”. Then Add application, the Name Claims Client, the App Path (.exe) and Save: “Application added”.
  3. The tester clicks Desktop Recorder and clicks through the new claim window: the policy number field, the amount field and the Save button. The recorder adds the captured controls as steps.
  4. The tester adds an Assert Visible step on the confirmation and starts a Dry Run with This computer under Device (agent). The log has plain lines such as "Save" was clicked.
  5. In Schedule the pipeline’s Run Environment is Run on Your Agent. The tester ticks the agent on the test PC.

The check that a tester clicked through by hand now runs as a pipeline on the test PC, as long as the agent there is online.

By hand, with hand-written scripts, and with SmartestQA#

QuestionTesting by handHand-written scriptsSmartestQA
Which applications can be tested?Any app you can openWhat your driver supportsWindows apps (Store / UWP, Win32, WPF, WinForms) and macOS apps, in a DESKTOP project
Who can create a test?Any testerSomeone who writes codeYou record the controls with the Desktop Recorder and build the test from step types such as Click, Type Text and Press Key
Where does the test run?On the tester’s PCOn the machine with the app, where you installed the driver and a runnerOn an agent on the machine with the app. Desktop tests do not run on the SmartestQA server
Can it run without a person?NoYes, when you build a scheduled job around the scriptsYes: a pipeline with Run on Your Agent and at least one online agent
What happens when the UI changes?The tester adapts on the spotSomeone updates the locators in the codeDesktop locators can be auto-healed when the project’s AI is on; each repair waits for your decision in Maintenance

Steps#

  1. Prepare the machine with the app

    Windows: in a DESKTOP project open Device FarmTest Agents and follow the Local Desktop Setup tab. Its single PowerShell line installs Appium and the Windows driver, installs the latest WinAppDriver, turns on Developer Mode, frees port 4723 and starts Appium. Mac: the tab shows the Windows steps, so follow Mac for desktop tests: Xcode 13 or newer, Appium with the Mac2 driver, and the macOS permissions. Both need a current LTS version of Node.js.

  2. Verify the driver and connect the agent

    Run appium driver list --installed in a second terminal. Then start the agent with its API key (Download Client).

    windows or mac2 is in the list of installed drivers, and the agent’s dot turns green. The machine is ready for desktop runs and the Desktop Recorder.

  3. Set the platform

    Open Desktop Configuration in the Project Panel. Under General Settings choose the Platform: Windows (WinAppDriver) or macOS (Mac2Driver). Appium Server URL defaults to http://localhost:4723. Click Save Configuration. See General Settings.

    “Desktop configuration saved”.

  4. Add the application

    Under Applications click Add application. Fill Name, for example ERP Client, and at least one of the identifier and the path: AUMID / App ID or App Path (.exe) on Windows, Bundle ID or App Path (.app) on macOS. Click Save. See Applications.

    “Application added”. The first application of a project becomes the default.

  5. Record the app

    In the DESKTOP project click Desktop Recorder. Fill Target Application, Platform and the app identifier, optionally App Path and App Arguments; Page Name defaults to Desktop. Click the controls in the app and save. The values from Desktop Configuration are pre-filled. See Discover › Desktop.

  6. Complete the test case

    The Desktop Recorder adds the captured controls as steps. Saved desktop actions are also in the Action List. Global opens Global Desktop Actions with steps that need no element, such as Press Enter, Save (Ctrl+S), Launch App and Take Screenshot; click Add to step list. See Desktop steps.

  7. Try it with a Dry Run

    Start a Dry Run and choose the agent under Device (agent): This computer or a Remote device. Offline agents are marked. Each step writes a plain message, for example "Save" was clicked or Key "Ctrl+S" was pressed.

  8. Put it in a pipeline

    In Schedule the Run Environment of a desktop pipeline is Run on Your Agent only. Tick at least one online agent on the machine with the app. Application chooses “Each test case's own application” or one application for every case. See Desktop projects.

Windows and macOS side by side#

WindowsmacOS
Platform in Desktop ConfigurationWindows (WinAppDriver), the defaultmacOS (Mac2Driver)
Setup guideThe Local Desktop Setup tab, titled Local Desktop (Windows) SetupMac for desktop tests; you need an administrator account on the Mac
What is installedNode.js, Appium, the Windows driver, WinAppDriver; Developer Mode onXcode 13 or newer, Node.js, Appium, the Mac2 driver
Installed driver shown aswindowsmac2
App identifierAUMID / App ID for Store / UWP appsBundle ID, for example com.example.MyApp
App pathApp Path (.exe) for classic Win32, WPF and WinForms appsApp Path (.app), for example /Applications/MyApp.app; the runner reads the bundle ID from the app when you give only the path
System permissionsAdministrator approval once, for WinAppDriverAccessibility, Screen Recording and Input Monitoring under Privacy & Security
Attach to a running windowAn option for WebView2 and PWA apps, with Window Title (attach)Not offered; the dialog hides it for macOS
Agent downloadSmartTest-Desktop-Windows-latest.zipSmartTest-Desktop-macOS-latest.zip

Desktop step types#

GroupStep types
MouseClick, Double Click, Right Click, Hover
Input and keysType Text, Clear, Clear & Type, Type Key by Key, Press Key (Enter, Tab, Esc, Ctrl+S, Alt+F4), Select
Scrolling and waitsScroll, Scroll To Element, Wait For Element, Wait For Visible, Wait
AssertionsAssert Visible, Assert Not Visible, Assert Exists, Assert Not Exists, Assert Enabled, Assert Checked, Assert Text
Read valuesGet Text, Get Attribute, Store Variable
App and windowLaunch App, Close App, Switch Window, Maximize Window, Screenshot

Shared step types work in desktop projects too: Assertion, Python, API, Database, Mail, Kafka, Global parameter, Wait (seconds), AI, JMeter and k6. JavaScript and Network steps are not available in desktop projects.

What you get#

  • One project type for two platforms. Each application in the list has its own platform, Windows or macOS.
  • Recorded locators, ranked. The Desktop Recorder keeps delphiPath (98), automationId (95), the element text (70) and an XPath.
  • Several applications per project. A run opens the application chosen in the pipeline, then the one chosen in the test case, then the project’s default.
  • Real keyboard input where it is needed. Type Key by Key types one key at a time, for password fields and fields that reject pasted or bulk input.
  • The same run settings as web and mobile. Retry count, wait timeout, continue on failure and screenshot on failure come from Test Management and each pipeline’s own settings.
  • Locator repair with review. Desktop locators can be auto-healed when the project’s AI is on; each repair waits for your decision in Maintenance.
  • Values between steps. Get Text, Get Attribute and Store Variable save a variable that later steps read as {{tc:name}}.

Questions and answers#

Can desktop tests run on the SmartestQA server?Customers

No. A desktop application can be opened only on the machine where it is installed, so desktop pipelines run on agents only. A desktop pipeline set to the server is moved to Run on Your Agent when you open it; save to keep it. See Desktop projects.

Does SmartestQA test macOS apps, or only Windows?Customers

Both. DESKTOP projects test Windows and macOS apps. On a Mac the runner drives the app with Appium’s Mac2 driver, and you choose the platform macOS (Mac2Driver) in Desktop Configuration. See Mac for desktop tests.

Which kinds of Windows application can I test?Customers

Store / UWP apps are added with their AUMID / App ID. Classic Win32, WPF and WinForms apps are added with App Path (.exe). For a WebView2 or PWA app, turn on the attach option in the application dialog: the runner attaches to a window instead of starting the app. See Applications.

Can a Windows agent test a macOS app, or the other way round?Customers

No. Desktop apps need an agent on the same operating system as the app: Windows apps a Windows agent, macOS apps a Mac agent. The agent must run on the machine with the app. See Which operating system does the agent need?

Can one project test several applications?Customers

Yes. Add each one under Applications in Desktop Configuration; names are unique in the project. Each test case picks one, an empty choice means the default, and a pipeline can override it. See Which application a test opens.

Why does the Desktop Recorder say “No agent is online”?Customers

The recorder needs an online agent on the Windows or macOS computer with the app. Start the SmartestQA client there and wait for the green dot; an agent is Online when it sent a heartbeat in the last 90 seconds. See the fix.

Which macOS permissions does it need?Customers

Three, under System Settings › Privacy & Security. Accessibility for Xcode Helper and the app that runs the agent, for test runs and the recorder. Screen Recording for screenshots of recorded steps; without it the Desktop Recorder records the steps without screenshots. Input Monitoring for capturing your clicks and key presses. See Mac for desktop tests.

Why does a Windows desktop test stop with “session terminated / driver unreachable”?Customers

Developer Mode is off. Without it, WinAppDriver crashes in the middle of a session. Turn it on under Settings › Privacy & Security › For developers and restart if Windows asks. See the fix.

What do I do when typing into a password field does nothing?Customers

Use the step type Type Key by Key. It types with the real keyboard, one key at a time, and is meant for password fields and fields that reject pasted or bulk input. See the fix.

Are desktop tests repaired when the app’s UI changes?Customers

Desktop locators can be auto-healed when the project’s AI is on. Desktop projects get AI repairs only, and you decide each one yourself in Maintenance; desktop repairs never confirm themselves. See Project types and engines.

Read more#

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai