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

# Core API

## Module Functions

### `app()`

Connect to a running application. Exactly one of `name`, `bundle_id`, or `pid` must be provided.

```python
import axterminator as ax

# By name
app = ax.app(name="Calculator")

# By bundle ID (recommended -- locale-independent)
app = ax.app(bundle_id="com.apple.Safari")

# By PID
app = ax.app(pid=12345)
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `name` | `str` | Application name (e.g., `"Safari"`) |
| `bundle_id` | `str` | Bundle identifier (e.g., `"com.apple.Safari"`) |
| `pid` | `int` | Process ID |

**Returns:** `AXApp` instance

**Raises:** `ValueError` if no selector provided; `RuntimeError` if app not found or not accessible

---

### `is_accessibility_enabled()`

Check if accessibility permissions are granted.

```python
if ax.is_accessibility_enabled():
    print("Ready!")
```

**Returns:** `bool`

---

### `configure_healing()`

Install a `HealingConfig` as the global healing configuration. Call once at startup.

```python
config = ax.HealingConfig(
    strategies=["data_testid", "title", "visual_vlm"],
    max_heal_time_ms=200,
)
ax.configure_healing(config)
```

---

### `configure_vlm()`

Configure the VLM (Vision Language Model) backend for visual element detection.

```python
ax.configure_vlm(
    backend="mlx",       # or "anthropic", "openai", "gemini", "ollama"
    api_key="...",       # Required for cloud backends
    model="...",         # Optional model override
    verbose=False        # Enable debug logging
)
```

**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `backend` | `str` | Backend name (`"mlx"`, `"anthropic"`, `"openai"`, `"gemini"`, `"ollama"`) |
| `api_key` | `str` | API key (cloud backends only) |
| `model` | `str` | Model name override |
| `verbose` | `bool` | Enable verbose logging |

---

## Classes

### `HealingConfig`

Configuration for self-healing locators.

```python
config = ax.HealingConfig(
    strategies=["data_testid", "aria_label", "title"],
    max_heal_time_ms=200,
    cache_healed=True,
)
```

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `strategies` | `list[str] \| None` | All 7 strategies | Ordered list of strategy names |
| `max_heal_time_ms` | `int` | `100` | Maximum time budget for healing (ms) |
| `cache_healed` | `bool` | `True` | Cache successful heals |

Valid strategy names: `"data_testid"`, `"aria_label"`, `"identifier"`, `"title"`, `"xpath"`, `"position"`, `"visual_vlm"`.

---

### `ActionMode`

Controls whether an action steals focus.

```python
ax.ActionMode.Background  # Default - no focus stealing
ax.ActionMode.Focus       # Brings app to foreground

# Convenience constants
ax.BACKGROUND
ax.FOCUS
```