Wiki › Project

mac-ui-tester

Project · tool · 2026

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.

CommandWhat 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
treePrints 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.

See also

In the knowledge graph

mac-ui-tester and the 7 things it is linked to. Open any dot for its page, or explore it in the full graph.

StarHubTH · work · RelatedStarHubTHPython · skill · Built withPythonSwift · skill · mentionsSwiftSwiftUI · skill · Built withSwiftUIAI agent skills · theme · ThemesAI agent skillsOpen source on GitHub · person, role or place · ContextOpen sourcemacOS · service or platform · Runs onmacOS mac-ui-test…
7 linked in the graph: 1 work3 skills1 theme1 person, role or place1 service or platform
When
2023202420252026
Jul 2026 · 2 commits

As data

Everything on this page is read from triples in the knowledge graph. These are the 19 it states about mac-ui-tester, and 2 more its ontology implies; the console runs SPARQL over the whole graph, here in your browser.

Download
@prefix id: <https://ask.chaipat.cc/id/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix cj: <https://ask.chaipat.cc/ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

id:MacUITester
    a cj:Project ;
    rdfs:label "mac-ui-tester" ;
    cj:description "Hands-on UI testing for real macOS apps: launch, look, click, type and screenshot from a terminal or an AI agent." ;
    cj:context id:OpenSource ;
    cj:repository "https://github.com/AppleBoiy/mac-ui-tester"^^xsd:anyURI ;
    cj:firstCommit "2026-07-25"^^xsd:date ;
    cj:lastCommit "2026-07-25"^^xsd:date ;
    cj:commitCount 2 ;
    cj:kind "tool" ;
    cj:theme id:ThemeAgentSkills ;
    cj:uses id:Python , id:SwiftUI ;
    cj:tier 2 ;
    cj:runsOn id:macOS ;
    cj:relatedTo id:StarHubTH ;
    cj:mentions id:Swift ;
    cj:article "https://ask.chaipat.cc/wiki/MacUITester"^^xsd:anyURI ;
    cj:activeIn id:Y2026 ;
    cj:activity _:b97 .
Works 1
StarHubTH