AppleSimulatorUtils

https://github.com/wix/applesimulatorutils
Admin
AppleSimulatorUtils is a command-line utility collection for managing Apple simulators, providing...
Tokens:4,361
Snippets:50
Trust Score:9.2
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Automated Test Setup Workflow

Source: https://context7.com/wix/applesimulatorutils/llms.txt

A complete script example for preparing a simulator with cleared data, specific permissions, and biometric settings.

```bash
#!/bin/bash

SIMULATOR_NAME="iPhone 15 Pro"
SIMULATOR_OS="17.0"
BUNDLE_ID="com.example.myapp"

# Boot the simulator if not already running
xcrun simctl boot "$SIMULATOR_NAME"

# Wait for simulator to be ready
sleep 5

# Clear previous test data
applesimutils --byName "$SIMULATOR_NAME" --byOS "$SIMULATOR_OS" --clearKeychain
applesimutils --byName "$SIMULATOR_NAME" --byOS "$SIMULATOR_OS" --clearMedia

# Set all required permissions for the app
applesimutils --byName "$SIMULATOR_NAME" --byOS "$SIMULATOR_OS" \
  --bundle "$BUNDLE_ID" \
  --setPermissions "camera=YES, photos=YES, microphone=YES, location=always, notifications=YES, contacts=YES, calendar=YES, faceid=YES"

# Enable biometric enrollment for Face ID tests
applesimutils --byName "$SIMULATOR_NAME" --byOS "$SIMULATOR_OS" \
  --biometricEnrollment YES

# App is now ready for automated testing
echo "Simulator configured successfully for testing"
```

--------------------------------

### Install and Verify AppleSimulatorUtils

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Install the ASU tool using Homebrew by first adding the Wix tap, then installing the package. Verify the installation by checking the version.

```bash
# Add the Wix tap and install applesimutils
brew tap wix/brew
brew install applesimutils

# Verify installation
applesimutils --version
# Output: applesimutils version 0.9.12
```

--------------------------------

### Verify installation

Source: https://github.com/wix/applesimulatorutils/blob/master/RELEASING.md

Update Homebrew and verify the new version of the binary is installed correctly.

```bash
brew update
brew install applesimutils
applesimutils --version
```

--------------------------------

### Install AppleSimulatorUtils via Homebrew

Source: https://github.com/wix/applesimulatorutils/blob/master/README.md

Use these commands to add the wix tap and install the applesimutils package.

```shell
brew tap wix/brew
brew install applesimutils
```

--------------------------------

### List Available Simulators

Source: https://context7.com/wix/applesimulatorutils/llms.txt

List all available simulators, with options to filter by name, OS version, device type, or state. Results can be limited and specific fields can be selected.

```bash
# List all available simulators
applesimutils --list
```

```bash
# List simulators filtered by name
applesimutils --list --byName "iPhone 15 Pro"
```

```bash
# List simulators filtered by OS version
applesimutils --list --byOS "17.0"
```

```bash
# List simulators filtered by device type
applesimutils --list --byType "com.apple.CoreSimulator.SimDeviceType.iPhone-15-Pro"
```

```bash
# List only booted simulators
applesimutils --list --booted
```

```bash
# Combine filters and limit results
applesimutils --list --byName "iPhone" --byOS "17.0" --maxResults 3
```

```bash
# List with specific fields only
applesimutils --list --fields "udid,name,state"
```

```json
# Example JSON output:
# [
#   {
#     "udid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
#     "name": "iPhone 15 Pro",
#     "state": "Booted",
#     "os": {
#       "version": "17.0",
#       "name": "iOS 17.0"
#     },
#     "deviceType": {
#       "name": "iPhone 15 Pro",
#       "identifier": "com.apple.CoreSimulator.SimDeviceType.iPhone-15-Pro"
#     }
#   }
# ]
```

--------------------------------

### Execute the release script

Source: https://github.com/wix/applesimulatorutils/blob/master/RELEASING.md

Run the release script with the target version number as an argument.

```bash
./releaseVersion.sh <YOUR_VERSION>
# e.g.
./releaseVersion.sh 0.9.12
```

--------------------------------

### Execute AppleSimulatorUtils Commands

Source: https://github.com/wix/applesimulatorutils/blob/master/README.md

Common usage patterns for filtering simulators, setting permissions, and managing biometric states.

```text
A collection of utils for Apple simulators.

Usage Examples:
    applesimutils --byId <simulator UDID> --bundle <bundle identifier> --setPermissions "<permission1>, <permission2>, ..."
    applesimutils --byName <simulator name> --byOS <simulator OS> --bundle <bundle identifier> --setPermissions "<permission1>, <permission2>, ..."
    applesimutils --list [--byName <simulator name>] [--byOS <simulator OS>] [--byType <simulator device type>] [--maxResults <int>] [--fields <key1,key2,...>]
    applesimutils --booted --biometricEnrollment <YES/NO>
    applesimutils --booted --biometricMatch

Options:
    --byId, -id                   Filters simulators by unique device identifier (UDID)
    --byName, -n                  Filters simulators by name
    --byType, -t                  Filters simulators by device type
    --byOS, -o                    Filters simulators by operating system
    --booted, -bt                 Filters simulators by booted status

    --list, -l                    Lists available simulators
    --bundle, -b                  The app bundle identifier
    --maxResults                  Limits the number of results returned from --list
    --fields                      Comma-separated list of fields to include in --list output (e.g. "udid,os,identifier")

    --setPermissions, -sp         Sets the specified permissions and restarts SpringBoard for the changes to take effect
    --clearKeychain, -ck          Clears the simulator's keychain
    --clearMedia, -cm             Clears the simulator's media
    --restartSB, -sb              Restarts SpringBoard

    --biometricEnrollment, -be    Enables or disables biometric (Face ID/Touch ID) enrollment.
    --biometricMatch, -bm         Approves a biometric authentication request with a matching biometric feature (e.g. face or finger)
    --biometricNonmatch, -bnm     Fails a biometric authentication request with a non-matching biometric feature (e.g. face or finger)

    --version, -v                 Prints version
    --help, -h                    Prints usage

Available Permissions:
    calendar=YES|NO|unset
    camera=YES|NO|unset
    contacts=YES|NO|unset
    faceid=YES|NO|unset
    health=YES|NO|unset (iOS/tvOS 12.0 and above)
    homekit=YES|NO|unset
    location=always|inuse|never|unset
    medialibrary=YES|NO|unset
    microphone=YES|NO|unset
    motion=YES|NO|unset
    notifications=YES|NO|critical|unset
    photos=YES|NO|limited|unset (“limited” supported on iOS/tvOS 14.0 and above)
    reminders=YES|NO|unset
    siri=YES|NO|unset
    speech=YES|NO|unset
    userTracking=YES|NO|unset (iOS/tvOS 14.0 and above)
```

--------------------------------

### Configure Biometric Testing

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Commands to enable biometric enrollment and simulate authentication events on a target simulator.

```bash
applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
  --biometricEnrollment YES
```

```bash
applesimutils --booted --biometricEnrollment YES
applesimutils --booted --biometricMatch
```

--------------------------------

### Filter Simulators

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Demonstrates various filtering criteria to target specific simulators for operations or listing.

```bash
applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" --list

applesimutils --byName "iPhone 15 Pro" --list

applesimutils --byOS "17.0" --list
applesimutils --byOS "iOS 17.0" --list

applesimutils --byType "iPhone 15 Pro" --list
applesimutils --byType "com.apple.CoreSimulator.SimDeviceType.iPhone-15-Pro" --list

applesimutils --booted --list

applesimutils --byName "iPhone" --byOS "17.0" --booted --list
```

--------------------------------

### Clear Simulator Media

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Removes all photos and videos from the simulator's media library to ensure a clean test state.

```bash
applesimutils --booted --clearMedia

applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" --clearMedia

applesimutils --byName "iPhone 15 Pro" --byOS "17.0" --clearMedia
```

--------------------------------

### Control Biometric Authentication

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Manage biometric enrollment and simulate authentication outcomes for Face ID and Touch ID on a booted simulator. Useful for testing apps that rely on biometric authentication.

```bash
# Enable biometric enrollment (Face ID or Touch ID)
applesimutils --booted --biometricEnrollment YES
```

```bash
# Disable biometric enrollment
applesimutils --booted --biometricEnrollment NO
```

```bash
# Simulate successful biometric authentication (matching face/finger)
applesimutils --booted --biometricMatch
```

```bash
# Simulate failed biometric authentication (non-matching face/finger)
applesimutils --booted --biometricNonmatch
```

--------------------------------

### Restart SpringBoard

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Forces a restart of the SpringBoard process, often required after applying permission changes.

```bash
applesimutils --booted --restartSB

applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" --restartSB
```

--------------------------------

### Clear Simulator Keychain

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Removes all stored credentials and secure data from the simulator's keychain to reset authentication state.

```bash
applesimutils --booted --clearKeychain

applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" --clearKeychain

applesimutils --byName "iPhone 15 Pro" --byOS "17.0" --clearKeychain
```

--------------------------------

### Trigger a release retry

Source: https://github.com/wix/applesimulatorutils/blob/master/RELEASING.md

Commit an empty change to trigger a retry if the Homebrew formula update fails.

```bash
git commit --allow-empty -m "Trigger retry for release <version>"
```

--------------------------------

### Set App Permissions

Source: https://context7.com/wix/applesimulatorutils/llms.txt

Modify Transparency, Consent, and Control (TCC) database permissions for a specific app on a simulator. Supports single or multiple permissions, and can target simulators by UDID, name, or OS.

```bash
# Set single permission by simulator UDID
applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
  --bundle "com.example.myapp" \
  --setPermissions "camera=YES"
```

```bash
# Set multiple permissions at once
applesimutils --byId "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" \
  --bundle "com.example.myapp" \
  --setPermissions "camera=YES, photos=YES, microphone=YES, location=always"
```

```bash
# Set permissions by simulator name and OS
applesimutils --byName "iPhone 15 Pro" --byOS "17.0" \
  --bundle "com.example.myapp" \
  --setPermissions "contacts=YES, calendar=YES, reminders=YES"
```

```bash
# Set permissions on booted simulator
applesimutils --booted \
  --bundle "com.example.myapp" \
  --setPermissions "notifications=YES, faceid=YES"
```

```bash
# Reset permissions to unset state
applesimutils --booted \
  --bundle "com.example.myapp" \
  --setPermissions "camera=unset, photos=unset"
```

```text
# Available permission values:
# - calendar=YES|NO|unset
# - camera=YES|NO|unset
# - contacts=YES|NO|unset
# - faceid=YES|NO|unset
# - health=YES|NO|unset (iOS 12.0+)
# - homekit=YES|NO|unset
# - location=always|inuse|never|unset
# - medialibrary=YES|NO|unset
# - microphone=YES|NO|unset
# - motion=YES|NO|unset
# - notifications=YES|NO|critical|unset
# - photos=YES|NO|limited|unset (limited: iOS 14.0+)
# - reminders=YES|NO|unset
# - siri=YES|NO|unset
# - speech=YES|NO|unset
# - userTracking=YES|NO|unset (iOS 14.0+)
```

--------------------------------

### Identify SHA256 hash

Source: https://github.com/wix/applesimulatorutils/blob/master/RELEASING.md

Locate the SHA256 hash from the GitHub release assets.

```text
AppleSimulatorUtils-0.9.12.tar.gz
sha256:4d6d02...
...
```
Tokens:
Raw