argent-ios-device-interact
software-mansion/argent
Control a physical iPhone through argent for automated testing and interaction.
What is argent-ios-device-interact?
Drive a physical iPhone connected via cable using argent's device automation tools. Use this skill only when testing against a real device (not a simulator); it provides gesture control, app launching, and UI inspection tailored to hardware constraints.
- Launch, restart, and reinstall apps on a physical iPhone
- Perform gestures (tap, swipe, custom) and button presses (home, volume, action button)
- Describe screen state and take screenshots without changing the UI
- Type text via keyboard and await UI elements or screen idle states
- Run automation sequences while respecting hardware limitations and re-fronting behavior
How to install argent-ios-device-interact
npx skills add https://github.com/software-mansion/argent --skill argent-ios-device-interact- Physical iPhone connected via USB cable
- Trust established between the iPhone and the host machine
- Proper code signing configured for the app under test
- argent tool-server running and detecting the device
How to use argent-ios-device-interact
- 1.Verify the device appears in list-devices with kind 'device' (not simulator)
- 2.Launch the target app using launch-app with the correct bundleId
- 3.Use describe or screenshot to inspect the current screen state
- 4.Perform interactions: gesture-tap, gesture-swipe, button presses, or keyboard input
- 5.After gestures or keyboard, re-describe to see the updated UI state
- 6.Use await-ui-element or await-screen-idle to synchronize with app changes
- 7.Repeat steps 3–6 for your test scenario; use run-sequence to chain multiple steps
Use cases
- Automated testing of iOS apps on real devices to catch hardware-specific bugs
- End-to-end testing workflows that require physical device interaction (camera, sensors, buttons)
- Validating app behavior across different iPhone models with their specific hardware buttons
- Testing gesture-based navigation and custom touch interactions on actual hardware
- Debugging app state by inspecting the live screen and taking diffs between states
- iOS QA engineers and testers
- Mobile app developers validating on physical devices
- Automation engineers building device-farm test suites
- Teams requiring hardware-specific testing beyond simulator capabilities
argent-ios-device-interact FAQ
Use this skill only for physical iPhones (kind 'device' in list-devices). Use argent-device-interact for simulators and all other platforms.
The first describe within a second of button home may still show the previous screen; call describe again to get the current state.
Read the argent-ios-device-setup skill; this skill assumes those prerequisites are already met.
Supported: gesture-tap, gesture-swipe, gesture-custom (within hardware limits), and buttons (home, volumeUp, volumeDown, actionButton on models that have it). Two-finger gestures, rotate, shake, and paste are not supported.
On physical devices, https URLs open in Safari by default. Pass the bundleId parameter to open-url to launch the link in your app instead.
Full instructions (SKILL.md)
Source of truth, from software-mansion/argent.
name: argent-ios-device-interact description: Drive a physical iPhone through argent. Use when a physical iPhone is involved (a list-devices iOS entry with kind "device") and ONLY then; never for a simulator. For cable, trust, or signing problems read argent-ios-device-setup.
Physical iPhone interaction
Read this only for a physical iPhone. argent-device-interact still applies for everything not listed here.
Contract
- Observation never changes the screen; mutation may.
describeandawait-ui-elementfail on a backgrounded target instead of re-fronting it;await-screen-idlereturnssettled: falsewith no reason. The firstdescribewithin a second ofbutton homecan still return the old tree; describe again. Gestures andkeyboardre-front it and returnreactivated: true; re-describe before the next step. launch-app,open-urlandrestart-appset the app under automation;reinstall-appclears it; a tool-server restart forgets it: launch again.- Each tool's description states its own hardware limits (named keys,
gesture-customshapes, buttons, edge swipes, tap counts). A gated tool fails with a barenot supported on ios device: the fix is in the list below, not in the error.
Tools on hardware
- Only these exist:
list-devices,launch-app,restart-app,reinstall-app,open-url,describe,screenshot,screenshot-diff,gesture-tap,gesture-swipe,gesture-custom,button(home,volumeUp,volumeDown,actionButtonon models that have one),keyboard,await-ui-element,await-screen-idle,run-sequence, the flow tools,stop-simulator-serverandstop-all-simulator-servers(session end). Every other device tool fails withnot supported on ios device. - No two-finger gestures,
rotate,shake,paste,settings-permissions, screen recording,debugger-*,react-profiler-*,native-profiler-*,native-*,boot-device: drive the app's own zoom and rotate UI with taps and drags, move the phone by hand, type withkeyboard, change permissions in the phone's Settings, and debug, profile or record on a simulator. gesture-swipe:durationMssets drag speed, not time;momentum:falseonly rests 300 ms at the end, no damping.open-urlhttps lands in Safari, never in the app that owns the link: passbundleId.
Related skills
More from software-mansion/argent and the wider catalog.
argent-ios-device-setup
Set up a cabled physical iPhone for argent automation testing.
argent-ios-simulator-setup
Set up and boot iOS simulators, verify connection, and obtain UDIDs for simulator interaction tasks.
argent-lens
Propose and compare multiple visual design variants for UI elements with human selection.
argent-metro-debugger
Debug React Native and Chromium apps via Chrome DevTools Protocol with Metro and CDP integration.
argent-native-profiler
Native profiling for iOS and Android: CPU hotspots, UI hangs, memory leaks via xctrace and Perfetto.
argent-qa-flows
Create repeatable QA regression E2E tests as Argent flows from test cases and acceptance criteria.