{"id":2063,"date":"2026-08-18T09:00:00","date_gmt":"2026-08-18T14:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=2063"},"modified":"2026-03-07T03:50:31","modified_gmt":"2026-03-07T08:50:31","slug":"universal-links-xcode-configuration","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/universal-links-xcode-configuration\/","title":{"rendered":"Handling Universal Links in Xcode Previews and Tests"},"content":{"rendered":"\n

Universal Links routing logic can be complex: parsing URLs, extracting parameters, mapping paths to screens, and handling edge cases. Testing this logic in Xcode ensures that your deep links work before they reach production. You can unit test URL parsing and routing, UI test the full launch-from-URL flow, and use Xcode's debugging tools to inspect Universal Link behavior on devices.<\/p>\n\n\n\n

This article covers how to test Universal Links at each level, from unit tests to UI tests to on-device debugging.<\/p>\n\n\n\n

For Universal Links fundamentals, see universal links: everything you need to know<\/a>. For general testing approaches, see testing Universal Links<\/a>.<\/p>\n\n\n\n

Unit Testing URL Routing<\/h2>\n\n\n\n

Your URL routing logic should be a pure function: give it a URL, get back a route or destination. This makes it easy to unit test without any iOS infrastructure.<\/p>\n\n\n\n

import XCTest\n@testable import YourApp\n\nclass UniversalLinkRouterTests: XCTestCase {\n\n    let router = DeepLinkRouter()\n\n    func testProductURL() {\n        let url = URL(string: "https:\/\/example.com\/product\/abc123")!\n        let route = router.route(for: url)\n        XCTAssertEqual(route, .product(id: "abc123"))\n    }\n\n    func testCategoryURL() {\n        let url = URL(string: "https:\/\/example.com\/category\/shoes")!\n        let route = router.route(for: url)\n        XCTAssertEqual(route, .category(slug: "shoes"))\n    }\n\n    func testUnknownPath() {\n        let url = URL(string: "https:\/\/example.com\/unknown\/path")!\n        let route = router.route(for: url)\n        XCTAssertNil(route)\n    }\n\n    func testQueryParameters() {\n        let url = URL(string: "https:\/\/example.com\/search?q=red+shoes&page=2")!\n        let route = router.route(for: url)\n        XCTAssertEqual(route, .search(query: "red shoes", page: 2))\n    }\n\n    func testMalformedURL() {\n        let url = URL(string: "https:\/\/example.com\/product\/")!\n        let route = router.route(for: url)\n        XCTAssertNil(route, "Empty product ID should not route")\n    }\n}\n<\/code><\/pre>\n\n\n\n
Structuring Your Router for Testability<\/h3>\n\n\n\n
The key to testable Universal Links is separating URL parsing from navigation. Your router should return a value (an enum case, a struct, a route identifier), not directly perform navigation:<\/p>\n\n\n\n
enum DeepLinkDestination: Equatable {\n    case product(id: String)\n    case category(slug: String)\n    case search(query: String, page: Int)\n    case profile(username: String)\n    case home\n}\n\nstruct DeepLinkRouter {\n\n    func route(for url: URL) -> DeepLinkDestination? {\n        let path = url.pathComponents\n\n        guard path.count >= 2 else { return nil }\n\n        switch path[1] {\n        case "product":\n            guard path.count >= 3, !path[2].isEmpty else { return nil }\n            return .product(id: path[2])\n        case "category":\n            guard path.count >= 3 else { return nil }\n            return .category(slug: path[2])\n        case "search":\n            let components = URLComponents(url: url, resolvingAgainstBaseURL: false)\n            let query = components?.queryItems?.first(where: { $0.name == "q" })?.value ?? ""\n            let page = Int(components?.queryItems?.first(where: { $0.name == "page" })?.value ?? "1") ?? 1\n            return .search(query: query, page: page)\n        case "user":\n            guard path.count >= 3 else { return nil }\n            return .profile(username: path[2])\n        default:\n            return nil\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
This router is a pure function with no side effects, making it trivial to test with any URL you can construct.<\/p>\n\n\n\n
UI Testing Universal Links<\/h2>\n\n\n\n
Xcode UI tests can launch your app with a Universal Link URL using the XCUIApplication<\/code> launch arguments. This tests the full flow from URL to screen.<\/p>\n\n\n\n
import XCTest\n\nclass UniversalLinkUITests: XCTestCase {\n\n    func testProductDeepLink() {\n        let app = XCUIApplication()\n        app.launchEnvironment["TEST_DEEP_LINK"] = "https:\/\/example.com\/product\/abc123"\n        app.launch()\n\n        \/\/ Assert the product screen is visible\n        XCTAssertTrue(app.navigationBars["Product Details"].waitForExistence(timeout: 5))\n        XCTAssertTrue(app.staticTexts["abc123"].exists)\n    }\n\n    func testCategoryDeepLink() {\n        let app = XCUIApplication()\n        app.launchEnvironment["TEST_DEEP_LINK"] = "https:\/\/example.com\/category\/shoes"\n        app.launch()\n\n        XCTAssertTrue(app.navigationBars["Shoes"].waitForExistence(timeout: 5))\n    }\n}\n<\/code><\/pre>\n\n\n\n
In your app code, handle the test deep link during launch:<\/p>\n\n\n\n
func application(\n    _ application: UIApplication,\n    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?\n) -> Bool {\n\n    #if DEBUG\n    if let testURL = ProcessInfo.processInfo.environment["TEST_DEEP_LINK"],\n       let url = URL(string: testURL) {\n        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {\n            self.handleUniversalLink(url)\n        }\n    }\n    #endif\n\n    return true\n}\n<\/code><\/pre>\n\n\n\n
This approach simulates the deep link within your app's process. It does not test iOS's AASA validation or the system-level Universal Link dispatch, but it does test your app's URL handling end-to-end.<\/p>\n\n\n\n
Testing With xcrun and Simctl<\/h2>\n\n\n\n
For testing on the Simulator, you can open a Universal Link using the xcrun simctl<\/code> command:<\/p>\n\n\n\n
xcrun simctl openurl booted "https:\/\/example.com\/product\/abc123"\n<\/code><\/pre>\n\n\n\n
This sends the URL to the Simulator's frontmost app as if the user tapped a Universal Link. If your app is installed and the AASA file is configured, the app will open and receive the URL through the standard delegate methods.<\/p>\n\n\n\n
Limitations of Simulator Testing<\/h3>\n\n\n\n