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();

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', 'user@example.com');

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

number

Horizontal scroll offset

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

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';

Node.js API

CLI Reference

​IOSManager

​Prerequisites

​Constructor

​Device Management

​listDevices()

​listRealDevices()

​listAllDevices()

​Launch & Connection

​launch()

​isLaunched()

​close()

​Navigation

​navigate()

​getUrl()

​getTitle()

​goBack()

​goForward()

​reload()

​Element Interaction

​click()

​tap()

​type()

​fill()

​check()

​uncheck()

​select()

​clear()

​focus()

​hover()

​Keyboard

​press()

​Scrolling & Gestures

​scroll()

​swipe()

​Snapshots & Element Refs

​getSnapshot()

​getRefMap()

​Element Queries

​getText()

​getAttribute()

​getContent()

​isVisible()

​isEnabled()

​count()

​getBoundingBox()

​Screenshots

​screenshot()

​JavaScript Execution

​evaluate()

​Wait Functions

​wait()

​Device Info

​getDeviceInfo()

​TypeScript Types

Build docs developers (and LLMs) love

IOSManager

Prerequisites

Constructor

Device Management

listDevices()

listRealDevices()

listAllDevices()

Launch & Connection

launch()

isLaunched()

close()

Navigation

navigate()

getUrl()

getTitle()

goBack()

goForward()

reload()

Element Interaction

click()

tap()

type()

fill()

check()

uncheck()

select()

clear()

focus()

hover()

Keyboard

press()

Scrolling & Gestures

scroll()

swipe()

Snapshots & Element Refs

getSnapshot()

getRefMap()

Element Queries

getText()

getAttribute()

getContent()

isVisible()

isEnabled()

count()

getBoundingBox()

Screenshots

screenshot()

JavaScript Execution

evaluate()

Wait Functions

wait()

Device Info

getDeviceInfo()

TypeScript Types