@acabai/ios

iOS automation library for acabAI. Automate UI actions, extract data, and perform assertions using AI.

This package uses Appium and WebdriverIO to provide a robust and flexible iOS automation solution.

Installation

npm install @acabai/ios webdriverio

Note: You need to have Appium server installed and running to use this package. See Appium Installation Guide for details.

Documentation

Basic Usage with Local Appium Server

import { IOSAgent, agentFromLocalAppium, type IOSCapabilities } from '@acabai/ios';

// Define capabilities for the iOS device/simulator
const capabilities: IOSCapabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone Simulator',
  'appium:udid': 'device_udid', // Optional: Specific device ID
  'appium:bundleId': 'com.apple.Preferences',
  'appium:noReset': true
};

// Create an agent using a local Appium server
const agent = await agentFromLocalAppium(capabilities);

// Launch the app
await agent.launch('com.apple.Preferences');

// Take a screenshot
const screenshot = await agent.page.screenshotBase64();

// Get screen size
const size = await agent.page.size();

// Tap on the screen
await agent.page.tap(100, 200);

// Scroll down
await agent.page.scrollDown(200);

// Use AI to find and interact with elements
await agent.aiAction('Find and tap on the Wi-Fi option');

// Check conditions with AI
const isEnabled = await agent.aiAssert('Is Wi-Fi enabled?');

// Clean up
await agent.page.disconnect();

Using a Custom Appium Server

import { 
  agentFromAppiumServer, 
  type AppiumServerConfig, 
  type IOSCapabilities 
} from '@acabai/ios';

// Define custom Appium server configuration
const serverConfig: AppiumServerConfig = {
  hostname: 'appium.example.com',
  port: 4723,
  path: '/wd/hub',
  protocol: 'https'
};

// Define capabilities for the iOS device
const capabilities: IOSCapabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone',
  'appium:bundleId': 'com.example.app'
};

// Create an agent using the custom Appium server
const agent = await agentFromAppiumServer(serverConfig, capabilities);

Using Sauce Labs

import { 
  agentFromSauceLabs, 
  type SauceLabsConfig, 
  type IOSSauceLabsCapabilities 
} from '@acabai/ios';

// Define Sauce Labs configuration
const sauceConfig: SauceLabsConfig = {
  username: 'your-sauce-username',
  accessKey: 'your-sauce-access-key',
  region: 'us-west-1' // or 'us-east-1' or 'eu-central-1'
};

// Define capabilities for the iOS device on Sauce Labs
const capabilities: IOSSauceLabsCapabilities = {
  platformName: 'iOS',
  'appium:automationName': 'XCUITest',
  'appium:deviceName': 'iPhone.*',
  'appium:platformVersion': '16',
  'appium:bundleId': 'com.apple.Preferences',
  'sauce:options': {
    name: 'My iOS Test',
    build: 'Build 1'
  }
};

// Create an agent using Sauce Labs
const agent = await agentFromSauceLabs(sauceConfig, capabilities);

Required Appium Capabilities

The following capabilities are required for basic Appium functionality:

• platformName: Must be 'iOS'
• appium:automationName: Should be 'XCUITest' for iOS
• appium:deviceName: A name for the device (e.g., 'iPhone Simulator', 'iPhone 14')

Additional useful capabilities:

• appium:udid: Device ID for connecting to a specific device
• appium:app: Path or URL to the .app or .ipa file
• appium:bundleId: Bundle ID of the app
• appium:platformVersion: iOS version
• appium:noReset: Prevent app data from being cleared between sessions
• appium:autoAcceptAlerts: Automatically accept permission alerts

Appium Server Setup

macOS Requirements

iOS automation with Appium requires macOS with:

1. Xcode (from App Store)
2. Xcode Command Line Tools: xcode-select --install
3. Node.js and npm
4. Appium: npm install -g appium
5. Appium XCUITest driver: appium driver install xcuitest

Checking Setup

Use appium-doctor to verify your setup:

npm install -g appium-doctor
appium-doctor --ios

Fix any issues reported by appium-doctor before using this package.

Examples

The package includes several examples in the examples directory:

• basic-usage.ts: Basic iOS automation
• custom-hub.ts: Using a custom Appium server
• sauce-labs.ts: Using Sauce Labs cloud testing
• ai-automation.ts: AI-powered automation

Run the examples with:

# Basic usage example
npm run example:basic

# Custom Appium server example
npm run example:custom-hub

# Sauce Labs integration example
npm run example:sauce

# AI-powered automation example
npm run example:ai

License

acabAI is MIT licensed.