Skip to main content
The UI configuration tools let you control how the simulator looks and capture what happens on screen — switch between light and dark mode, override the status bar to show consistent values in screenshots, and record video with automatic key frame extraction.

​
simulator_set_appearance

Switch the simulator between light and dark mode. The change applies system-wide immediately without a reboot.

​
Parameters

​
mode
string
required
The appearance mode to apply. One of "light" or "dark".
​
deviceId
string
Target device UDID or name. Defaults to the booted simulator.

​
Example

simulator_set_appearance mode="dark"
simulator_set_appearance mode="light"

​
simulator_override_status_bar

Override individual status bar fields to produce consistent, reproducible screenshots. Useful for marketing assets and visual regression tests where the real time, battery, and signal would vary.

​
Parameters

​
time
string
Time string to display. For example, "9:41".
​
batteryLevel
number
Battery percentage from 0 to 100.
​
batteryState
string
Battery state. One of "charging", "charged", or "discharging".
​
cellularBars
number
Cellular signal strength from 0 to 4.
​
wifiBars
number
WiFi signal strength from 0 to 3.
​
networkType
string
Data network type to display. One of: wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc.
​
operatorName
string
Carrier or operator name to display.
​
clear
boolean
Set to true to remove all status bar overrides and restore the real values.
​
deviceId
string
Target device UDID or name. Defaults to the booted simulator.

​
Example: screenshot-ready status bar

# Configure a clean status bar for marketing screenshots
simulator_override_status_bar \
  time="9:41" \
  batteryLevel=100 \
  batteryState="charged" \
  cellularBars=4 \
  wifiBars=3 \
  networkType="5g" \
  operatorName="Carrier"

# After screenshots, restore real values
simulator_override_status_bar clear=true

​
simulator_record_video

Start recording the simulator screen to a temporary video file. Use simulator_stop_recording to stop and retrieve key frames as inline images.
Only one recording can be active per device at a time. If a recording is already in progress, the tool returns an error asking you to stop it first.

​
Parameters

​
codec
string
Video codec to use for encoding. One of "h264" (default) or "hevc".
​
display
string
Which display to capture. One of "internal" (default) or "external".
​
mask
string
How to handle the non-rectangular device mask. One of "ignored", "alpha", or "black".
​
deviceId
string
Target device UDID or name. Defaults to the booted simulator.

​
Example

simulator_record_video codec="h264"
# → Video recording started (h264). Use simulator_stop_recording to stop and get key frames.

​
simulator_stop_recording

Stop an active recording. Key frames are extracted from the video at even intervals and returned inline as JPEG images — no video file is saved to disk unless you provide savePath.

​
Parameters

​
savePath
string
Optional path to save the full video file. If omitted, the temporary video is discarded after key frame extraction. Parent directories are created automatically.
​
maxFrames
number
Maximum number of key frames to extract. Defaults to 3. Maximum is 6. If ffmpeg is not available, a single final screenshot is returned instead.
​
deviceId
string
Target device UDID or name. Defaults to the booted simulator.

​
Example

# Stop and get 5 key frames, also save the full video
simulator_stop_recording maxFrames=5 savePath="/tmp/recordings/flow.mp4"

​
Dark Mode Testing Workflow

Switch between appearances and capture screenshots to verify your app’s dark mode support.
1

Set a consistent status bar

Override the status bar so both screenshots have the same time and battery state:
simulator_override_status_bar time="9:41" batteryLevel=100 batteryState="charged"
2

Capture the light mode screenshot

simulator_set_appearance mode="light"
simulator_screenshot
3

Switch to dark mode and screenshot again

simulator_set_appearance mode="dark"
simulator_screenshot
4

Clear the status bar overrides

Restore real status bar values when you’re done:
simulator_override_status_bar clear=true

​
Video Recording Workflow

Record a user flow and get representative frames for review without storing video on disk.
1

Start recording

simulator_record_video codec="h264"
2

Perform the interactions you want to capture

Navigate through screens, fill forms, trigger transitions, and exercise the feature under test.
3

Stop recording and retrieve key frames

Stop the recording and extract evenly-spaced frames. With ffmpeg installed, frames are extracted from across the full duration:
simulator_stop_recording maxFrames=4
The response contains JPEG images directly — no files accumulate on your Desktop.
4

Optionally save the full video

If you need the raw video for a report or CI artifact:
simulator_stop_recording maxFrames=4 savePath="/tmp/recordings/onboarding-flow.mp4"
Install ffmpeg for best frame extraction results. Without it, only a single final screenshot is returned.

Build docs developers (and LLMs) love

Get started for freeTalk to us