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
129
130
131
132
133
134
135
136

# Configuration

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AXTERMINATOR_VLM_BACKEND` | VLM backend | None |
| `AXTERMINATOR_VLM_API_KEY` | VLM API key | None |
| `AXTERMINATOR_TIMEOUT_MS` | Default timeout | 5000 |
| `AXTERMINATOR_LOG_LEVEL` | Log level | INFO |
| `AXTERMINATOR_PRIORITY_MODE` | Visual lookup source-priority mode: `legacy` or `explicit` | `legacy` |

## HealingConfig

```python
import axterminator as ax

config = ax.HealingConfig(
    strategies=[
        "data_testid",  # Developer-set IDs (most stable)
        "aria_label",   # Accessibility labels
        "identifier",   # AX identifier
        "title",        # Element title
        "xpath",        # Structural path
        "position",     # Screen position
        "visual_vlm",   # AI vision (slowest)
    ],
    max_heal_time_ms=100,  # Total time budget for healing (ms), default: 100
)
```

### Strategy Details

| Strategy | Stability | Speed | Notes |
|----------|-----------|-------|-------|
| `data_testid` | Highest | Fast | Set by developers |
| `aria_label` | High | Fast | Accessibility-focused |
| `identifier` | High | Fast | System-assigned |
| `title` | Medium | Fast | May change with i18n |
| `xpath` | Low | Medium | Breaks on structure changes |
| `position` | Lowest | Fast | Breaks on layout changes |
| `visual_vlm` | High | Slow | Requires VLM backend |

## VLM Configuration

### MLX (Local, Recommended)

```python
ax.configure_vlm(backend="mlx")
```

No API key needed. Uses Apple Silicon GPU.

### Ollama (Local)

```python
ax.configure_vlm(
    backend="ollama",
    model="llava"  # or "bakllava", "llava:13b"
)
```

Requires Ollama running locally.

### Anthropic (Cloud)

```python
ax.configure_vlm(
    backend="anthropic",
    api_key="sk-ant-..."
)
```

### OpenAI (Cloud)

```python
ax.configure_vlm(
    backend="openai",
    api_key="sk-..."
)
```

### Gemini (Cloud)

```python
ax.configure_vlm(
    backend="gemini",
    api_key="..."
)
```

## Logging

```python
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Or via environment
# AXTERMINATOR_LOG_LEVEL=DEBUG
```

## pytest Integration

```python
# conftest.py
import pytest

@pytest.fixture
def ax_app():
    """Fixture to get app connections."""
    import axterminator as ax

    def _get_app(name):
        return ax.app(name=name)

    return _get_app

@pytest.fixture
def ax_wait():
    """Fixture for waiting."""
    import time
    return time.sleep
```

### Custom Markers

```python
# pytest.ini
[pytest]
markers =
    integration: Integration tests (require --run-integration)
    slow: Slow tests
    requires_app: Requires specific app running
```