{"_id":"@aiscene/ios","name":"@aiscene/ios","dist-tags":{"latest":"1.3.4"},"versions":{"1.3.4":{"name":"@aiscene/ios","version":"1.3.4","description":"iOS automation library for Midscene","keywords":["iOS UI automation","iOS AI testing","iOS automation library","iOS automation tool","iOS testing","simulator automation"],"main":"./dist/lib/index.js","module":"./dist/es/index.mjs","types":"./dist/types/index.d.ts","bin":{"midscene-ios-playground":"bin/ios-playground"},"exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/es/index.mjs","require":"./dist/lib/index.js"},"./src/bin":{"types":"./dist/types/bin.d.ts","import":"./dist/es/bin.mjs","require":"./dist/lib/bin.js"},"./mcp-server":{"types":"./dist/types/mcp-server.d.ts","import":"./dist/es/mcp-server.mjs","require":"./dist/lib/mcp-server.js"},"./package.json":"./package.json"},"scripts":{"dev":"npm run build:watch","build":"rslib build","build:watch":"rslib build --watch --no-clean","playground":"DEBUG=midscene:* tsx demo/playground.ts","test":"vitest --run","test:u":"vitest --run -u","test:ai":"AI_TEST_TYPE=iOS npm run test","test:ai:cache":"MIDSCENE_CACHE=true AI_TEST_TYPE=iOS npm run test"},"dependencies":{"@midscene/core":"^1.3.4","@midscene/shared":"^1.3.4","@midscene/webdriver":"^1.3.4","@inquirer/prompts":"^7.8.6","@midscene/playground":"^1.3.4","open":"10.1.0"},"devDependencies":{"@rslib/core":"^0.18.3","@types/node":"^18.0.0","dotenv":"^16.4.5","typescript":"^5.8.3","tsx":"^4.19.2","vitest":"3.0.5","zod":"3.24.3"},"license":"MIT","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_id":"@aiscene/ios@1.3.4","gitHead":"81fe9ab138672f084a91d607b90d22d581514541","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-eVX/ZSgYok2vxc8l54OulCBC1PEiyOCbsFC4NQ7WMFu3NpmcyBTgmqf0DWyYbnGNil7PFUgNGI1+Wskd00Hhsw==","shasum":"0b4d209e89af3874f5d49ec4e21f39b463f51f2b","tarball":"https://registry.npmjs.org/@aiscene/ios/-/ios-1.3.4.tgz","fileCount":85,"unpackedSize":43951755,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDGaYZiNnw9m3/6JbPDSDSg4BmfHBios4Em4ipK9wTmBgIgGjuNOxqi0X1UsV2i3Q3wU6Jm6RYWW72xMD0ig9qWTgo="}]},"_npmUser":{"name":"liuzhanhui","email":"870884599@qq.com"},"directories":{},"maintainers":[{"name":"liuzhanhui","email":"870884599@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ios_1.3.4_1774953275102_0.013065058982289157"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T10:34:35.016Z","1.3.4":"2026-03-31T10:34:35.534Z","modified":"2026-03-31T10:34:35.742Z"},"maintainers":[{"name":"liuzhanhui","email":"870884599@qq.com"}],"description":"iOS automation library for Midscene","keywords":["iOS UI automation","iOS AI testing","iOS automation library","iOS automation tool","iOS testing","simulator automation"],"license":"MIT","readme":"# @midscene/ios\n\niOS automation library for Midscene, providing AI-powered testing and automation capabilities for iOS simulators and devices.\n\n## Features\n\n- 🎯 **iOS Simulator Support** - Full automation support for iOS simulators\n- 🤖 **AI-Powered Actions** - Intelligent element detection and interaction\n- 📱 **Native iOS Actions** - Home button, app switcher, and iOS-specific gestures\n- 🔧 **Simple API** - Easy-to-use interface similar to @midscene/android\n- 📸 **Screenshot Capture** - Built-in screenshot functionality\n- ⌨️ **Text Input** - Support for text input including non-ASCII characters\n- 🎮 **Gesture Support** - Tap, swipe, long press, and custom gestures\n\n## Prerequisites\n\n- **macOS** (required for iOS development)\n- **Xcode** and Xcode Command Line Tools\n- **iOS Simulator** or physical iOS device\n- **WebDriverAgent** (required for automation)\n\n### Environment Setup\n\n```bash\n# Install Xcode Command Line Tools\nxcode-select --install\n\n# Verify simctl is available\nxcrun simctl list devices\n\n# Install WebDriverAgent dependency\nnpm install appium-webdriveragent\n```\n\n### WebDriverAgent Setup\n\nMidscene iOS uses WebDriverAgent for device automation. You need to prepare WebDriverAgent before using the library:\n\n#### For iOS Simulators\n\n1. **Install WebDriverAgent dependency:**\n   ```bash\n   npm install appium-webdriveragent\n   ```\n\n2. **Build and start WebDriverAgent:**\n   ```bash\n   # Navigate to WebDriverAgent project\n   cd node_modules/appium-webdriveragent\n   \n   # Build and run for simulator\n   xcodebuild -project WebDriverAgent.xcodeproj \\\n             -scheme WebDriverAgentRunner \\\n             -destination 'platform=iOS Simulator,name=iPhone 15' \\\n             test\n   ```\n\n#### For Physical iOS Devices\n\n1. **Configure Development Team:**\n   - Open `node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj` in Xcode\n   - Select your Development Team for both `WebDriverAgentLib` and `WebDriverAgentRunner` targets\n   - Ensure proper code signing is configured\n\n2. **Build and deploy to device:**\n   ```bash\n   # Replace DEVICE_UDID with your device's UDID\n   xcodebuild -project WebDriverAgent.xcodeproj \\\n             -scheme WebDriverAgentRunner \\\n             -destination 'id=YOUR_DEVICE_UDID' \\\n             test\n   ```\n\n3. **Trust Developer Certificate:**\n   - On your iOS device, go to Settings > General > VPN & Device Management\n   - Trust your developer certificate\n\n4. **Set up port forwarding (for real devices):**\n   ```bash\n   # Install iproxy (if needed)\n   brew install libimobiledevice\n   \n   # Forward local port 8100 to device port 8100\n   iproxy -u YOUR_DEVICE_ID 8100:8100\n   ```\n\n#### Alternative Setup Methods\n\nFor more advanced setup options and troubleshooting, refer to the official WebDriverAgent documentation:\n**📖 [WebDriverAgent Setup Guide](https://appium.github.io/appium-xcuitest-driver/4.25/wda-custom-server/)**\n\n> **⚠️ Important:** WebDriverAgent must be running on port 8100 (default) before using Midscene iOS. If WebDriverAgent is not detected, you'll receive setup instructions.\n\n## Installation\n\n```bash\nnpm install @midscene/ios\n# or\npnpm add @midscene/ios\n```\n\n## Quick Start\n\n### Basic Usage (Recommended)\n\n```typescript\nimport { agentFromWebDriverAgent } from '@midscene/ios';\n\n// Connect to WebDriverAgent (auto-detects device)\nconst agent = await agentFromWebDriverAgent();\n\n// Launch an app\nawait agent.launch('com.apple.MobileSafari');\n\n// Perform AI-powered actions\nawait agent.aiAct('tap on the address bar');\nawait agent.aiAct('type \"https://example.com\"');\nawait agent.aiAct('tap the go button');\n```\n\n### Using Custom WebDriverAgent Configuration\n\n```typescript\nimport { agentFromWebDriverAgent } from '@midscene/ios';\n\n// Connect to WebDriverAgent on custom host/port\nconst agent = await agentFromWebDriverAgent({\n  wdaHost: 'localhost',\n  wdaPort: 8100,  // Custom port\n  aiActionContext: 'If any popup appears, click agree',\n});\n\n// Launch app and interact\nawait agent.launch('com.yourapp.bundleid');\nawait agent.aiAct('tap the login button');\n```\n\n## API Reference\n\n### IOSDevice\n\nCore device automation class implementing the AbstractInterface.\n\n```typescript\nimport { IOSDevice } from '@midscene/ios';\n\n// Create device (deviceId is auto-detected from WebDriverAgent)\nconst device = new IOSDevice({\n  wdaHost: 'localhost',\n  wdaPort: 8100,\n});\nawait device.connect();\n\n// Basic interactions\nawait device.tap(100, 200);\nawait device.swipe(100, 200, 300, 400);\nawait device.typeText('Hello World');\nawait device.pressKey('Enter');\n\n// iOS-specific actions\nawait device.home();\nawait device.appSwitcher();\nawait device.longPress(150, 300, 1000);\n\n// Screenshots\nconst screenshot = await device.screenshotBase64();\n\n// Cleanup\nawait device.destroy();\n```\n\n### IOSAgent\n\nHigh-level agent for AI-powered automation.\n\n```typescript\nimport { IOSAgent, agentFromWebDriverAgent } from '@midscene/ios';\n\n// Recommended approach\nconst agent = await agentFromWebDriverAgent();\n\n// AI actions\nawait agent.aiAct('tap the settings icon');\nawait agent.aiQuery('what is the current battery level?');\nawait agent.aiWaitFor('the page is loaded');\n\n// App management\nawait agent.launch('com.apple.Preferences');\n```\n\n### Utility Functions\n\n```typescript\nimport {\n  checkIOSEnvironment,\n  ensureSimulatorBooted,\n  // Note: getConnectedDevices and getDefaultDevice are deprecated\n  // Use agentFromWebDriverAgent() instead\n} from '@midscene/ios';\n\n// Environment check\nconst envStatus = await checkIOSEnvironment();\nconsole.log('iOS environment available:', envStatus.available);\n\n// Simulator management (if needed)\nawait ensureSimulatorBooted('simulator-udid');\n\n// Simulator management\nawait ensureSimulatorBooted('device-udid');\n```\n\n## Configuration\n\nSet environment variables for default behavior:\n\n```bash\n# Default device UDID\nexport MIDSCENE_IOS_DEVICE_UDID=your-device-udid\n\n# Default simulator UDID\nexport MIDSCENE_IOS_SIMULATOR_UDID=your-simulator-udid\n```\n\n## Supported iOS Actions\n\n### Basic Gestures\n- `tap(x, y)` - Single tap at coordinates\n- `doubleTap(x, y)` - Double tap at coordinates\n- `longPress(x, y, duration)` - Long press with duration\n- `swipe(fromX, fromY, toX, toY)` - Swipe gesture\n\n### Text Input\n- `typeText(text)` - Type text using iOS keyboard\n- `pressKey(key)` - Press specific keys (Enter, Backspace, etc.)\n- `clearInput(element)` - Clear input field\n\n### Scrolling\n- `scrollUp/Down/Left/Right(distance?, startPoint?)` - Directional scrolling\n- `scrollUntilTop/Bottom/Left/Right(startPoint?)` - Scroll to extremes\n\n### iOS System Actions\n- `home()` - Press home button\n- `appSwitcher()` - Open app switcher\n- `hideKeyboard()` - Dismiss keyboard\n\n### AI-Powered Actions\n- `aiAct(instruction)` - Perform action based on natural language\n- `aiQuery(question)` - Query UI state with natural language\n- `aiWaitFor(condition)` - Wait for condition to be met\n\n## Device Requirements\n\n### iOS Simulators\n- Managed through Xcode\n- No additional setup required\n- Supports all iOS versions available in Xcode\n\n### Physical iOS Devices\n- Requires iOS 9.0 or later\n- Device must be in Developer Mode\n- Requires valid provisioning profile for your apps\n\n## Examples\n\n### Complete Test Example\n\n```typescript\nimport { describe, it } from 'vitest';\nimport { agentFromWebDriverAgent } from '@midscene/ios';\n\ndescribe('iOS App Test', () => {\n  it('should login to app', async () => {\n    // WebDriverAgent auto-detects the connected device\n    const agent = await agentFromWebDriverAgent();\n    \n    // Launch your app\n    await agent.launch('com.yourcompany.yourapp');\n    \n    // AI-powered login flow\n    await agent.aiAct('tap on email field');\n    await agent.aiAct('type \"user@example.com\"');\n    await agent.aiAct('tap on password field');\n    await agent.aiAct('type \"password123\"');\n    await agent.aiAct('tap the login button');\n    \n    // Verify successful login\n    await agent.aiWaitFor('dashboard is visible');\n    \n    const isLoggedIn = await agent.aiQuery('is the user logged in?');\n    expect(isLoggedIn).toBe(true);\n  });\n});\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"No iOS devices available\"**\n   - Ensure Xcode is installed\n   - Check `xcrun simctl list devices` shows available simulators\n   - Try booting a simulator manually in Xcode\n\n2. **\"Command failed: xcrun simctl\"**\n   - Verify Xcode Command Line Tools are installed\n   - Run `xcode-select --install` if needed\n   - Check `which xcrun` returns a valid path\n\n3. **Simulator not responding**\n   - Restart the simulator\n   - Try `xcrun simctl shutdown all && xcrun simctl boot <udid>`\n\n4. **App launch fails**\n   - Verify the bundle ID is correct\n   - Ensure the app is installed on the simulator\n   - Check app permissions and entitlements\n\n### Debug Mode\n\nEnable debug logging:\n\n```typescript\nprocess.env.DEBUG = 'ios:*';\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.","readmeFilename":"README.md","_rev":"1-aebff01ca5131c216b60f3cb26230bac"}