axterminator 0.10.1

macOS GUI testing framework with background testing, sub-millisecond element access, and self-healing locators
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# Finding Elements

AXTerminator provides multiple ways to locate UI elements, with automatic fallback through self-healing locators.

## Basic Finding

```bash
# Find by text -- searches title, description, value, label, and identifier
axterminator find "5" --app Calculator

# Find with timeout (milliseconds)
axterminator find "Save" --app Safari --timeout 5000
```

Or via MCP tool call:

```
ax_find query="5" app="Calculator"
ax_find query="Save" app="Safari" timeout_ms=5000
```

## Query Syntax

Use prefixes to specify search type:

```bash
# Simple text -- matches ANY of: title, description, value, label, identifier
axterminator find "Save" --app Safari

# By identifier
axterminator find "identifier:_NS:9" --app Safari

# By role
axterminator find "role:AXButton" --app Safari

# By title
axterminator find "title:Save" --app Safari

# By description (useful for apps like Calculator where buttons use AXDescription)
axterminator find "description:equals" --app Calculator

# By value
axterminator find "value:42" --app Calculator

# By label
axterminator find "label:Save button" --app Safari

# Combined (AND semantics -- all specified fields must match)
axterminator find "role:AXButton title:OK" --app Safari
```

> **Note:** Simple text queries (without a prefix) search across ALL text-bearing attributes using OR semantics. Prefixed queries use AND semantics -- every specified field must match.

## Finding Multiple Elements

```bash
# Find all buttons
axterminator find "role:AXButton" --app Safari --all
```

Or via MCP:

```
ax_find query="role:AXButton" app="Safari" multiple=true
```

## Element Properties

Inspect all attributes of a found element:

```bash
axterminator tree --app Safari
```

Or via MCP:

```
ax_get_attributes app="Safari" query="Save"
ax_get_tree app="Safari"
```

Attributes returned include: title, role, value, identifier, enabled, focused, and more.

## Hierarchical Navigation

Use the tree command to see the full element hierarchy:

```bash
# Full element hierarchy
axterminator tree --app Finder

# Inspect specific element attributes
axterminator find "role:AXToolbar" --app Finder
```

Or via MCP:

```
ax_get_tree app="Finder"
ax_find query="role:AXToolbar" app="Finder"
```

## Waiting for Elements

Use the timeout parameter to wait for elements to appear:

```bash
axterminator find "Done" --app Safari --timeout 5000
```

Or via MCP:

```
ax_find query="Done" app="Safari" timeout_ms=5000
ax_wait_idle app="Safari" timeout_ms=3000
```

## Error Handling

If an element is not found within the timeout, AXTerminator returns an error. Use `axterminator tree` or `ax_get_tree` to inspect the current element hierarchy and adjust your query.

Common issues:

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Element not found` for short labels | App uses `AXDescription` not `AXTitle` | Try `description:label` or inspect with `axterminator tree` |
| No results for role query | Wrong role name | Check `axterminator tree` output for actual role names |
| Timeout finding element | Element not yet rendered | Increase `--timeout` value |