IOSManager

iOS Simulator and Safari automation via Appium with 1:1 command parity to BrowserManager

IOSManager

The IOSManager class provides iOS Safari automation via Appium with full feature parity to BrowserManager. It supports both iOS Simulators and real devices.

Prerequisites

# Install Appium and XCUITest driver
npm install -g appium
appium driver install xcuitest

Constructor

import { IOSManager } from '@agentic-labs/browser';

const ios = new IOSManager();

Device Management

listDevices()

List available iOS simulators.

const devices = await ios.listDevices();
console.log(devices);
// [{ name: 'iPhone 15 Pro', udid: '...', state: 'Booted', runtime: 'iOS 17.0', isAvailable: true }]

return · IOSDeviceInfo[]

name · string

Device name

udid · string

Device UDID

state · string

Device state (Booted, Shutdown, etc.)

runtime · string

iOS runtime version

isAvailable · boolean

Whether device is available

isRealDevice · boolean

True if physical device

listRealDevices()

List connected real iOS devices.

const realDevices = await ios.listRealDevices();

return · IOSDeviceInfo[]

Array of connected physical iOS devices

listAllDevices()

List all devices (simulators + real devices).

const allDevices = await ios.listAllDevices();

return · IOSDeviceInfo[]

Array of all available iOS devices (real devices first, then simulators)

Launch & Connection

launch()

Launch iOS Safari via Appium. Automatically boots simulator if needed and starts Appium server.

// Launch on default device (latest iPhone Pro)
await ios.launch();

// Launch on specific device
await ios.launch({ device: 'iPhone 15 Pro' });

// Launch on specific UDID
await ios.launch({ udid: '12345678-1234-1234-1234-123456789012' });

options · object

device · string

Device name or partial name match

udid · string

Exact device UDID

headless · boolean

Ignored for iOS (simulators are always visible)

Environment Variables:

• AGENT_BROWSER_IOS_DEVICE - Default device name
• AGENT_BROWSER_IOS_UDID - Default device UDID

isLaunched()

Check if browser is launched.

const launched = ios.isLaunched();

return · boolean

True if browser is launched

close()

Close browser and cleanup resources.

await ios.close();

Navigation

navigate()

Navigate to a URL.

const result = await ios.navigate('https://example.com');
console.log(result.url, result.title);

url · string

URL to navigate to

return · { url: string; title: string }

Current URL and page title after navigation

getUrl()

Get current page URL.

const url = await ios.getUrl();

return · string

Current page URL

getTitle()

Get page title.

const title = await ios.getTitle();

return · string

Page title

goBack()

Navigate back.

await ios.goBack();

goForward()

Navigate forward.

await ios.goForward();

reload()

Reload the page.

await ios.reload();

Element Interaction

click()

Click/tap an element.

await ios.click('#submit');
await ios.click('@e5'); // by ref

selector · string

CSS selector or element ref

tap()

Alias for click() with semantic clarity for touch.

await ios.tap('#button');

selector · string

CSS selector or element ref

type()

Type text into an element.

await ios.type('#search', 'query', { delay: 100, clear: true });

selector · string

CSS selector or element ref

text · string

Text to type

options · object

delay · number

Delay between keystrokes in ms

clear · boolean

Clear field before typing

fill()

Clear and fill an input field.

await ios.fill('#email', '[e-mail]');

selector · string

CSS selector or element ref

value · string

Value to set

check()

Check a checkbox.

await ios.check('#terms');

selector · string

CSS selector or element ref

uncheck()

Uncheck a checkbox.

await ios.uncheck('#newsletter');

selector · string

CSS selector or element ref

select()

Select option(s) from dropdown.

await ios.select('#country', 'US');
await ios.select('#tags', ['tag1', 'tag2']);

selector · string

CSS selector or element ref

values · string | string[]

Value(s) to select

clear()

Clear an input field.

await ios.clear('#search');

selector · string

CSS selector or element ref

focus()

Focus an element.

await ios.focus('#username');

selector · string

CSS selector or element ref

hover()

Hover over element (scrolls into view on iOS).

await ios.hover('#menu-item');

selector · string

CSS selector or element ref

Keyboard

press()

Press a key.

await ios.press('Enter');
await ios.press('Tab');
await ios.press('Escape');

key · string

Key name (Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight)

Scrolling & Gestures

scroll()

Scroll the page or an element.

// Scroll by direction
await ios.scroll({ direction: 'down', amount: 300 });

// Scroll by coordinates
await ios.scroll({ x: 0, y: 500 });

// Scroll element into view
await ios.scroll({ selector: '#footer' });

options · object

selector · string

Element to scroll into view

x · number

Horizontal scroll offset

y · number

Vertical scroll offset

direction · 'up' | 'down' | 'left' | 'right'

Scroll direction

amount · number

Scroll distance in pixels (default: 300)

swipe()

iOS-specific swipe gesture.

await ios.swipe('up', { distance: 400 });
await ios.swipe('left');

direction · 'up' | 'down' | 'left' | 'right'

Swipe direction

options · object

distance · number

Swipe distance in pixels (default: 300)

Snapshots & Element Refs

getSnapshot()

Get page snapshot with element refs.

const snapshot = await ios.getSnapshot({ interactive: true });
console.log(snapshot.tree);
console.log(snapshot.refs);

options · object

interactive · boolean

Only include interactive elements

return · IOSEnhancedSnapshot

tree · string

Accessibility tree as formatted text

refs · IOSRefMap

Element refs with selector and metadata

getRefMap()

Get cached ref map from last snapshot.

const refs = ios.getRefMap();

return · IOSRefMap

Map of refs to element data

Element Queries

getText()

Get element text content.

const text = await ios.getText('#heading');

selector · string

CSS selector or element ref

return · string

Element text content

getAttribute()

Get element attribute value.

const href = await ios.getAttribute('a', 'href');

selector · string

CSS selector or element ref

attribute · string

Attribute name

return · string | null

Attribute value or null

getContent()

Get page or element HTML content.

const html = await ios.getContent();
const elementHtml = await ios.getContent('#container');

selector · string

Optional CSS selector or element ref

return · string

HTML content

isVisible()

Check if element is visible.

const visible = await ios.isVisible('#modal');

selector · string

CSS selector or element ref

return · boolean

True if element is visible

isEnabled()

Check if element is enabled.

const enabled = await ios.isEnabled('#submit');

selector · string

CSS selector or element ref

return · boolean

True if element is enabled

count()

Get count of matching elements.

const count = await ios.count('.item');

selector · string

CSS selector

return · number

Number of matching elements

getBoundingBox()

Get element bounding box.

const box = await ios.getBoundingBox('#element');
console.log(box.x, box.y, box.width, box.height);

selector · string

CSS selector or element ref

return · { x: number; y: number; width: number; height: number } | null

Bounding box or null if element not found

Screenshots

screenshot()

Take a screenshot.

// Save to file
await ios.screenshot({ path: './screen.png' });

// Get base64
const result = await ios.screenshot();
console.log(result.base64);

options · object

path · string

Output file path

fullPage · boolean

Capture full page (iOS limitation: may not work)

return · { path?: string; base64?: string }

Screenshot result with path or base64 data

JavaScript Execution

evaluate()

Execute JavaScript in page context.

const title = await ios.evaluate<string>('document.title');

const result = await ios.evaluate<number>(
  'return arguments[0] + arguments[1]',
  5,
  10
);

script · string

JavaScript code to execute

args · unknown[]

Arguments to pass to the script

return · T

Script execution result

Wait Functions

wait()

Wait for element or timeout.

// Wait for element to be attached
await ios.wait({ selector: '#content', timeout: 10000 });

// Wait for element to be visible
await ios.wait({ selector: '#modal', state: 'visible' });

// Wait for element to be detached
await ios.wait({ selector: '.loader', state: 'detached' });

// Just wait (timeout)
await ios.wait({ timeout: 2000 });

options · object

selector · string

CSS selector or element ref

timeout · number

Timeout in milliseconds (default: 30000)

state · 'attached' | 'detached' | 'visible' | 'hidden'

Element state to wait for (default: ‘attached’)

Device Info

getDeviceInfo()

Get current device information.

const info = ios.getDeviceInfo();
if (info) {
  console.log(info.name, info.udid);
}

return · { name: string; udid: string } | null

Device info or null if not launched

TypeScript Types

import type {
  IOSManager,
  IOSDeviceInfo,
  IOSEnhancedSnapshot,
  IOSRefMap
} from '@agentic-labs/browser';