What Are "Atomic Capabilities"?
An atomic capability is the smallest indivisible operation unit—like atomic operations in programming: either fully completes or fully fails, never enters a half-finished state.
In iDeviceFarm, atomic capabilities are invoked directly by the Agent client on each phone. The farm controller only dispatches commands and collects results. This separation provides decoupling: regardless of what model or strategy sits above, bottom-line execution remains consistent and verifiable.
Capability Breakdown
| Capability | What It Does | Success Receipt |
|---|---|---|
| launch_app | Launch a specified app | Target app is in foreground |
| tap | Tap a coordinate or UI selector | Tap sent; optional UI change confirmation |
| swipe | Swipe gesture (up/down/left/right) | Gesture completed |
| input | Enter text into a target field | Field text matches expectation or is readable |
| wait_ui | Wait for text or element to appear | Explicit failure if timeout reached |
| album_import / pick_media | Import/select a media file | Resource selectable on publish page |
| screenshot (optional) | Capture current screen | Only enabled during debugging; disabled by default, never persisted |
Core Design Principles
- Every call gets a receipt: not "I sent a tap" but "I sent a tap and the screen navigated to the next page";
- Timeouts & error codes: wait_ui returns an explicit timeout error after N seconds instead of hanging forever;
- Idempotency: sending the same tap twice has the same effect as once—no double-triggered side effects;
- No side effects: atomic operations only affect the targeted app state (never clear cache, never modify config).
Atomic Actions vs. Record-and-Playback Scripts
Many people confuse atomic capabilities with "record and playback." The difference is significant:
| Dimension | Record & Playback | Atomic Actions + AI |
|---|---|---|
| Stability | Breaks on app redesign | Reads actual screen content; resistant to updates |
| Flexibility | Can only replay recorded flow | AI dynamically composes from intent |
| Error handling | Restart from beginning on failure | Pinpoint failing step, retry just that step |
| Use case | Fixed-flow testing | Variable-length flows (user freely describes tasks) |
Bottom line: atomic capabilities are the foundation of the entire system. Solid foundations mean elaborate upper designs don't collapse. Curious how atoms chain into workflows? Read our capabilities deep dive.