simctl-status-bar

Override or clear simulator status bar appearance for consistent screenshots and UI testing.

What it does

Controls the simulator's status bar appearance, allowing you to set specific time, network status, battery level, and WiFi state. Useful for creating consistent screenshots and testing app behavior under different device conditions.

Parameters

• udid (string, required): Simulator UDID (from simctl-list)

• operation (string, required): "override" or "clear"

• time (string, optional): Time in 24-hour format (e.g., "9:41", "23:59")

• dataNetwork (string, optional): Network type - none, 1x, 3g, 4g, 5g, lte, lte-a

• wifiMode (string, optional): WiFi state - active, searching, failed

• batteryState (string, optional): Battery state - charging, charged, discharging

• batteryLevel (number, optional): Battery percentage 0-100

Returns

JSON response with:

• Status bar modification status

• Applied parameters (for override operation)

• Guidance for verification and testing

Examples

Override with classic Apple time

await simctlStatusBarTool({
  udid: 'device-123',
  operation: 'override',
  time: '9:41',
  batteryLevel: 100
})

Simulate poor network conditions

await simctlStatusBarTool({
  udid: 'device-123',
  operation: 'override',
  dataNetwork: 'none',
  wifiMode: 'failed'
})

Simulate low battery

await simctlStatusBarTool({
  udid: 'device-123',
  operation: 'override',
  batteryState: 'discharging',
  batteryLevel: 15
})

Clear all overrides

await simctlStatusBarTool({
  udid: 'device-123',
  operation: 'clear'
})

Common Use Cases

1. Consistent screenshots: Set time to 9:41 and battery to 100% for app store screenshots

2. Network condition testing: Test app behavior with different network types

3. Low battery testing: Verify app handles low battery warnings correctly

4. UI testing: Ensure status bar doesn't interfere with visual regression tests

5. Demo mode: Clean status bar for presentations and demos

Status Bar Parameters

Time

• Format: 24-hour "HH:MM" (e.g., "9:41", "14:30", "23:59")

• Apple default: "9:41" (time of original iPhone announcement)

Data Network

• none: No cellular data

• 1x: 2G network

• 3g: 3G network

• 4g: 4G network

• 5g: 5G network

• lte: LTE network

• lte-a: LTE Advanced

WiFi Mode

• active: Connected and active

• searching: Searching for network

• failed: Connection failed

Battery State

• charging: Device is charging

• charged: Fully charged

• discharging: Running on battery

Battery Level

• Range: 0-100

• Shows percentage in status bar

Important Notes

• Screenshot consistency: Apply overrides before taking screenshots for consistent results

• Demo mode: Apple often uses 9:41 time and 100% battery for marketing materials

• Simulator only: Status bar overrides only work on simulators, not real devices

• Persistent: Overrides persist until cleared or simulator is reset

• Version compatibility: Some parameters may not work on older iOS versions

Error Handling

• Invalid time format: Error if time is not in HH:MM format

• Invalid network type: Error if dataNetwork is not in allowed list

• Invalid battery level: Error if batteryLevel is not 0-100

• Simulator not found: Validates simulator exists in cache

App Store Screenshot Best Practices

For app store screenshots, Apple recommends:

1. Time: "9:41" (Apple's standard)

2. Battery: 100% (shows full battery icon)

3. Signal: Full bars (use "lte" or "5g")

4. WiFi: Active (shows connected)

5. No notifications or indicators

await simctlStatusBarTool({
  udid: 'device-123',
  operation: 'override',
  time: '9:41',
  dataNetwork: '5g',
  wifiMode: 'active',
  batteryState: 'charged',
  batteryLevel: 100
})

Testing Workflow

1. Apply overrides: Set desired status bar state

2. Take screenshot: simctl-io <udid> screenshot to verify

3. Test app: Launch app and verify it handles the conditions

4. Clear overrides: Reset to normal state when done

Visual Verification

After applying overrides, always take a screenshot to verify the status bar appears correctly:

simctl-io <udid> screenshot

The status bar changes are visible immediately and affect all screenshots taken while overrides are active.

When to Clear Overrides

• After taking app store screenshots

• Before testing features that depend on actual device state

• When switching between different test scenarios

• At the end of automated test runs