> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# Install Appium and XCUITest driver
npm install -g appium
appium driver install xcuitest
```

## Constructor

```typescript theme={null}
import { IOSManager } from '@agentic-labs/browser';

const ios = new IOSManager();
```

## Device Management

### listDevices()

List available iOS simulators.

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

<ResponseField name="return" type="IOSDeviceInfo[]">
  <ResponseField name="name" type="string">Device name</ResponseField>
  <ResponseField name="udid" type="string">Device UDID</ResponseField>
  <ResponseField name="state" type="string">Device state (Booted, Shutdown, etc.)</ResponseField>
  <ResponseField name="runtime" type="string">iOS runtime version</ResponseField>
  <ResponseField name="isAvailable" type="boolean">Whether device is available</ResponseField>
  <ResponseField name="isRealDevice" type="boolean">True if physical device</ResponseField>
</ResponseField>

### listRealDevices()

List connected real iOS devices.

```typescript theme={null}
const realDevices = await ios.listRealDevices();
```

<ResponseField name="return" type="IOSDeviceInfo[]">
  Array of connected physical iOS devices
</ResponseField>

### listAllDevices()

List all devices (simulators + real devices).

```typescript theme={null}
const allDevices = await ios.listAllDevices();
```

<ResponseField name="return" type="IOSDeviceInfo[]">
  Array of all available iOS devices (real devices first, then simulators)
</ResponseField>

## Launch & Connection

### launch()

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

```typescript theme={null}
// 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' });
```

<ParamField path="options" type="object">
  <ParamField path="device" type="string">
    Device name or partial name match
  </ParamField>

  <ParamField path="udid" type="string">
    Exact device UDID
  </ParamField>

  <ParamField path="headless" type="boolean">
    Ignored for iOS (simulators are always visible)
  </ParamField>
</ParamField>

**Environment Variables:**

* `AGENT_BROWSER_IOS_DEVICE` - Default device name
* `AGENT_BROWSER_IOS_UDID` - Default device UDID

### isLaunched()

Check if browser is launched.

```typescript theme={null}
const launched = ios.isLaunched();
```

<ResponseField name="return" type="boolean">
  True if browser is launched
</ResponseField>

### close()

Close browser and cleanup resources.

```typescript theme={null}
await ios.close();
```

## Navigation

### navigate()

Navigate to a URL.

```typescript theme={null}
const result = await ios.navigate('https://example.com');
console.log(result.url, result.title);
```

<ParamField path="url" type="string">
  URL to navigate to
</ParamField>

<ResponseField name="return" type="{ url: string; title: string }">
  Current URL and page title after navigation
</ResponseField>

### getUrl()

Get current page URL.

```typescript theme={null}
const url = await ios.getUrl();
```

<ResponseField name="return" type="string">
  Current page URL
</ResponseField>

### getTitle()

Get page title.

```typescript theme={null}
const title = await ios.getTitle();
```

<ResponseField name="return" type="string">
  Page title
</ResponseField>

### goBack()

Navigate back.

```typescript theme={null}
await ios.goBack();
```

### goForward()

Navigate forward.

```typescript theme={null}
await ios.goForward();
```

### reload()

Reload the page.

```typescript theme={null}
await ios.reload();
```

## Element Interaction

### click()

Click/tap an element.

```typescript theme={null}
await ios.click('#submit');
await ios.click('@e5'); // by ref
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### tap()

Alias for click() with semantic clarity for touch.

```typescript theme={null}
await ios.tap('#button');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### type()

Type text into an element.

```typescript theme={null}
await ios.type('#search', 'query', { delay: 100, clear: true });
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ParamField path="text" type="string">
  Text to type
</ParamField>

<ParamField path="options" type="object">
  <ParamField path="delay" type="number">Delay between keystrokes in ms</ParamField>
  <ParamField path="clear" type="boolean">Clear field before typing</ParamField>
</ParamField>

### fill()

Clear and fill an input field.

```typescript theme={null}
await ios.fill('#email', 'user@example.com');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ParamField path="value" type="string">
  Value to set
</ParamField>

### check()

Check a checkbox.

```typescript theme={null}
await ios.check('#terms');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### uncheck()

Uncheck a checkbox.

```typescript theme={null}
await ios.uncheck('#newsletter');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### select()

Select option(s) from dropdown.

```typescript theme={null}
await ios.select('#country', 'US');
await ios.select('#tags', ['tag1', 'tag2']);
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ParamField path="values" type="string | string[]">
  Value(s) to select
</ParamField>

### clear()

Clear an input field.

```typescript theme={null}
await ios.clear('#search');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### focus()

Focus an element.

```typescript theme={null}
await ios.focus('#username');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

### hover()

Hover over element (scrolls into view on iOS).

```typescript theme={null}
await ios.hover('#menu-item');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

## Keyboard

### press()

Press a key.

```typescript theme={null}
await ios.press('Enter');
await ios.press('Tab');
await ios.press('Escape');
```

<ParamField path="key" type="string">
  Key name (Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight)
</ParamField>

## Scrolling & Gestures

### scroll()

Scroll the page or an element.

```typescript theme={null}
// 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' });
```

<ParamField path="options" type="object">
  <ParamField path="selector" type="string">Element to scroll into view</ParamField>
  <ParamField path="x" type="number">Horizontal scroll offset</ParamField>
  <ParamField path="y" type="number">Vertical scroll offset</ParamField>
  <ParamField path="direction" type="'up' | 'down' | 'left' | 'right'">Scroll direction</ParamField>
  <ParamField path="amount" type="number">Scroll distance in pixels (default: 300)</ParamField>
</ParamField>

### swipe()

iOS-specific swipe gesture.

```typescript theme={null}
await ios.swipe('up', { distance: 400 });
await ios.swipe('left');
```

<ParamField path="direction" type="'up' | 'down' | 'left' | 'right'">
  Swipe direction
</ParamField>

<ParamField path="options" type="object">
  <ParamField path="distance" type="number">Swipe distance in pixels (default: 300)</ParamField>
</ParamField>

## Snapshots & Element Refs

### getSnapshot()

Get page snapshot with element refs.

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

<ParamField path="options" type="object">
  <ParamField path="interactive" type="boolean">
    Only include interactive elements
  </ParamField>
</ParamField>

<ResponseField name="return" type="IOSEnhancedSnapshot">
  <ResponseField name="tree" type="string">Accessibility tree as formatted text</ResponseField>
  <ResponseField name="refs" type="IOSRefMap">Element refs with selector and metadata</ResponseField>
</ResponseField>

### getRefMap()

Get cached ref map from last snapshot.

```typescript theme={null}
const refs = ios.getRefMap();
```

<ResponseField name="return" type="IOSRefMap">
  Map of refs to element data
</ResponseField>

## Element Queries

### getText()

Get element text content.

```typescript theme={null}
const text = await ios.getText('#heading');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ResponseField name="return" type="string">
  Element text content
</ResponseField>

### getAttribute()

Get element attribute value.

```typescript theme={null}
const href = await ios.getAttribute('a', 'href');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ParamField path="attribute" type="string">
  Attribute name
</ParamField>

<ResponseField name="return" type="string | null">
  Attribute value or null
</ResponseField>

### getContent()

Get page or element HTML content.

```typescript theme={null}
const html = await ios.getContent();
const elementHtml = await ios.getContent('#container');
```

<ParamField path="selector" type="string">
  Optional CSS selector or element ref
</ParamField>

<ResponseField name="return" type="string">
  HTML content
</ResponseField>

### isVisible()

Check if element is visible.

```typescript theme={null}
const visible = await ios.isVisible('#modal');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ResponseField name="return" type="boolean">
  True if element is visible
</ResponseField>

### isEnabled()

Check if element is enabled.

```typescript theme={null}
const enabled = await ios.isEnabled('#submit');
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ResponseField name="return" type="boolean">
  True if element is enabled
</ResponseField>

### count()

Get count of matching elements.

```typescript theme={null}
const count = await ios.count('.item');
```

<ParamField path="selector" type="string">
  CSS selector
</ParamField>

<ResponseField name="return" type="number">
  Number of matching elements
</ResponseField>

### getBoundingBox()

Get element bounding box.

```typescript theme={null}
const box = await ios.getBoundingBox('#element');
console.log(box.x, box.y, box.width, box.height);
```

<ParamField path="selector" type="string">
  CSS selector or element ref
</ParamField>

<ResponseField name="return" type="{ x: number; y: number; width: number; height: number } | null">
  Bounding box or null if element not found
</ResponseField>

## Screenshots

### screenshot()

Take a screenshot.

```typescript theme={null}
// Save to file
await ios.screenshot({ path: './screen.png' });

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

<ParamField path="options" type="object">
  <ParamField path="path" type="string">Output file path</ParamField>
  <ParamField path="fullPage" type="boolean">Capture full page (iOS limitation: may not work)</ParamField>
</ParamField>

<ResponseField name="return" type="{ path?: string; base64?: string }">
  Screenshot result with path or base64 data
</ResponseField>

## JavaScript Execution

### evaluate()

Execute JavaScript in page context.

```typescript theme={null}
const title = await ios.evaluate<string>('document.title');

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

<ParamField path="script" type="string">
  JavaScript code to execute
</ParamField>

<ParamField path="args" type="unknown[]">
  Arguments to pass to the script
</ParamField>

<ResponseField name="return" type="T">
  Script execution result
</ResponseField>

## Wait Functions

### wait()

Wait for element or timeout.

```typescript theme={null}
// 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 });
```

<ParamField path="options" type="object">
  <ParamField path="selector" type="string">CSS selector or element ref</ParamField>
  <ParamField path="timeout" type="number">Timeout in milliseconds (default: 30000)</ParamField>

  <ParamField path="state" type="'attached' | 'detached' | 'visible' | 'hidden'">
    Element state to wait for (default: 'attached')
  </ParamField>
</ParamField>

## Device Info

### getDeviceInfo()

Get current device information.

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

<ResponseField name="return" type="{ name: string; udid: string } | null">
  Device info or null if not launched
</ResponseField>

## TypeScript Types

```typescript theme={null}
import type {
  IOSManager,
  IOSDeviceInfo,
  IOSEnhancedSnapshot,
  IOSRefMap
} from '@agentic-labs/browser';
```