---

name: deep-link-debugging description: Use when adding debug-only deep links for testing, enabling simulator navigation to specific screens, or integrating with automated testing workflows - enables closed-loop debugging without production deep link implementation skill_type: discipline version: 1.0.0 last_updated: 2025-12-08 apple_platforms: iOS 13+

MCP annotations (ignored by Claude Code)

mcp: category: debugging tags: [deep-linking, url-schemes, simulator, testing, debugging, navigation] related: [simulator-tester, xcode-debugging, swiftui-nav]

Deep Link Debugging

When to Use This Skill

Use when:

• Adding debug-only deep links for simulator testing
• Enabling automated navigation to specific screens for screenshot/testing
• Integrating with simulator-tester agent or /axiom:screenshot
• Need to navigate programmatically without production deep link implementation
• Testing navigation flows without manual tapping

Do NOT use for:

• Production deep linking (use swiftui-nav skill instead)
• Universal links or App Clips
• Complex routing architectures

Example Prompts

1. "Claude Code can't navigate to specific screens for testing"

→ Add debug-only URL scheme to enable xcrun simctl openurl navigation

2. "I want to take screenshots of different screens automatically"

→ Create debug deep links for each screen, callable from simulator

3. "Automated testing needs to set up specific app states"

→ Add debug links that navigate AND configure state

---

Red Flags — When You Need Debug Deep Links

If you're experiencing ANY of these, add debug deep links:

Testing friction:

• ❌ "I have to manually tap through 5 screens to test this feature"
• ❌ "Screenshot capture can't show the screen I need to debug"
• ❌ "Automated tests can't reach the error state without complex setup"

Debugging inefficiency:

• ❌ "I make a fix, rebuild, manually navigate, check — takes 3 minutes per iteration"
• ❌ "Can't visually verify fixes because Claude Code can't navigate there"

Solution: Add debug deep links that let you (and Claude Code) jump directly to any screen with any state configuration.

---

Implementation

Pattern 1: Basic Debug URL Scheme (SwiftUI)

Add a debug-only URL scheme that routes to screens.

import SwiftUI

struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                #if DEBUG
                .onOpenURL { url in
                    handleDebugURL(url)
                }
                #endif
        }
    }

    #if DEBUG
    private func handleDebugURL(_ url: URL) {
        guard url.scheme == "debug" else { return }

        // Route based on host
        switch url.host {
        case "settings":
            // Navigate to settings
            NotificationCenter.default.post(
                name: .navigateToSettings,
                object: nil
            )

        case "profile":
            // Navigate to profile
            let userID = url.queryItems?["id"] ?? "current"
            NotificationCenter.default.post(
                name: .navigateToProfile,
                object: userID
            )

        case "reset":
            // Reset app to initial state
            resetApp()

        default:
            print("⚠️ Unknown debug URL: \(url)")
        }
    }
    #endif
}

#if DEBUG
extension Notification.Name {
    static let navigateToSettings = Notification.Name("navigateToSettings")
    static let navigateToProfile = Notification.Name("navigateToProfile")
}

extension URL {
    var queryItems: [String: String]? {
        guard let components = URLComponents(url: self, resolvingAgainstBaseURL: false),
              let items = components.queryItems else {
            return nil
        }
        return Dictionary(uniqueKeysWithValues: items.map { ($0.name, $0.value ?? "") })
    }
}
#endif

Usage:

# From simulator
xcrun simctl openurl booted "debug://settings"
xcrun simctl openurl booted "debug://profile?id=123"
xcrun simctl openurl booted "debug://reset"

---

Pattern 2: NavigationPath Integration (iOS 16+)

Integrate debug deep links with NavigationStack for robust navigation.

import SwiftUI

@MainActor
class DebugRouter: ObservableObject {
    @Published var path = NavigationPath()

    #if DEBUG
    func handleDebugURL(_ url: URL) {
        guard url.scheme == "debug" else { return }

        switch url.host {
        case "settings":
            path.append(Destination.settings)

        case "recipe":
            if let id = url.queryItems?["id"], let recipeID = Int(id) {
                path.append(Destination.recipe(id: recipeID))
            }

        case "recipe-edit":
            if let id = url.queryItems?["id"], let recipeID = Int(id) {
                // Navigate to recipe, then to edit
                path.append(Destination.recipe(id: recipeID))
                path.append(Destination.recipeEdit(id: recipeID))
            }

        case "reset":
            path = NavigationPath() // Pop to root

        default:
            print("⚠️ Unknown debug URL: \(url)")
        }
    }
    #endif
}

struct ContentView: View {
    @StateObject private var router = DebugRouter()

    var body: some View {
        NavigationStack(path: $router.path) {
            HomeView()
                .navigationDestination(for: Destination.self) { destination in
                    destinationView(for: destination)
                }
        }
        #if DEBUG
        .onOpenURL { url in
            router.handleDebugURL(url)
        }
        #endif
    }

    @ViewBuilder
    private func destinationView(for destination: Destination) -> some View {
        switch destination {
        case .settings:
            SettingsView()
        case .recipe(let id):
            RecipeDetailView(recipeID: id)
        case .recipeEdit(let id):
            RecipeEditView(recipeID: id)
        }
    }
}

enum Destination: Hashable {
    case settings
    case recipe(id: Int)
    case recipeEdit(id: Int)
}

Usage:

# Navigate to settings
xcrun simctl openurl booted "debug://settings"

# Navigate to recipe #42
xcrun simctl openurl booted "debug://recipe?id=42"

# Navigate to recipe #42 edit screen
xcrun simctl openurl booted "debug://recipe-edit?id=42"

# Pop to root
xcrun simctl openurl booted "debug://reset"

---

Pattern 3: State Configuration Links

Debug links that both navigate AND configure state.

#if DEBUG
extension DebugRouter {
    func handleDebugURL(_ url: URL) {
        guard url.scheme == "debug" else { return }

        switch url.host {
        case "login":
            // Show login screen
            path.append(Destination.login)

        case "login-error":
            // Show login screen WITH error state
            path.append(Destination.login)
            // Trigger error state
            NotificationCenter.default.post(
                name: .showLoginError,
                object: "Invalid credentials"
            )

        case "recipe-empty":
            // Show recipe list in empty state
            UserDefaults.standard.set(true, forKey: "debug_emptyRecipeList")
            path.append(Destination.recipes)

        case "recipe-error":
            // Show recipe list with network error
            UserDefaults.standard.set(true, forKey: "debug_networkError")
            path.append(Destination.recipes)

        default:
            print("⚠️ Unknown debug URL: \(url)")
        }
    }
}
#endif

Usage:

# Test login error state
xcrun simctl openurl booted "debug://login-error"

# Test empty recipe list
xcrun simctl openurl booted "debug://recipe-empty"

# Test network error handling
xcrun simctl openurl booted "debug://recipe-error"

---

Pattern 4: Info.plist Configuration (DEBUG only)

Register the debug URL scheme ONLY in debug builds.

Step 1: Add scheme to Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>debug</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.example.debug</string>
    </dict>
</array>

Step 2: Strip from release builds

Add a Run Script phase to your target's Build Phases (runs BEFORE "Copy Bundle Resources"):

# Strip debug URL scheme from Release builds
if [ "${CONFIGURATION}" = "Release" ]; then
    echo "Removing debug URL scheme from Info.plist"

    /usr/libexec/PlistBuddy -c "Delete :CFBundleURLTypes:0" "${BUILT_PRODUCTS_DIR}/${INFOPLIST_PATH}" 2>/dev/null || true
fi

Alternative: Use separate Info.plist files for Debug vs Release configurations in Build Settings.

---

Integration with Simulator Testing

With /axiom:screenshot Command

# 1. Navigate to screen
xcrun simctl openurl booted "debug://settings"

# 2. Wait for navigation
sleep 1

# 3. Capture screenshot
/axiom:screenshot

With simulator-tester Agent

Simply tell the agent:

• "Navigate to Settings and take a screenshot"
• "Open the recipe editor and verify the layout"
• "Go to the error state and show me what it looks like"

The agent will use your debug deep links to navigate.

---

Mandatory First Steps

ALWAYS complete these steps before adding debug deep links:

Step 1: Define Navigation Needs

List all screens you need to reach for testing:

- Settings screen
- Profile screen (with specific user ID)
- Recipe detail (with specific recipe ID)
- Error states (login error, network error, etc.)
- Empty states (no recipes, no favorites)

Step 2: Choose URL Scheme Pattern

debug://screen-name              # Simple screen navigation
debug://screen-name?param=value  # Navigation with parameters
debug://state-name               # State configuration

Step 3: Add URL Handler

Use #if DEBUG to ensure code is stripped from release builds.

Step 4: Test Deep Links

# Boot simulator
xcrun simctl boot "iPhone 16 Pro"

# Launch app
xcrun simctl launch booted com.example.YourApp

# Test each deep link
xcrun simctl openurl booted "debug://settings"
xcrun simctl openurl booted "debug://profile?id=123"

---

Common Mistakes

❌ WRONG — Hardcoding navigation in URL handler

#if DEBUG
func handleDebugURL(_ url: URL) {
    if url.host == "settings" {
        // ❌ WRONG — Creates tight coupling
        self.showingSettings = true
    }
}
#endif

Problem: URL handler now owns navigation logic, duplicating coordinator/router patterns.

✅ RIGHT — Use existing navigation system:

#if DEBUG
func handleDebugURL(_ url: URL) {
    if url.host == "settings" {
        // Use existing NavigationPath
        path.append(Destination.settings)
    }
}
#endif

---

❌ WRONG — Leaving debug code in production

// ❌ WRONG — No #if DEBUG
func handleDebugURL(_ url: URL) {
    // This ships to users!
}

Problem: Debug endpoints exposed in production. Security risk.

✅ RIGHT — Wrap in #if DEBUG:

#if DEBUG
func handleDebugURL(_ url: URL) {
    // Stripped from release builds
}
#endif

---

❌ WRONG — Using query parameters without validation

#if DEBUG
case "profile":
    let userID = Int(url.queryItems?["id"] ?? "0")! // ❌ Force unwrap
    path.append(Destination.profile(id: userID))
#endif

Problem: Crashes if id is missing or invalid.

✅ RIGHT — Validate parameters:

#if DEBUG
case "profile":
    guard let idString = url.queryItems?["id"],
          let userID = Int(idString) else {
        print("⚠️ Invalid profile ID")
        return
    }
    path.append(Destination.profile(id: userID))
#endif

---

Testing Checklist

Before using debug deep links in automated workflows:

• URL handler wrapped in #if DEBUG
• All deep links tested manually in simulator
• Parameters validated (don't force unwrap)
• Deep links integrate with existing navigation (don't duplicate logic)
• URL scheme stripped from Release builds (script or separate Info.plist)
• Documented in README or comments for other developers
• Works with /axiom:screenshot command
• Works with simulator-tester agent

---

Real-World Example

Scenario: You're debugging a recipe app layout issue in the editor screen.

Before (manual testing):

1. Build app → 30 seconds
2. Launch simulator
3. Tap "Recipes" → wait for load
4. Scroll to recipe #42
5. Tap to open detail
6. Tap "Edit"
7. Check if layout is fixed
8. Make change, rebuild → repeat from step 1 Total: 2-3 minutes per iteration

After (with debug deep links):

1. Build app → 30 seconds
2. Run: xcrun simctl openurl booted "debug://recipe-edit?id=42"
3. Run: /axiom:screenshot
4. Claude analyzes screenshot and confirms layout fix
5. Make change if needed, rebuild → repeat from step 2 Total: 45 seconds per iteration

Time savings: 60-75% faster iteration with visual verification

---

Integration with Existing Navigation

For Apps Using NavigationStack

Add debug URL handler that appends to existing NavigationPath:

router.path.append(Destination.fromDebugURL(url))

For Apps Using Coordinator Pattern

Trigger coordinator methods from debug URL handler:

coordinator.navigate(to: .fromDebugURL(url))

For Apps Using Custom Routing

Integrate with your router's navigation API:

AppRouter.shared.push(Screen.fromDebugURL(url))

Key principle: Debug deep links should USE existing navigation, not replace it.

---

Advanced Patterns

Pattern 5: Parameterized State Setup

#if DEBUG
case "test-scenario":
    // Parse complex test scenario from URL
    // Example: debug://test-scenario?user=premium&recipes=empty&network=slow

    if let userType = url.queryItems?["user"] {
        configureUser(type: userType) // "premium", "free", "trial"
    }

    if let recipesState = url.queryItems?["recipes"] {
        configureRecipes(state: recipesState) // "empty", "full", "error"
    }

    if let networkState = url.queryItems?["network"] {
        configureNetwork(state: networkState) // "fast", "slow", "offline"
    }

    // Now navigate
    path.append(Destination.recipes)
#endif

Usage:

# Test premium user with empty recipe list
xcrun simctl openurl booted "debug://test-scenario?user=premium&recipes=empty"

# Test slow network with error handling
xcrun simctl openurl booted "debug://test-scenario?network=slow&recipes=error"

---

Pattern 6: Screenshot Automation Helper

Create a single URL that sets up AND captures state:

#if DEBUG
case "screenshot":
    // Parse screen and configuration
    guard let screen = url.queryItems?["screen"] else { return }

    // Configure state
    if let state = url.queryItems?["state"] {
        applyState(state)
    }

    // Navigate
    navigate(to: screen)

    // Post notification for external capture
    DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
        NotificationCenter.default.post(
            name: .readyForScreenshot,
            object: screen
        )
    }
#endif

Usage:

# Navigate to login screen with error state, wait, then screenshot
xcrun simctl openurl booted "debug://screenshot?screen=login&state=error"
sleep 2
xcrun simctl io booted screenshot login-error.png

---

Related Skills

• swiftui-nav — Production deep linking and NavigationStack patterns
• simulator-tester — Automated simulator testing using debug deep links
• xcode-debugging — Environment-first debugging workflows

---

Summary

Debug deep links enable:

• Closed-loop debugging with visual verification
• 60-75% faster iteration on visual fixes
• Automated testing without manual navigation
• Screenshot automation for any app state

Remember:

1. Wrap ALL debug code in #if DEBUG
2. Strip URL scheme from release builds
3. Integrate with existing navigation, don't duplicate
4. Validate all parameters (no force unwraps)
5. Document for team members