> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/macos

A macOS orb for CircleCI containing useful features and tools for macOS based jobs.


## Commands

### add-permission

Add a permission to the macOS permissions database

| Parameter | Type | Default | Description |
|---|---|---|---|
| `bundle-id` | string |  | The Bundle ID of the app to grant permissions to |
| `permission-type` | string |  | The type of permission to grant |

### add-safari-permissions

Add Safari automation permissions to the macOS permissions database and enable safaridriver testing

### add-uitest-permissions

Enable common environment permissions for testing MacOS apps with Xcode.


### add-voiceover-permissions

Enable VoiceOver permissions for testing MacOS apps.


### delete-permission

Delete a permission in the macOS permissions database

| Parameter | Type | Default | Description |
|---|---|---|---|
| `bundle-id` | string |  | The Bundle ID of the app to grant permissions to |
| `permission-type` | string |  | The type of permission to grant |

### enable-vnc

Enables VNC and sets up an account for login. Re-run your job using the `Re-run with SSH` feature, set up SSH forwarding on your _local_ machine using `ssh -p 54782 <mac container ip> -L5901:localhost:5900 -N` and connect to the host using `localhost:5901` in your favourite VNC client.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `password` | env_var_name | MAC_ORB_VNC_PASSWORD | The password of the VNC login account |
| `username` | string | vncuser | The username of the VNC login account |

### install-rosetta

Install Rosetta 2 on Apple Silicon executors

### list-permission-types

Lists the types of permissions that can be set.

### list-permissions

Lists the currently defined permissions in the permissions database.

### preboot-paired-simulator

Boots a paired iOS and watchOS simulator with the specified devices

| Parameter | Type | Default | Description |
|---|---|---|---|
| `iphone-device` | string | iPhone 13 Pro Max | The device type. E.g., "iPhone 13 Pro Max" |
| `iphone-device-udid-var` | env_var_name | MACOS_ORB_IPHONE_UDID | The name of the variable to contain the iphone's UDID e.g. IPHONE_UDID |
| `iphone-version` | string | 18.0 | The OS version. E.g., "15.0" |
| `pair-udid-var` | env_var_name | MACOS_ORB_PAIR_UDID | The name of the variable to contain the pair's UDID e.g. PAIR_UDID |
| `watch-device` | string | Apple Watch Series 7 - 45mm | The device type. E.g., "Apple Watch Series 7 - 45mm" |
| `watch-device-udid-var` | env_var_name | MACOS_ORB_WATCH_UDID | The name of the variable to contain the watch's UDID e.g. WATCH_UDID |
| `watch-version` | string | 11.0 | The OS version. E.g., "8.0" |

### preboot-simulator

Boots the iOS simulator with the specific device

| Parameter | Type | Default | Description |
|---|---|---|---|
| `device` | string | iPhone 12 | The device type. E.g., "iPhone 12" |
| `device-udid-var` | env_var_name | MACOS_ORB_DEVICE_UDID | The name of the variable to contain the device's UDID e.g. IPHONE_UDID |
| `platform` | string | iOS | The platform type. Accepts only "iOS", "watchOS", "tvOS" |
| `version` | string | 18.0 | The OS version. E.g., "14.5" |

### set-sim-location

Sets the simulator to a custom location

| Parameter | Type | Default | Description |
|---|---|---|---|
| `latitude` | string | 51.5032973 | The latitude to set for the custom location |
| `longitude` | string | -0.1195537 | The longitude to set for the custom location |

### switch-ruby

Sets the Ruby version in the job

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | 4.0.5 | The version of Ruby to switch to |

### wait-until-simulator-booted

Wait until the simulator has booted.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `device-udid-var` | env_var_name | MACOS_ORB_DEVICE_UDID | The UDID of the device to wait for |

## Examples

### enable_settings_for_ui_testing

In order to interact with the UI, a user must approve a manual dialog menu in the OS, which is not possible from a "headless" remote environment. Utilize the `add-uitest-permissions` command to disable this permissions check.


```yaml
version: '2.1'
orbs:
  macos: circleci/macos@1.0
jobs:
  build-test:
    macos:
      xcode: 11.7
    steps:
      - checkout
      - run: echo 'chruby ruby-2.7' >> ~/.bash_profile
      - macos/add-uitest-permissions
      - run: bundle install
      - run: bundle exec fastlane testandbuild
workflows:
  verify:
    jobs:
      - build-test
```