Baguette iOS Simulator Automation Guide

baguette GitHub tool guide thumbnail

TL;DR

TL;DR: Baguette is a Swift CLI and browser UI for headless iOS Simulator farms, with live streaming, coordinate gestures, accessibility dumps, logs, screenshots, virtual camera support, and device-farm control surfaces.

Source and Accuracy Notes

This article uses public material from tddworks/baguette, project quickstart, CLI reference, build notes, and documented web UI behavior. Commands below are limited to commands documented by Baguette project material.

Baguette targets recent Apple simulator tooling and links against private SimulatorKit and CoreSimulator frameworks shipped with Xcode. That makes environment fit more important than typical CLI tools. Expect macOS, Xcode, simulator runtime, and architecture details to affect success.

What Is baguette?

Baguette is a headless iOS Simulator manager and farm. It provides host-side input injection for iOS simulators, including taps, swipes, multi-finger gestures, keyboard events, hardware buttons, live 60 fps streaming, screenshots, logs, accessibility inspection, virtual camera support, and browser-based dashboard views.

The project solves a practical automation gap. Apple simulators are powerful, but visual control at scale can be awkward: multiple booted devices, focus pages, gesture input, screenshots, logs, accessibility tree capture, and farm overview usually require mix of Xcode UI, simctl, custom scripts, and screen-recording glue. Baguette packages those surfaces into one CLI plus web server.

Its browser UI has two major entry points. /simulators lists simulators on machine with boot and shutdown controls, per-device stream pages, DeviceKit-sourced bezel, camera, accessibility, logs, home, screenshot, app switcher controls, and focus-mode device view. /farm shows every booted simulator side by side, letting user click to focus. For agentic mobile testing, that farm view matters because computer-vision or UI agents need visual state, not only command success.

Repo-Specific Setup Workflow

Step 1: Install on supported Mac

Homebrew install path:

brew install tddworks/tap/baguette

Before blaming Baguette for failures, confirm Xcode and required iOS simulator runtimes are installed. Baguette depends on Apple simulator frameworks, not generic cross-platform device emulation.

Step 2: Start web UI

Quickstart starts local server:

# Start the web UI
baguette serve

# Single-device dashboard — list, boot/shutdown, per-device stream pages
open http://localhost:8421/simulators

# Device farm — every booted simulator side-by-side, click to focus
open http://localhost:8421/farm

Default port is 8421. Server command also supports documented options in CLI reference:

serve [--port 8421] [--host 127.0.0.1] [--device-set <path>]

Step 3: Use headless terminal workflow

Headless path lists devices, boots chosen UDID, and sends coordinate tap:

baguette list
baguette boot --udid <UDID>
baguette tap --udid <UDID> --x 219 --y 478 --width 438 --height 954

Coordinates are device points in documented CLI reference for gestures, with width and height matching simulator screen size in points. Do not hard-code values across devices unless your device set is fixed.

Step 4: Build from source when needed

Source build and tests:

make           # release build via ./build.sh
swift test     # run the test suite

Build is hybrid. Swift Package Manager fetches dependencies such as ArgumentParser, Mockable, Hummingbird, and HummingbirdWebSocket; swiftc compiles with Objective-C bridging header targeting arm64e-apple-macos26.0 and links Apple private frameworks including CoreSimulator, SimulatorKit, IOSurface, VideoToolbox, CoreGraphics, and ImageIO from Xcode private frameworks.

Step 5: Learn CLI shape before scripting

Core command pattern:

baguette <command> [options]

Important lifecycle commands:

list [--json]
boot     --udid <UDID>
shutdown --udid <UDID>
orientation --udid <UDID> <portrait|landscape-left|landscape-right|portrait-upside-down>

Frames and screenshots:

stream     --udid <UDID> [--fps 60] [--format mjpeg|avcc]
screenshot --udid <UDID> [--output <path>] [--quality 0.85] [--scale 1]

Accessibility and logs:

describe-ui --udid <UDID> [--x <px> --y <px>] [--output <path>]
logs --udid <UDID> [--level info|debug|default] [--style default|compact|json|ndjson|syslog] [--predicate <NSPredicate>] [--bundle-id <id>]

One-shot gestures include tap, double-tap, swipe, pinch, and pan. Keyboard commands include key and type. Hardware commands use press with button names such as home, lock, power, volume, action, app-switcher, swipe-to-home, and notification-center gestures.

Deeper Analysis

Baguette is important for AI tooling because mobile agents need repeatable visual and input control. Desktop web agents can use Playwright. Native iOS agents often hit rougher terrain: simulator lifecycle, visual stream, coordinate gestures, accessibility tree, logs, and screenshots must line up. Baguette creates one service layer around those concerns.

The web UI is not just convenience. A farm view becomes debugging surface for automation at scale. When tests or agents run on multiple devices, seeing all booted simulators side by side helps identify stuck launches, wrong orientation, permission dialogs, camera state, and UI drift.

Accessibility dumps may be even more valuable than pixels. describe-ui returns on-screen accessibility tree as JSON, with frames in device points so they can pipe straight back into taps. That connects perception to action: inspect UI, choose node, tap coordinates. For agent workflows, this is safer than pure image-coordinate guessing.

The private-framework dependency is tradeoff. It gives deeper simulator control and streaming capability, but may break when Xcode internals change. Teams should pin Xcode versions in CI and treat Baguette upgrades as simulator-infrastructure changes, not harmless CLI bumps.

Practical Evaluation Checklist

Confirm macOS version, Xcode version, and installed simulator runtimes.
Run baguette serve and open both /simulators and /farm.
Boot one simulator through web UI and one through CLI.
Validate baguette list --json output before automation.
Test tap coordinates on each target device size.
Compare describe-ui frames with gesture coordinates.
Exercise screenshots, logs, and stream commands under concurrent devices.
Pin Xcode and Baguette versions for CI farms.

Security Notes

Baguette controls local iOS simulators and exposes web UI. Keep serve bound to 127.0.0.1 unless you intentionally expose farm controls. Remote access could allow clicking, typing, capturing screenshots, viewing logs, or manipulating test devices.

Simulator logs and screenshots may contain tokens, app secrets, test user data, or unreleased UI. Treat captured artifacts as sensitive CI data. If agents consume screenshots or accessibility dumps, redact secrets before sending them outside local trusted environment.

Private framework linkage creates operational risk. Xcode updates can change behavior. Test Baguette after Xcode upgrades before running critical mobile automation.

FAQ

Q: Is Baguette for real iPhones? A: Project scope is iOS Simulator management and host-side simulator input injection, not physical device control.

Q: What port does web UI use? A: Quickstart opens http://localhost:8421/simulators and http://localhost:8421/farm after baguette serve.

Q: Can Baguette run headlessly? A: Yes. CLI supports list, boot, shutdown, gesture commands, streaming, screenshots, accessibility dumps, logs, keyboard input, and hardware button actions.

Q: Are gesture coordinates pixels or points? A: CLI reference describes gesture coordinates and width / height as device points for simulator screen size. Keep device dimensions accurate.

Q: Why does source build depend on Xcode internals? A: Baguette links against SimulatorKit and CoreSimulator frameworks shipped with Xcode to provide deep simulator management and streaming behavior.

Conclusion

Baguette is a serious simulator-control layer for teams building mobile automation, visual device farms, or iOS agents. Its repo-specific strength is broad surface area: web dashboard, farm view, live streams, input injection, accessibility JSON, logs, screenshots, and virtual device controls in one Swift tool.

Adopt it with environment discipline. Validate Xcode version, keep simulator device sets predictable, avoid exposing web UI, and test coordinate workflows across device sizes. If your current mobile automation depends on fragile simulator scripts, Baguette is worth evaluating as unified control plane.