AppleSimulatorUtils

The --setLocation command in AppleSimulatorUtils is deprecated. Use the official Apple xcrun simctl location command instead. For detailed usage and available flags, run xcrun simctl location --help.

# Instead of using AppleSimulatorUtils --setLocation
xcrun simctl location <device> <latitude> <longitude>

Because the release script fails to update Homebrew hashes correctly on the first try, you must manually update the applesimutils.rb formula in the wix-incubator/homebrew-brew repository.

1. Locate the SHA256 hashes for the assets (e.g., AppleSimulatorUtils-0.9.12.tar.gz) under the Assets section of your new GitHub release.
2. Open the formula file: applesimutils.rb in the wix-incubator/homebrew-brew repository.
3. Update the sha256 fields with the correct values found on GitHub.

To install applesimutils, you must first have Homebrew installed on your Mac. Then, tap the Wix brew repository and install the package.

brew tap wix/brew
brew install applesimutils

To publish a new version, follow these steps in order:

1. Pre-flight Check: Ensure you have direct push access to the master branch and that all features are committed and tested.
2. Run the Release Script: Execute the release script with the target version number. This will open your default Markdown editor for release notes. Important: You must completely quit the editor (e.g., Xcode) after writing your notes for the script to proceed.
3. Update Homebrew Hashes: Due to a known bug, the release script does not update Homebrew hashes correctly on the first attempt. You must manually update the SHA256 hashes in the Homebrew formula immediately after the GitHub release is live.
4. Final Verification: Verify the installation via Homebrew.

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

If the Homebrew formula update fails (for example, due to a wrong hash or bad URL), the release might be left in a broken or partial state. To unblock the process, commit an empty change to trigger a retry, then re-run the release script.

git commit --allow-empty -m "Trigger retry for release <version>"
# Then re-run the release script

If you encounter issues installing or running applesimutils, try the following steps:

1. Command Line Tools: Ensure your Xcode Command Line Tools are updated via the macOS System Update preference pane.
2. Homebrew Tap Conflicts: If Homebrew reports a conflict in the wix/brew tap, reset it:

   brew untap wix/brew && brew tap wix/brew

3. General Health: Run brew doctor and resolve any reported issues or warnings.

You can grant or revoke specific permissions for an app bundle on a simulator. Using --setPermissions will automatically restart SpringBoard to ensure the changes take effect. You can target a simulator using its UDID (--byId) or its name (--byName).

# Set permissions using UDID
applesimutils --byId <simulator UDID> --bundle <bundle identifier> --setPermissions "<permission1>, <permission2>, ..."

# Set permissions using Name and OS
applesimutils --byName <simulator name> --byOS <simulator OS> --bundle <bundle identifier> --setPermissions "<permission1>, <permission2>, ..."

The utility provides commands to manage biometric (Face ID/Touch ID) states on booted simulators. You can enroll biometrics or simulate successful/failed authentication attempts.

# Enable/Disable biometric enrollment on a booted simulator
applesimutils --booted --biometricEnrollment YES

# Simulate a successful biometric match
applesimutils --booted --biometricMatch

# Simulate a failed biometric match
applesimutils --booted --biometricNonmatch

After completing the release and hash update, verify that the new version is correctly installed and functional using the following commands:

brew update
brew install applesimutils
applesimutils --version

The following --setPermissions options in AppleSimulatorUtils are deprecated. You should replace them with the corresponding xcrun simctl privacy commands to ensure compatibility with newer versions of iOS and Xcode.

# Example replacement for setting media library permissions
# Instead of using AppleSimulatorUtils --setPermissions medialibrary
xcrun simctl privacy media-library <device> <status>