Diagnostic Commands

This page contains commands you can run to verify your Specchio installation and diagnose issues.

Quick Health Check
Xcode Verification
Device Detection
WebDriverAgent Testing
Network Diagnostics
Performance Testing

Quick Health Check

All-in-One Diagnostic Script

Save this as specchio-health-check.sh:

bash

#!/bin/bash

echo "╔════════════════════════════════════════╗"
echo "║   Specchio Health Check               ║"
echo "╚════════════════════════════════════════╝"
echo ""

# Function to print status
print_status() {
    if [ $1 -eq 0 ]; then
        echo "✅ $2"
    else
        echo "❌ $2"
    fi
}

# 1. macOS version
echo "📱 macOS Version"
sw_vers
echo ""

# 2. Xcode
echo "🔨 Xcode"
if [ -d "/Applications/Xcode.app" ]; then
    xcodebuild -version
    print_status 0 "Xcode installed"
else
    print_status 1 "Xcode not found"
fi
echo ""

# 3. iOS SDK
echo "📲 iOS SDK"
if xcodebuild -showsdks 2>&1 | grep -q "iphoneos"; then
    xcodebuild -showsdks | grep "iphoneos"
    print_status 0 "iOS SDK installed"
else
    print_status 1 "iOS SDK not found"
fi
echo ""

# 4. Certificates
echo "🔑 Code Signing Certificates"
CERT_COUNT=$(security find-identity -v -p codesigning 2>/dev/null | grep -c "Apple Development")
if [ $CERT_COUNT -gt 0 ]; then
    security find-identity -v -p codesigning | grep "Apple Development" | head -1
    print_status 0 "Found $CERT_COUNT certificate(s)"
else
    print_status 1 "No Apple Development certificate"
fi
echo ""

# 5. Connected devices
echo "🔗 Connected iOS Devices"
DEVICES=$(xcrun devicectl list devices 2>&1)
DEVICE_COUNT=$(echo "$DEVICES" | grep -c "iPhone\|iPad")
if [ $DEVICE_COUNT -gt 0 ]; then
    echo "$DEVICES" | grep -E "iPhone|iPad|deviceType"
    print_status 0 "Found $DEVICE_COUNT device(s)"
else
    print_status 1 "No devices found"
fi
echo ""

# 6. iproxy
echo "🔌 iproxy"
if pgrep -x iproxy > /dev/null; then
    print_status 0 "iproxy is running"
    ps aux | grep iproxy | grep -v grep | head -1
else
    echo "⚠️  iproxy not running (normal when not connected)"
fi
echo ""

# 7. WDA endpoint (if iproxy running)
if pgrep -x iproxy > /dev/null; then
    echo "🌐 WebDriverAgent Endpoint"
    if curl -s http://localhost:8100/status > /dev/null 2>&1; then
        print_status 0 "WDA responding on port 8100"
        curl -s http://localhost:8100/status | python3 -m json.tool 2>/dev/null || curl -s http://localhost:8100/status
    else
        print_status 1 "WDA not responding"
    fi
    echo ""
fi

echo "╔════════════════════════════════════════╗"
echo "║   Health Check Complete                ║"
echo "╚════════════════════════════════════════╝"

Run it:

bash

chmod +x specchio-health-check.sh
./specchio-health-check.sh

Xcode Verification

Check Xcode Installation

bash

# Is Xcode installed?
ls -la /Applications/Xcode.app

# Xcode version
xcodebuild -version

# Xcode path
xcode-select -p

# Xcode location
xcode-select --print-path

Verify Xcode Components

bash

# List installed SDKs
xcodebuild -showsdks

# Check for iOS SDK specifically
xcodebuild -showsdks | grep iphoneos

# List all platforms
ls -la /Applications/Xcode.app/Contents/Developer/Platforms/

Check Xcode License

bash

# Check license status
xcodebuild -checkFirstLaunchStatus

# If needed, accept license
sudo xcodebuild -license accept

Verify Developer Tools

bash

# Check if Command Line Tools are installed
xcode-select --install

# Check git (comes with Xcode)
git --version

# Check clang
clang --version

Device Detection

List All iOS Devices

bash

# Modern method (macOS 14+)
xcrun devicectl list devices

# Legacy method (still works)
xcrun xctrace list devices

# Detailed device info
xcrun devicectl list devices | jq .

Check Specific Device

bash

# Get device UDID
xcrun devicectl list devices | grep -oE '[0-9a-f]{40}'

# Get device name
system_profiler SPUSBDataType | grep -A 10 iPhone

# Check device details
idevice_id -l # if libimobiledevice tools installed

Test Device Connection

bash

# Ping device (if WiFi debugging enabled)
# First get device IP from:
xcrun devicectl list devices
# Then ping:
ping <DEVICE_IP>

# Check if port 8100 is accessible (via iproxy)
nc -zv localhost 8100

Verify Device Trust

bash

# Check for trusted certificates on Mac
security find-trust | grep iPhone

# Check for developer certificate on device
# (Only visible in iOS Settings → General → VPN & Device Management)

WebDriverAgent Testing

Test WDA Connection

bash

# Check WDA status
curl http://localhost:8100/status

# With pretty formatting
curl http://localhost:8100/status | python3 -m json.tool

# Check WDA session
curl http://localhost:8100/session

Test Screenshot Endpoint

bash

# Get screenshot (saves current screen)
curl http://localhost:8100/screenshot --output test.png

# Check screenshot quality
file test.png
# Should show iPhone resolution like: 1179x2556

# Open screenshot
open test.png

# Measure screenshot performance
time curl http://localhost:8100/screenshot --output test.png

Test Input Endpoints

bash

# Test tap at center
curl -X POST http://localhost:8100/wda/tap/0 \
  -H "Content-Type: application/json" \
  -d '{"x": 0.5, "y": 0.5}'

# Test swipe up
curl -X POST http://localhost:8100/wda/swipe \
  -H "Content-Type: application/json" \
  -d '{"fromX": 0.5, "fromY": 0.8, "toX": 0.5, "toY": 0.2}'

# Test text input
curl -X POST http://localhost:8100/wda/keys \
  -H "Content-Type: application/json" \
  -d '{"value": ["Test"]}'

# Test home button
curl -X POST http://localhost:8100/wda/pressButton \
  -H "Content-Type: application/json" \
  -d '{"name": "home"}'

Test Accessibility Tree (Lite Mode)

bash

# Get accessibility tree
curl http://localhost:8100/source

# Save and format
curl http://localhost:8100/source > a11y_tree.xml
xmllint --format a11y_tree.xml | less

# Check tree size (smaller = faster for Lite mode)
wc -l a11y_tree.xml

Network Diagnostics

Check Network Configuration

bash

# Get Mac's IP address
ipconfig getifaddr en0

# Get subnet info
ifconfig en0 | grep netmask

# Get WiFi network name
networksetup -getairportnetwork en0

# Check network status
networksetup -getinfo "Wi-Fi"

Test Device Connectivity

bash

# Browse for iOS devices on network
dns-sd -B _apple-mobdev2._tcp local.

# Resolve specific device
dns-sd -L "iPhone Name" _apple-mobdev2._tcp local.

# Check if specific port is open
nc -zv <DEVICE_IP> 8100

Test Network Performance

bash

# Ping device (if available)
ping -c 10 <DEVICE_IP>

# Measure latency to WDA
time curl http://<DEVICE_IP>:8100/status

# Test screenshot speed over network
time curl http://<DEVICE_IP>:8100/screenshot --output wifi_test.png

Check Firewall Settings

bash

# Check firewall status
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Check if blocked
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

# Allow incoming connections if needed
# System Settings → Network → Firewall

Performance Testing

Measure Screenshot Performance

bash

# Download 10 screenshots and measure time
time for i in {1..10}; do
    curl -s http://localhost:8100/screenshot --output "screenshot_$i.png"
done

# Check file sizes
ls -lh screenshot_*.png

# Calculate FPS from timing
# If 10 screenshots took 5 seconds = 2 FPS
# If 10 screenshots took 2 seconds = 5 FPS

Test Different Display Modes

bash

# Test Screenshot mode
curl http://localhost:8100/screenshot --output screenshot_test.png

# Check file size (larger = more bandwidth)
du -h screenshot_test.png

# Test accessibility tree size
curl http://localhost:8100/source --output a11y_test.xml
du -h a11y_test.xml

# Compare sizes (a11y should be much smaller)

Monitor Resource Usage

bash

# Check Specchio CPU usage
top -l 1 | grep Specchio

# Check memory usage
ps aux | grep Specchio | awk '{print $6}'

# Check iproxy resources
ps aux | grep iproxy

# Continuous monitoring
top -o cpu -s 5 | grep -E "Specchio|iproxy"

Test Latency

bash

# Measure round-trip time
time curl http://localhost:8100/status > /dev/null

# Multiple measurements
for i in {1..10}; do
    { time curl -s http://localhost:8100/status > /dev/null; } 2>&1 | grep real
done

# Average the results for typical latency

Automated Test Suite

Complete Diagnostic Script

Save as specchio-full-diagnostic.sh:

bash

#!/bin/bash

OUTPUT_FILE="specchio-diagnostic-$(date +%Y%m%d-%H%M%S).log"

echo "Running Specchio diagnostics..." | tee $OUTPUT_FILE
echo "==================================" | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# System info
echo "SYSTEM INFORMATION" | tee -a $OUTPUT_FILE
echo "===================" | tee -a $OUTPUT_FILE
sw_vers | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE
xcodebuild -version | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# Disk space
echo "DISK SPACE" | tee -a $OUTPUT_FILE
echo "===========" | tee -a $OUTPUT_FILE
df -h / | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# Xcode check
echo "XCODE STATUS" | tee -a $OUTPUT_FILE
echo "============" | tee -a $OUTPUT_FILE
xcodebuild -checkFirstLaunchStatus | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# iOS SDK
echo "IOS SDK" | tee -a $OUTPUT_FILE
echo "=======" | tee -a $OUTPUT_FILE
xcodebuild -showsdks | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# Certificates
echo "CERTIFICATES" | tee -a $OUTPUT_FILE
echo "===========" | tee -a $OUTPUT_FILE
security find-identity -v -p codesigning 2>&1 | grep -i "apple development" | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# Devices
echo "CONNECTED DEVICES" | tee -a $OUTPUT_FILE
echo "=================" | tee -a $OUTPUT_FILE
xcrun devicectl list devices 2>&1 | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# iproxy
echo "IPROXY STATUS" | tee -a $OUTPUT_FILE
echo "=============" | tee -a $OUTPUT_FILE
ps aux | grep iproxy | grep -v grep | tee -a $OUTPUT_FILE
echo "" | tee -a $OUTPUT_FILE

# WDA status (if iproxy running)
if pgrep -x iproxy > /dev/null; then
    echo "WEBDRIVERAGENT STATUS" | tee -a $OUTPUT_FILE
echo "=====================" | tee -a $OUTPUT_FILE
    curl -s http://localhost:8100/status | tee -a $OUTPUT_FILE
    echo "" | tee -a $OUTPUT_FILE

    # Screenshot test
    echo "SCREENSHOT TEST" | tee -a $OUTPUT_FILE
echo "===============" | tee -a $OUTPUT_FILE
    echo "Downloading screenshot..." | tee -a $OUTPUT_FILE
    { time curl -s http://localhost:8100/screenshot --output diagnostic-screenshot.png; } 2>&1 | tee -a $OUTPUT_FILE
    file diagnostic-screenshot.png | tee -a $OUTPUT_FILE
    echo "" | tee -a $OUTPUT_FILE
fi

echo "==================================" | tee -a $OUTPUT_FILE
echo "Diagnostic complete: $OUTPUT_FILE" | tee -a $OUTPUT_FILE
echo "==================================" | tee -a $OUTPUT_FILE

Run it:

bash

chmod +x specchio-full-diagnostic.sh
./specchio-full-diagnostic.sh

This creates a timestamped log file you can share when reporting issues.

Quick Reference

Essential Commands

Purpose	Command
Check Xcode	`xcodebuild -version`
List devices	`xcrun devicectl list devices`
Check certificate	`security find-identity -v -p codesigning`
Test WDA	`curl http://localhost:8100/status`
Get screenshot	`curl http://localhost:8100/screenshot --output test.png`
Check iproxy	`ps aux \| grep iproxy`
Test network	`ping <DEVICE_IP>`

Log Locations

Component	Log Location
Specchio	View → Show Log in app
Xcode	`~/Library/Logs/DiagnosticReports/Xcode*.crash`
iOS Device	Xcode → Window → Devices and Simulators → View Device Logs
System	Console.app

For help interpreting results or fixing issues, see the Troubleshooting page.

Diagnostic Commands ​

Table of Contents ​

Quick Health Check ​

All-in-One Diagnostic Script ​

Xcode Verification ​

Check Xcode Installation ​

Verify Xcode Components ​

Check Xcode License ​

Verify Developer Tools ​

Device Detection ​

List All iOS Devices ​

Check Specific Device ​

Test Device Connection ​

Verify Device Trust ​

WebDriverAgent Testing ​

Test WDA Connection ​

Test Screenshot Endpoint ​

Test Input Endpoints ​

Test Accessibility Tree (Lite Mode) ​

Network Diagnostics ​

Check Network Configuration ​

Test Device Connectivity ​

Test Network Performance ​

Check Firewall Settings ​

Performance Testing ​

Measure Screenshot Performance ​

Test Different Display Modes ​

Monitor Resource Usage ​

Test Latency ​

Automated Test Suite ​

Complete Diagnostic Script ​

Quick Reference ​

Essential Commands ​

Log Locations ​

Diagnostic Commands

Table of Contents

Quick Health Check

All-in-One Diagnostic Script

Xcode Verification

Check Xcode Installation

Verify Xcode Components

Check Xcode License

Verify Developer Tools

Device Detection

List All iOS Devices

Check Specific Device

Test Device Connection

Verify Device Trust

WebDriverAgent Testing

Test WDA Connection

Test Screenshot Endpoint

Test Input Endpoints

Test Accessibility Tree (Lite Mode)

Network Diagnostics

Check Network Configuration

Test Device Connectivity

Test Network Performance

Check Firewall Settings

Performance Testing

Measure Screenshot Performance

Test Different Display Modes

Monitor Resource Usage

Test Latency

Automated Test Suite

Complete Diagnostic Script

Quick Reference

Essential Commands

Log Locations