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 axiom-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):

• Build app → 30 seconds

• Launch simulator

• Tap "Recipes" → wait for load

• Scroll to recipe #42

• Tap to open detail

• Tap "Edit"

• Check if layout is fixed

• Make change, rebuild → repeat from step 1 Total: 2-3 minutes per iteration

After (with debug deep links):

• Build app → 30 seconds

• Run: xcrun simctl openurl booted "debug://recipe-edit?id=42"

• Run: /axiom:screenshot

• Claude analyzes screenshot and confirms layout fix

• 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

• axiom-swiftui-nav — Production deep linking and NavigationStack patterns

• simulator-tester — Automated simulator testing using debug deep links

• axiom-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:

• Wrap ALL debug code in #if DEBUG

• Strip URL scheme from release builds

• Integrate with existing navigation, don't duplicate

• Validate all parameters (no force unwraps)

• Document for team members