---
title: "How do I test a Windows or macOS desktop application?"
section: "Use cases"
description: "Test Windows and macOS desktop apps in SmartestQA: prepare the machine with the agent and Appium, add the application in Desktop Configuration, record with the Desktop Recorder, and run on your agent."
url: https://docs.smartestqa.ai/en/use-case-desktop-app.html
audience: [customer, admin]
updated: 2026-11-12
keywords: "desktop application testing windows app test automation macos app testing winappdriver mac2 driver appium desktop recorder wpf winforms win32 uwp aumid bundle id webview2 pwa desktop project run on agent thick client erp client automate desktop client regression manual desktop testing alternative thick client test automation without scripts"
---
# Use cases: 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**

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**](https://docs.smartestqa.ai/en/project-settings-desktop.html), record its controls with the [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop), 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**](https://docs.smartestqa.ai/en/schedule-where.html#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**](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) 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**](https://docs.smartestqa.ai/en/project-settings-desktop.html) the tester keeps the **Platform** Windows (WinAppDriver) and clicks **Save Configuration**: “Desktop configuration saved”. Then [**Add application**](https://docs.smartestqa.ai/en/agent-pool-app-library.html#upload), the **Name** `Claims Client`, the App Path (.exe) and **Save**: “Application added”.
3. The tester clicks [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop) 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**](https://docs.smartestqa.ai/en/schedule-where.html#run-environment) is [**Run on Your Agent**](https://docs.smartestqa.ai/en/schedule-where.html#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**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop) 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**](https://docs.smartestqa.ai/en/schedule-where.html#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

1. **Prepare the machine with the app**

   **Windows:** in a DESKTOP project open **Device Farm** › [**Test Agents**](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list) and follow the [**Local Desktop Setup**](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) 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](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop): 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](https://docs.smartestqa.ai/en/agent-pool-agents.html#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**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).
3. **Set the platform**

   Open [**Desktop Configuration**](https://docs.smartestqa.ai/en/project-settings-desktop.html) 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](https://docs.smartestqa.ai/en/project-settings-desktop.html#general).

   “Desktop configuration saved”.
4. **Add the application**

   Under Applications click [**Add application**](https://docs.smartestqa.ai/en/agent-pool-app-library.html#upload). 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](https://docs.smartestqa.ai/en/project-settings-desktop.html#applications).

   “Application added”. The first application of a project becomes the default.
5. **Record the app**

   In the DESKTOP project click [**Desktop Recorder**](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop). Fill [**Target Application**](https://docs.smartestqa.ai/en/automate-editor.html#test-case-detail), **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](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop).
6. **Complete the test case**

   The Desktop Recorder adds the captured controls as steps. Saved desktop actions are also in the [Action List](https://docs.smartestqa.ai/en/automate-add-steps.html#action-list). [**Global**](https://docs.smartestqa.ai/en/automate-steps-mobile.html#global-actions) opens [**Global Desktop Actions**](https://docs.smartestqa.ai/en/automate-steps-desktop.html#global-desktop) with steps that need no element, such as Press Enter, Save (Ctrl+S), Launch App and Take Screenshot; click [**Add to step list**](https://docs.smartestqa.ai/en/automate-steps-mobile.html#global-actions). See [Desktop steps](https://docs.smartestqa.ai/en/automate-steps-desktop.html).
7. **Try it with a Dry Run**

   Start a [Dry Run](https://docs.smartestqa.ai/en/automate-dry-run.html#desktop-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**](https://docs.smartestqa.ai/en/schedule-where.html#run-environment) of a desktop pipeline is [**Run on Your Agent**](https://docs.smartestqa.ai/en/schedule-where.html#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](https://docs.smartestqa.ai/en/schedule-where.html#desktop).

## Windows and macOS side by side

|  | Windows | macOS |
| --- | --- | --- |
| Platform in Desktop Configuration | Windows (WinAppDriver), the default | macOS (Mac2Driver) |
| Setup guide | The [**Local Desktop Setup**](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) tab, titled [**Local Desktop (Windows) Setup**](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) | [Mac for desktop tests](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop); 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)**](https://docs.smartestqa.ai/en/project-settings-desktop.html#applications) | 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](https://docs.smartestqa.ai/en/project-settings-test-management.html#test-settings) 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

### Q: Can desktop tests run on the SmartestQA server?

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**](https://docs.smartestqa.ai/en/schedule-where.html#agent) when you open it; save to keep it. See [Desktop projects](https://docs.smartestqa.ai/en/schedule-where.html#desktop).

_Audience: customer, admin_

### Q: Does SmartestQA test macOS apps, or only Windows?

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**](https://docs.smartestqa.ai/en/project-settings-desktop.html). See [Mac for desktop tests](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop).

_Audience: customer, admin_

### Q: Which kinds of Windows application can I test?

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](https://docs.smartestqa.ai/en/project-settings-desktop.html#applications).

_Audience: customer, admin_

### Q: Can a Windows agent test a macOS app, or the other way round?

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?](https://docs.smartestqa.ai/en/agent-pool-faq.html#faq-which-os)

_Audience: customer, admin_

### Q: Can one project test several applications?

Yes. Add each one under Applications in [**Desktop Configuration**](https://docs.smartestqa.ai/en/project-settings-desktop.html); 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](https://docs.smartestqa.ai/en/project-settings-desktop.html#app-choice).

_Audience: customer, admin_

### Q: Why does the Desktop Recorder say “No agent is online”?

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](https://docs.smartestqa.ai/en/discover-troubleshooting.html#fix-desktop-agent).

_Audience: customer, admin_

### Q: Which macOS permissions does it need?

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](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop).

_Audience: customer, admin_

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

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](https://docs.smartestqa.ai/en/agent-pool-troubleshooting.html#fix-session-terminated).

_Audience: customer, admin_

### Q: What do I do when typing into a password field does nothing?

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](https://docs.smartestqa.ai/en/automate-steps-troubleshooting.html#fix-desktop-password).

_Audience: customer, admin_

### Q: Are desktop tests repaired when the app’s UI changes?

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](https://docs.smartestqa.ai/en/maintenance-how-healing-works.html#project-types).

_Audience: customer, admin_

## Read more

- [Windows machine for desktop tests](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop): the setup guide, step by step.
- [Mac for desktop tests](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop): Xcode, the Mac2 driver and the permissions.
- [Desktop Configuration](https://docs.smartestqa.ai/en/project-settings-desktop.html): platform, Appium Server URL and the applications list.
- [Discover › Desktop](https://docs.smartestqa.ai/en/discover-mobile-desktop.html#desktop): the Desktop Recorder.
- [Desktop steps](https://docs.smartestqa.ai/en/automate-steps-desktop.html): every step type and the Global desktop actions.
- [Test Agents](https://docs.smartestqa.ai/en/agent-pool-agents.html): install the client, the API key, shared agents.
- [What happens to my tests when the UI changes?](https://docs.smartestqa.ai/en/use-case-self-healing.html): how repairs are made and reviewed.
