Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

ios-simulator

/ios-simulator

Steruje symulatorem iOS i iPadOS z wiersza poleceń przez xcrun simctl dla aplikacji fintech: urządzenia, instalacja, push APNs, deep linki, uprawnienia prywatności, lokalizacja i nadpisanie paska stanu.

Repozytorium
kmp-ios-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
25.08.2026

Ocena i bezpieczeństwo

87/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność17 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.08.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Steruje symulatorem iOS i iPadOS z wiersza poleceń przez xcrun simctl dla aplikacji fintech: urządzenia, instalacja, push APNs, deep linki, uprawnienia prywatności, lokalizacja i nadpisanie paska stanu.

Oryginalny opis (EN)

Drive the iOS/iPadOS Simulator from the command line with xcrun simctl for a fintech app — list/create/boot/shutdown/erase/delete/clone devices and runtimes; install/launch/terminate/uninstall apps; push remote APNs (aps JSON payload); openurl for custom-scheme deep links and Universal Links; privacy grant/revoke/reset (photos, contacts, location, camera, calendar…); location set/run/clear (fixed coords + built-in scenarios); status_bar override (9:41 time, battery, wifi/cellular bars) for App Store screenshots; io screenshot/recordVideo; spawn log stream --predicate; get_app_container; addmed

Jak działa

  1. Contents
  2. Device identity & booted
  3. Lifecycle: create / boot / erase / delete
  4. Apps: install / launch / terminate / uninstall
  5. Push notifications (APNs)
  6. Deep links & Universal Links (openurl)
  7. Privacy permissions
  8. Location
  9. Status bar overrides
  10. Screenshots & video (io)
Sekcje z nagłówków SKILL.md, w oryginale · 286 linii, 2 216 słów
Podgląd SKILL.md
---
name: ios-simulator
description: "Drive the iOS/iPadOS Simulator from the command line with xcrun simctl for a fintech app — list/create/boot/shutdown/erase/delete/clone devices and runtimes; install/launch/terminate/uninstall apps; push remote APNs (aps JSON payload); openurl for custom-scheme deep links and Universal Links; privacy grant/revoke/reset (photos, contacts, location, camera, calendar…); location set/run/clear (fixed coords + built-in scenarios); status_bar override (9:41 time, battery, wifi/cellular bars) for App Store screenshots; io screenshot/recordVideo; spawn log stream --predicate; get_app_container; addmedia; keychain add-root-cert. Also which behaviors REQUIRE a real device (camera capture, Secure Enclave, App Attest/DeviceCheck, some background modes). Use when scripting Simulator setup, CI screenshots, notification/deep-link testing, or permission fixtures. Siblings: push-notifications (APNs auth/production), deep-linking (Universal Links/associated domains), ios-testing (XCUITest launch args), device-integrity (App Attest — real device only), swift-security (Secure Enclave), debugging-instruments (LLDB/Instruments)."
---

# iOS Simulator (`xcrun simctl`)

Command-line control of the iOS/iPadOS/watchOS/tvOS Simulator for scripting,
CI, and local fixtures. Everything routes through `simctl`; the Simulator.app GUI
is optional. Targets Xcode 16/17, iOS 26 era.

- **Device counterpart:** hardware-backed features (camera, Secure Enclave, App Attest) do **not** work in the Simulator — see [Simulator vs. real device](#device-only) and cross-reference `device-integrity` / `swift-security`.
- **UI-test driving** (tap/type/assert) is XCUITest's job, not `simctl` — see `ios-testing`. `simctl` sets up state *around* the test (permissions, push, media, location).

## Contents

- [Device identity & `booted`](#identity)
- [Lifecycle: create / boot / erase / delete](#lifecycle)
- [Apps: install / launch / terminate / uninstall](#apps)
- [Push notifications (APNs)](#push)
- [Deep links & Universal Links (`openurl`)](#openurl)
- [Privacy permissions](#privacy)
- [Location](#location)
- [Status bar overrides](#status-bar)
- [Screenshots & video (`io`)](#io)
- [Logs (`spawn log stream`)](#logs)
- [App container, media, keychain](#misc)
- [Simulator vs. real device](#device-only)
- [Checklist](#checklist)
- Depth: `references/command-reference.md`, `references/device-vs-simulator.md`

<a id="identity"></a>
## Device identity & `booted`

Every device has a UDID. Most subcommands take a **device specifier**: a UDID, a
device name, or the literal `booted` (the single currently-booted device — errors
if zero or more than one is booted).

```bash
xcrun simctl list devices           # all devices, grouped by runtime; shows (Booted)
xcrun simctl list devices booted     # only booted ones
xcrun simctl list devices available -j   # JSON; filter to installed runtimes only
xcrun simctl list runtimes           # installed iOS/watchOS/… runtimes + identifiers
xcrun simctl list devicetypes        # e.g. com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro
```

- Parse JSON (`-j` / `--json`), never scrape the human table, in scripts. `devices` JSON keys each list by runtime identifier; each entry has `udid`, `name`, `state`, `isAvailable`.
- Resolve one UDID in a script:

```bash
UDID=$(xcrun simctl list devices -j \
  | jq -r '.devices[][] | select(.name=="iPhone 16 Pro" and .isAvailable) | .udid' | head -1)
```

- A name is ambiguous if it exists under multiple runtimes — prefer a resolved UDID in CI.

<a id="lifecycle"></a>
## Lifecycle: create / boot / erase / delete

```bash
# Create: <name> <devicetype> [<runtime>]
UDID=$(xcrun simctl create "CI-iPhone" \
  "com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro" \
  "com.apple.CoreSimulator.SimRuntime.iOS-26-0")

xcrun simctl boot     "$UDID"        # boot headless (no GUI)
open -a Simulator                    # optionally show the GUI window
xcrun simctl bootstatus "$UDID" -b   # wait until fully booted, then exit
xcrun simctl shutdown "$UDID"        # (or: shutdown all)
xcrun simctl erase    "$UDID"        # wipe to factory — device must be shut down (or: erase all)
xcrun simctl delete   "$UDID"        # remove device (or: delete unavailable / all)
xcrun simctl clone    "$UDID" "CI-iPhone-copy"   # snapshot a configured device
```

- `boot` is idempotent-ish: booting an already-booted device errors — guard with a state check or `|| true` in CI.
- `bootstatus -b` blocks until services are up; use it before `install`/`launch` to avoid races. `boot` returning is **not** the same as "ready".
- `erase all` requires every device shut down first (`shutdown all && erase all`).
- Reset a corrupt CoreSimulator state as a last resort: `xcrun simctl shutdown all && xcrun simctl erase all`.
- Isolate CI state with a private set: prepend `--set <path>` (e.g. `xcrun simctl --set ./.sim create …`) so devices don't pollute the developer's default set.

<a id="apps"></a>
## Apps: install / launch / terminate / uninstall

```bash
xcrun simctl install   booted /path/to/MyApp.app          # install a built .app (Simulator slice)
xcrun simctl launch    booted com.example.myapp            # launch by bundle id
xcrun simctl terminate booted com.example.myapp
xcrun simctl uninstall booted com.example.myapp
```

- Install the **Simulator build** (`.app` from a `iphonesimulator` SDK build), not a device `.ipa`.
- Launch with arguments / environment (consumed by XCUITest launch arguments or your own flags):

```bash
xcrun simctl launch booted com.example.myapp -uiTestMode YES        # launch args after bundle id
SIMCTL_CHILD_MY_FLAG=1 xcrun simctl launch booted com.example.myapp  # SIMCTL_CHILD_* → app's env
xcrun simctl launch --console booted com.example.myapp               # attach stdout/stderr
xcrun simctl launch --wait-for-debugger booted com.example.myapp
```

- `SIMCTL_CHILD_<VAR>` sets `<VAR>` in the launched process's environment — the standard way to inject config/feature flags at launch. Pairs with `ios-testing` `XCUIApplication().launchArguments`.

<a id="push"></a>
## Push notifications (APNs)

Simulate a **remote** notification without a real APNs round-trip.

```bash
xcrun simctl push booted com.example.myapp payload.json
xcrun simctl push booted com.example.myapp -            # read payload from stdin
```

```json
{
  "Simulator Target Bundle": "com.example.myapp",
  "aps": {
    "alert": { "title": "Payment received", "body": "You got $50.00" },
    "badge": 1,
    "sound": "default"
  }
}
```

- Payload rules (enforced): top-level **object**, must contain a valid `aps` key, and be **≤ 4096 bytes**.
- The bundle id can be supplied as the CLI arg **or** via the `"Simulator Target Bundle"` top-level key; the CLI arg wins if both are present.
- **Only ordinary remote pushes.** VoIP (PushKit), Complication, and File Provider pushes are **not** simulable — those need a real device / real APNs. For actual APNs auth-key/token setup and production delivery see `push-notifications`.
- `simctl push` neither prompts nor authorizes notifications itself: the app must have registered for remote notifications and hold notification authorization. There is **no** `notifications` TCC service, so you can't pre-grant it via `privacy` — drive the authorization prompt in-app (or via XCUITest).

<a id="openurl"></a>
## Deep links & Universal Links (`openurl`)

```bash
xcrun simctl openurl booted "myapp://transfer?amount=50&to=alice"   # custom URL scheme
xcrun simctl openurl booted "https://pay.example.com/invoice/42"    # Universal Link
xcrun simctl openurl booted "mailto:test@example.com"              # system-handled URL
```

- Custom-scheme links route to whichever installed app declares the scheme.
- **Universal Links** open in your app only if it ships the `applinks:` Associated Domains entitlement and the `apple-app-site-association` (AASA) file resolves for that domain; otherwise the URL opens in Safari. See `deep-linking` for AASA/entitlement setup.
- **Known issue (Xcode 26 simulators):** Universal Links may fail to route to the app in the Simulator even when correctly configured — verify Universal Link behavior on a real device, and use custom schemes for Simulator smoke tests.

<a id="privacy"></a>
## Privacy permissions

Pre-grant or reset TCC permissions so tests don't stall on system prompts.

```bash
xcrun simctl privacy booted grant  photos   com.example.myapp
xcrun simctl privacy booted revoke location com.example.myapp
xcrun simctl privacy booted reset  all       com.example.myapp   # back to "unasked" → prompt reappears
xcrun simctl privacy booted reset  contacts  com.example.myapp
```

- Actions: `grant`, `revoke`, `reset`. A bundle id is required for `grant`/`revoke`; `reset` accepts a bundle id or applies broadly.
- Services (per `simctl privacy` in Xcode 26): `all`, `calendar`, `contacts-limited`, `contacts`, `location`, `location-always`, `photos-add`, `photos`, `media-library`, `microphone`, `motion`, `reminders`, `siri`, plus `camera` (accepted although omitted from the help text). There is **no** `faceid`, `speech-recognition`, `user-tracking`, or `notifications` service — `simctl privacy` rejects those names; run `xcrun simctl privacy` with no args for the authoritative list.
- `grant`/`revoke` cover services routed through TCC. Some prompts (notification authorization, the ATT dialog) are managed by the app/OS, are **not** standalone `privacy` services, and still surface — drive them in-app; `privacy reset all` returns TCC state broadly to the fresh-prompt state.
- Pre-granting `camera`/`microphone` only silences the *permission* prompt; the Simulator still has **no real camera** (see [device-only](#device-only)).

<a id="location"></a>
## Location

```bash
xcrun simctl location booted set 40.7580,-73.9855          # fixed lat,long (Times Square)
xcrun simctl location booted list                          # built-in scenario names
xcrun simctl location booted run "City Run"                # replay a built-in scenario
xcrun simctl location booted start --speed=25 \
  40.75,-73.98 40.76,-73.97                                # follow a waypoint path
xcrun simctl location booted clear                         # revert to no simulated location
```

- `set` pins one coordinate; `run` replays Apple's built-in scenarios (e.g. City Run, Freeway Drive); `start` follows supplied waypoints (optionally `--speed`, `--distance`, `--interval`); `clear` removes the override.
- This drives CoreLocation for the whole device — the app must still hold `location` (or `location-always`) authorization; grant it via [`privacy`](#privacy).

<a id="status-bar"></a>
## Status bar overrides

Deterministic status bar for App Store screenshots ("9:41", full battery, full bars).

```bash
xcrun simctl status_bar booted override \
  --time "9:41" \
  --dataNetwork wifi --wifiMode active --wifiBars 3 \
  --cellularMode active --cellularBars 4 \
  --batteryState charged --batteryLevel 100

xcrun simctl status_bar booted clear        # remove overrides
```

- Flags: `--time`, `--dataNetwork` (`wifi`/`3g`/`4g`/`lte`/`5g`…), `--wifiMode`/`--wifiBars` (0–3), `--cellularMode`/`--cellularBars` (0–4), `--batteryState` (`charging`/`charged`/`discharging`) + `--batteryLevel` (0–100), `--operatorName`.
- Overrides are **not persistent** — they reset when the device shuts down / relaunches. Re-apply in the screenshot script right before capturing.
- Run `xcrun simctl status_bar booted override` with no flags to print the full option list for the installed Xcode.

<a id="io"></a>
## Screenshots & video (`io`)

```bash
xcrun simctl io booted screenshot shot.png                 # PNG of the current screen
xcrun simctl io booted screenshot --mask=black shot.png    # notch/corner mask: ignored|alpha|black
xcrun simctl io booted recordVideo --codec=h264 demo.mov   # Ctrl-C to stop; default codec hevc
xcrun simctl io booted recordVideo --mask=black --force out.mp4
```

- `screenshot`: `--type` (`png`/`jpeg`), `--display` (`internal`/`external`), `--mask` (`ignored`/`alpha`/`black`). Use `alpha`/`black` for rounded/notched framing in marketing shots.
- `recordVideo`: `--codec` (`hevc` default, or `h264` for broader compatibility), `--mask`, `--force` (overwrite). Stop with `SIGINT` (Ctrl-C); in scripts send `kill -INT` to the recorder PID.

<a id="logs"></a>
## Logs (`spawn log stream`)

Run a process inside the Simulator; commonly the unified-logging `log` tool.

```bash
# Live stream, filtered by predicate:
xcrun simctl spawn booted log stream \
  --level debug \
  --predicate 'subsystem == "com.example.myapp"'

# Filter by process:
xcrun simctl spawn booted log stream --predicate 'processImagePath ENDSWITH "myapp"'

# Dump a past window instead of streaming:
xcrun simctl spawn booted log show --last 5m --predicate 'category == "network"'
```

- The `--predicate` is an `NSPredicate` over unified-logging fields: `subsystem`, `category`, `process`, `processImagePath`, `eventMessage`, `messageType`. Quote carefully in the shell.
- Set `subsystem`/`category` in your `Logger` (os.log) so this filtering is precise — see `debugging-instruments` for the LLDB/Instruments side.

<a id="misc"></a>
## App container, media, keychain

```bash
# Absolute path to a container (inspect sandbox files, DBs, Documents):
xcrun simctl get_app_container booted com.example.myapp data     # app|data|groups|<group id>
DB="$(xcrun simctl get_app_container booted com.example.myapp data)/Documents/app.sqlite"

# Seed the photo library / media:
xcrun simctl addmedia booted photo1.jpg clip.mov

# Trust a self-signed root CA (e.g. Proxyman/Charles TLS interception in dev):
xcrun simctl keychain booted add-root-cert ./proxymanCA.pem
xcrun simctl keychain booted reset                              # clear the device keychain
```

- `get_app_container` container types: `app` (the bundle), `data` (the sandbox — Documents/Library/tmp), `groups` (all App Groups), or a specific `group.<id>`.
- `addmedia` imports into Photos; grant `photos` via [`privacy`](#privacy) if the app reads them.
- `keychain add-root-cert` installs a CA so the Simulator trusts a dev proxy's TLS certs. **Dev only** — never a substitute for real certificate handling; SPKI pinning (see `swift-security`) will still reject an interception proxy by design.
- `--set <path>` also applies here (`xcrun simctl --set previews keychain booted add-root-cert …`) to target a specific device set.

<a id="device-only"></a>
## Simulator vs. real device

The Simulator runs your app against the **host Mac's** CPU, filesystem, and (in
part) frameworks — it is not an emulator of Apple hardware. Anything backed by
device silicon or peripherals behaves differently or is absent.

**Requires a real device (cannot be validated in the Simulator):**

- **Camera capture** — `AVCaptureDevice` for the camera is unavailable; there is no camera feed. (Photo *library* works; use `addmedia`.) Cross-ref `photokit`.
- **Secure Enclave** — `SecureEnclave.isAvailable` is `false`; hardware-backed keys don't exist. Guard and provide a software fallback — see `swift-security`.
- **App Attest / DeviceCheck** — depend on the Secure Enclave; attestation fails. Test on hardware — see `device-integrity`.
- **VoIP / PushKit, Complication, File Provider pushes** — not deliverable via `simctl push`.
- **Real modem/cellular, Bluetooth, NFC, motion sensors, barometer, true GPS** — absent or coarse (location is *simulated*, not sensed).
- **Some background execution** (real background app refresh scheduling, precise power/thermal behavior) and **Face ID/Touch ID hardware** — biometrics are *simulated* via the Simulator menu (Features ▸ Face ID ▸ Enrolled / Matching Face), not a real sensor.

**Gate hardware paths at compile time so Simulator builds stay runnable:**

```swift
#if targetEnvironment(simulator)
    // stub: no camera / no Secure Enclave — return a fixture or software key
#else
    // real AVCaptureSession / SecureEnclave key
#endif
```

- `#if targetEnvironment(simulator)` is a **compile-time** switch (not a runtime `if`), so simulator-only stubs are compiled out of device builds. Prefer feature-detection at runtime (`SecureEnclave.isAvailable`, `UIImagePickerController.isSourceTypeAvailable(.camera)`) where a runtime check is more honest than a build flag.

<a id="checklist"></a>
## Correctness checklist

- [ ] Scripts parse `simctl list -j` JSON and resolve a **UDID**, not a possibly-ambiguous device name.
- [ ] `bootstatus -b` (not bare `boot`) gates `install`/`launch` so services are ready.
- [ ] CI uses `--set <path>` to isolate the device set and cleans up (`shutdown`/`delete`) after.
- [ ] Simulator (`iphonesimulator` SDK) `.app` installed — not a device `.ipa`.
- [ ] Push payload is a top-level object with a valid `aps` key and ≤ 4096 bytes; only remote (non-VoIP) pushes.
- [ ] Permissions pre-set with `privacy grant`; `privacy reset` used to test the first-run prompt path.
- [ ] Universal Links verified on a **real device** (Simulator routing is unreliable on Xcode 26); custom schemes used for Simulator smoke tests.
- [ ] Status-bar override re-applied right before each screenshot (it doesn't persist across boots).
- [ ] `recordVideo` stopped with `SIGINT`; `--codec h264` when broad compatibility matters.
- [ ] Camera, Secure Enclave, App Attest/DeviceCheck, PushKit paths tested on hardware, gated with `#if targetEnvironment(simulator)` or runtime feature checks.
- [ ] `keychain add-root-cert` confined to dev; production relies on ATS + pinning (`swift-security`), which correctly defeats interception proxies.
Pliki w paczce (3)
  • SKILL.md 17 KB
  • references/command-reference.md 6 KB
  • references/device-vs-simulator.md 4 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · TalissonVitorino/kmp-ios-skills87MIT
callstack/agent-device91MIT
callstackincubator/agent-device91MIT
simiancraft/simiancraft-skills90MIT

Migawka bazy z 13.11.2026 · wersja paczki 03c3f59f4965 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95simulator-workflows
    Zarządza urządzeniami i aplikacjami symulatora iOS przez simctl: tworzy, uruchamia i diagnozuje symulatory.
  • 86herdr-ios-simulator
    Buduje, uruchamia i debuguje aplikacje iOS na symulatorze współdzielonym z użytkownikiem w herdrze, czyta logi i raporty awarii.
  • 100ios-android-logs
    Pobiera, filtruje, strumieniuje i zapisuje logi oraz raporty awarii aplikacji Capacitor na symulatorze iOS, iPhonie, emulatorze Androida i urządzeniach.
  • 100simctlhouse
    Rezerwuje na wyłączność symulator iPhone lub iPad do budowania i testów aplikacji, a potem go zwalnia.
  • 100proof
    Buduje, testuje i weryfikuje zmiany w aplikacjach iOS narzędziem proof: testy, sterowanie symulatorem, zrzuty ekranu i komentarze do PR.
  • 100ios-simulator-skill
    Buduje, testuje i steruje aplikacjami iOS w symulatorze za pomocą 30 skryptów: klikanie po etykietach dostępności, zrzuty ekranu, audyt dostępności, logi i zarządzanie symulatorami.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.