mac-ui-tester
mac-ui-tester is a single-file Python tool for hands-on testing of real macOS apps. From a terminal, or from an AI agent driving one, it builds an app, launches it, reads what is on screen, clicks and types into it, and takes screenshots. It isn't a replacement for unit tests. It exercises the interface the way a person would.
How it works
It needs no Xcode test target and no dependencies, only two tools built into macOS: osascript (AppleScript and System Events) and screencapture. The terminal running it needs Accessibility permission, and check confirms it has it.
| Command | What it does |
|---|---|
build <dir> | Finds an Xcode project or a build script and runs it |
launch <dir or .app> | Opens the newest .app under a folder, or a given app |
tree | Prints the accessibility tree: what is actually on screen |
click <id or label> | Clicks an element by its accessibility identifier or visible label |
type <text> | Types into the focused field |
screenshot <file> | Captures the app's window or the whole screen |
quit <app> | Closes the app cleanly |
Why accessibility identifiers
Visible labels change with localisation and copy edits, so a test that clicks "Install Mod" breaks as soon as the app is shown in Thai. Setting a stable .accessibilityIdentifier on SwiftUI views gives click a target that survives both. This matters for a bilingual app like StarHubTH, which this tool was written alongside.