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.
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
- Prepare the machine: Node.js, Appium and the driver, then start the agent with its API key.
- Open Desktop Configuration, set Platform and click Save Configuration.
- Click Add application and fill the name and the app identifier or path.
- Click Desktop Recorder, click the controls in the app and save.
- 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.
- 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 --installedshowswindows, and after the agent starts its dot turns green. - 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”. - 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.
- 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. - 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#
| Question | Testing by hand | Hand-written scripts | SmartestQA |
|---|---|---|---|
| Which applications can be tested? | Any app you can open | What your driver supports | Windows apps (Store / UWP, Win32, WPF, WinForms) and macOS apps, in a DESKTOP project |
| Who can create a test? | Any tester | Someone who writes code | You 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 PC | On the machine with the app, where you installed the driver and a runner | On an agent on the machine with the app. Desktop tests do not run on the SmartestQA server |
| Can it run without a person? | No | Yes, when you build a scheduled job around the scripts | Yes: a pipeline with Run on Your Agent and at least one online agent |
| What happens when the UI changes? | The tester adapts on the spot | Someone updates the locators in the code | Desktop locators can be auto-healed when the project’s AI is on; each repair waits for your decision in Maintenance |
Steps#
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.
Verify the driver and connect the agent
Run
appium driver list --installedin a second terminal. Then start the agent with its API key (Download Client).windowsormac2is in the list of installed drivers, and the agent’s dot turns green. The machine is ready for desktop runs and the Desktop Recorder.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”.
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.
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.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.
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 clickedorKey "Ctrl+S" was pressed.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#
| Windows | macOS | |
|---|---|---|
| Platform in Desktop Configuration | Windows (WinAppDriver), the default | macOS (Mac2Driver) |
| Setup guide | The Local Desktop Setup tab, titled Local Desktop (Windows) Setup | Mac for desktop tests; you need an administrator account on the Mac |
| What is installed | Node.js, Appium, the Windows driver, WinAppDriver; Developer Mode on | Xcode 13 or newer, Node.js, Appium, the Mac2 driver |
| Installed driver shown as | windows | mac2 |
| App identifier | AUMID / App ID for Store / UWP apps | Bundle ID, for example com.example.MyApp |
| App path | App Path (.exe) for classic Win32, WPF and WinForms apps | App Path (.app), for example /Applications/MyApp.app; the runner reads the bundle ID from the app when you give only the path |
| System permissions | Administrator approval once, for WinAppDriver | Accessibility, Screen Recording and Input Monitoring under Privacy & Security |
| Attach to a running window | An option for WebView2 and PWA apps, with Window Title (attach) | Not offered; the dialog hides it for macOS |
| Agent download | SmartTest-Desktop-Windows-latest.zip | SmartTest-Desktop-macOS-latest.zip |
Desktop step types#
| Group | Step types |
|---|---|
| Mouse | Click, Double Click, Right Click, Hover |
| Input and keys | Type Text, Clear, Clear & Type, Type Key by Key, Press Key (Enter, Tab, Esc, Ctrl+S, Alt+F4), Select |
| Scrolling and waits | Scroll, Scroll To Element, Wait For Element, Wait For Visible, Wait |
| Assertions | Assert Visible, Assert Not Visible, Assert Exists, Assert Not Exists, Assert Enabled, Assert Checked, Assert Text |
| Read values | Get Text, Get Attribute, Store Variable |
| App and window | Launch 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#
- Windows machine for desktop tests: the setup guide, step by step.
- Mac for desktop tests: Xcode, the Mac2 driver and the permissions.
- Desktop Configuration: platform, Appium Server URL and the applications list.
- Discover › Desktop: the Desktop Recorder.
- Desktop steps: every step type and the Global desktop actions.
- Test Agents: install the client, the API key, shared agents.
- What happens to my tests when the UI changes?: how repairs are made and reviewed.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai