Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
21.0 KB
Raw Blame
import Foundation
import Testing
@testable import VPhoneCoreKit

struct FirmwareCatalogReportTests {
    /// Experimental bring-ups created from IPSW URLs given by hand; the catalog
    /// offers no pairing for them, so the report leaves them out.
    private static let offCatalog: [VPhoneGuestDevice] = [.iPhone15_4, .iPhone15_2]

    @Test(arguments: ["HomeAccessory17,1", "HomeAccessory17,2"])
    func `HomeView 27_2 uses its full Pallas OTA and the HD restore base`(type: String) throws {
        let release = try #require(VPhoneFirmwareCatalog.otaRelease(for: type, build: "24V514"))
        #expect(release.version == "27.2" && release.size == 6_509_559_808)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: release.url, preferring: type) == release)
        #expect(release.key == "C6bVk4JwejgY6PfCJTX/nbrw/CtdphOG5EmsQMYe6As=")
        let pairings = VPhoneFirmwareCatalog.pairings(for: type, hostMacOS: 27)
        #expect(pairings.count == 1 && pairings[0].iosURL == release.url)
        #expect(pairings[0].cloudosURL == VPhoneFirmwareCatalog.cloud264)
        #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release)?.hasSuffix("AppleTV5,3_26.6_23L773_Restore.ipsw") == true)
        #expect(VPhoneFirmwareCatalog.pairings(for: type, hostMacOS: 26).isEmpty)
        let report = try #require(VPhoneFirmwareCatalog.report(hostMacOS: 27).devices.first { $0.productType == type })
        #expect(report.family == "homeView" && report.pairings[0].ios.build == "24V514")
    }

    @Test func `maps every pairing`() {
        let report = VPhoneFirmwareCatalog.report
        #expect(report.device == VPhoneFirmwareCatalog.device)
        #expect(report.pairings.count == VPhoneFirmwareCatalog.pairings.count)

        for (entry, pairing) in zip(report.pairings, VPhoneFirmwareCatalog.pairings) {
            #expect(entry.ios.name == pairing.iosName)
            #expect(entry.ios.url == pairing.iosURL)
            #expect(entry.recommendedCloudOS.name == pairing.cloudosName)
            #expect(entry.recommendedCloudOS.url == pairing.cloudosURL)
        }
    }

    @Test func `an OTA pairing names its build and the files it needs`() throws {
        let tv4K = try #require(VPhoneFirmwareCatalog.report(hostMacOS: 27).devices.first { $0.productType == "AppleTV14,1" })
        let ipsw = try #require(tv4K.pairings.first { $0.ios.name == "tvOS 26.6" })
        let ota = try #require(tv4K.pairings.first { $0.ios.name == "tvOS 27.0" })
        #expect(ipsw.ios.build == nil && ipsw.ios.files == nil)
        #expect(ota.ios.build == "24J361")
        #expect(ota.ios.files == ["ota/AppleTV14,1_27.0_24J361_OTA.aea", "AppleTV5,3_26.6_23L773_Restore.ipsw"])
        // An IPSW's entry encodes as before, so an older Launchpad reads it unchanged.
        let json = try #require(String(data: JSONEncoder().encode(ipsw), encoding: .utf8))
        #expect(!json.contains("build") && !json.contains("files"))
    }

    @Test func `iOS 26.4 to 26.6 can also run on their own cloudOS, on the research board`() throws {
        let report = VPhoneFirmwareCatalog.report
        let own = Dictionary(uniqueKeysWithValues: report.pairings.compactMap { entry in
            entry.matchingCloudOS.map { (entry.ios.name, $0.name) }
        })
        #expect(own["iOS 26.4.2"] == "cloudOS 26.4 (23E244)")
        #expect(own["iOS 26.5"] == "cloudOS 26.5 (23F75)")
        #expect(own["iOS 26.6.2"] == "cloudOS 26.6 (23G71)")
        #expect(own["iOS 26.3.1"] == nil && own["iOS 27.0"] == nil)
        // The recommendation stays the 26.4 beta, which needs neither root nor ipsw.
        let ios266 = try #require(report.pairings.first { $0.ios.name == "iOS 26.6" })
        #expect(ios266.recommendedCloudOS.name == "cloudOS 26.4")
        // Only the iPhone has run on the research board.
        let pad = try #require(report.devices.first { $0.family == "iPad" })
        #expect(pad.pairings.allSatisfy { $0.matchingCloudOS == nil })
        // An entry without one encodes as before, so an older Launchpad reads it unchanged.
        let ios27 = try #require(report.pairings.first { $0.ios.name == "iOS 27.0" })
        #expect(try !String(decoding: JSONEncoder().encode(ios27), as: UTF8.self).contains("matchingCloudOS"))
    }

    @Test func `lists every curated guest`() {
        let report = VPhoneFirmwareCatalog.report(hostMacOS: 27)
        #expect(report.devices.map(\.productType) == VPhoneGuestDevice.known.filter { !Self.offCatalog.contains($0) }.map(\.productType))
        #expect(report.devices.first?.pairings == report.pairings)
        #expect(Self.offCatalog.allSatisfy { VPhoneFirmwareCatalog.pairings(for: $0.productType, hostMacOS: 27).isEmpty })
        for device in report.devices.dropFirst() {
            #expect(device.family == VPhoneGuestDevice.named(device.productType)?.family.rawValue)
            #expect(!device.pairings.isEmpty)
            #expect(device.name == VPhoneGuestDevice.named(device.productType)?.productName)
        }
    }

    @Test func `the Apple TV 4K pairs each OTA with the Apple TV HD IPSW it is restored over`() throws {
        let pairings = VPhoneFirmwareCatalog.pairings(for: "AppleTV14,1", hostMacOS: 27)
        #expect(pairings.map(\.iosName) == ["tvOS 26.6", "tvOS 27.0"])
        let hd = try #require(VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3").first { $0.iosName == "tvOS 26.6" })
        for p in pairings {
            #expect(p.device == "AppleTV14,1")
            #expect(p.cloudosURL == hd.cloudosURL)
        }
        // 26.6 names the HD's IPSW of its own version; 27.0, which the HD
        // never got, names its OTA, and `fw prepare` finds the base from it.
        #expect(pairings[0].iosURL == hd.iosURL)
        let ota27 = try #require(VPhoneFirmwareCatalog.otaRelease(source: pairings[1].iosURL))
        #expect(ota27.version == "27.0" && ota27.build == "24J361" && ota27.baseVersion == "26.6")
        #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: ota27) == hd.iosURL)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: "/cache/ota/\(ota27.fileName)") == ota27)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: hd.iosURL) == nil)
        let ota = try #require(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV14,1", build: "23L773"))
        #expect(ota.version == "26.6")
        #expect(ota.url.hasPrefix("https://updates.cdn-apple.com/") && ota.url.hasSuffix(".aea"))
        #expect(ota.size == 4_764_729_344)
        #expect(Data(base64Encoded: try #require(ota.key))?.count == 32)
        #expect(ota.fileName == "AppleTV14,1_26.6_23L773_OTA.aea")
        #expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV14,1", build: "23L760") == nil)
        #expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV5,3", build: "23L773") == nil)
        // Every OTA has a base release to be restored over.
        for release in VPhoneFirmwareCatalog.otaReleases {
            let guest = try #require(VPhoneGuestDevice.named(release.productType))
            let base = guest.restoreBase ?? guest
            #expect(VPhoneFirmwareCatalog.pairings(for: base.productType).contains { $0.iosName.hasSuffix(" \(release.baseVersion)") })
            #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release) != nil)
            if let key = release.key { #expect(Data(base64Encoded: key)?.count == 32) }
        }
    }

    @Test func `the fourth generation Apple TV offers only its 27 point 2 OTA over the HD base`() throws {
        let release = try #require(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV18,1", build: "24K120"))
        #expect(release.version == "27.2" && release.baseVersion == "26.6")
        #expect(release.size == 5_234_491_392)
        #expect(release.key == "B/S/c74WZgPJLoJc7BDr+IxDjtQZ2H8gUwWp7kq9RpI=")
        #expect(release.url.hasSuffix("/c6553d1b2d6e080adcd92fd8281e36a47dc870e22fb9d0ac057b4489916bcd9c.aea"))
        #expect(release.fileName == "AppleTV18,1_27.2_24K120_OTA.aea")
        #expect(VPhoneFirmwareCatalog.otaRelease(source: "/cache/ota/\(release.fileName)") == release)
        let pairings = VPhoneFirmwareCatalog.pairings(for: "AppleTV18,1", hostMacOS: 27)
        #expect(pairings.map(\.iosName) == ["tvOS 27.2"])
        #expect(pairings.first?.iosURL == release.url)
        #expect(pairings.first?.cloudosURL == VPhoneFirmwareCatalog.cloud264)
        let base = try #require(VPhoneFirmwareCatalog.restoreBaseURL(for: release))
        #expect(base.hasSuffix("/AppleTV5,3_26.6_23L773_Restore.ipsw"))
        let device = try #require(VPhoneFirmwareCatalog.report(hostMacOS: 27).devices.first { $0.productType == "AppleTV18,1" })
        #expect(device.family == "appleTV" && device.name == "Apple TV 4K (4th generation)")
        #expect(device.pairings.count == 1 && device.pairings[0].ios.build == "24K120")
        #expect(device.pairings[0].ios.files == ["ota/\(release.fileName)", (base as NSString).lastPathComponent])
        #expect(VPhoneFirmwareCatalog.pairings(for: "AppleTV18,1", hostMacOS: 26).isEmpty)
        #expect(!VPhoneFirmwareCatalog.report(hostMacOS: 26).devices.contains { $0.productType == "AppleTV18,1" })
        #expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV18,1", build: "24J361") == nil)
    }

    @Test func `Apple TV pairings are tvOS releases on cloudOS 26.4`() throws {
        let pairings = VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3")
        #expect(pairings.map(\.iosName) == ["tvOS 26.6"])
        for p in pairings {
            #expect(p.device == "AppleTV5,3")
            #expect(p.iosURL.hasPrefix("https://updates.cdn-apple.com/"))
            #expect(p.iosURL.contains("/AppleTV5,3_"))
            #expect(p.iosURL.hasSuffix("_Restore.ipsw"))
            #expect(p.cloudosName == "cloudOS 26.4")
            #expect(p.cloudosURL == VPhoneFirmwareCatalog.cloud264)
        }
        let tv = try #require(VPhoneFirmwareCatalog.report.devices.first { $0.productType == "AppleTV5,3" })
        #expect(tv.family == "appleTV")
        #expect(tv.name == "Apple TV HD")
    }

    @Test func `HomePod mini pairs its native 27 IPSW with cloudOS without an OTA base`() throws {
        let pairings = VPhoneFirmwareCatalog.pairings(for: "AudioAccessory5,1", hostMacOS: 27)
        #expect(pairings.map(\.iosName) == ["HomePod Software 26.5", "HomePod Software 27.0", "HomePod Software 27.2"])
        let pairing = pairings[1]
        #expect(pairing.device == "AudioAccessory5,1")
        #expect(pairing.iosName == "HomePod Software 27.0")
        #expect(pairing.iosURL == "https://updates.cdn-apple.com/2026SFallFCS/a595a3b2-2c42-470a-9417-a705aaafa05c/AudioAccessory5,1_27.0_24J361_Restore.ipsw")
        #expect(pairing.cloudosName == "cloudOS 26.4")
        #expect(pairing.cloudosURL == VPhoneFirmwareCatalog.cloud264)
        #expect(VPhoneGuestDevice.audioAccessory5_1.restoreBase == nil)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: pairing.iosURL) == nil)
        #expect(VPhoneFirmwareCatalog.otaRelease(for: "AudioAccessory5,1", build: "24J361") == nil)
        #expect(VPhoneFirmwareCatalog.pairings(for: "AudioAccessory1,1").isEmpty)

        let device = try #require(VPhoneFirmwareCatalog.report.devices.first { $0.productType == "AudioAccessory5,1" })
        #expect(device.family == "homePod" && device.name == "HomePod mini")
        let entry = device.pairings[1]
        #expect(entry.ios.name == pairing.iosName && entry.ios.url == pairing.iosURL)
        #expect(entry.ios.build == nil && entry.ios.files == nil)
        #expect(entry.recommendedCloudOS.url == VPhoneFirmwareCatalog.cloud264)
    }

    @Test func `HomePod mini 26 point 5 pairs with the research board cloudOS its kernelcache recipe covers`() throws {
        let pairing = try #require(VPhoneFirmwareCatalog.pairings(for: "AudioAccessory5,1").first)
        #expect(pairing.iosName == "HomePod Software 26.5")
        #expect(pairing.iosURL.hasSuffix("/AudioAccessory5,1_26.5_23L471_Restore.ipsw"))
        #expect(pairing.cloudosName == "cloudOS 26.5 (23F75)")
        #expect(pairing.cloudosURL == VPhoneFirmwareCatalog.researchBoardCloudOS(forVersion: "26.5")?.url)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: pairing.iosURL) == nil)
    }

    @Test func `HomePod 27 point 2 takes its full ZIP OTA over its own 27 IPSW`() throws {
        let release = try #require(VPhoneFirmwareCatalog.otaRelease(for: "AudioAccessory5,1", build: "24K120"))
        #expect(release.version == "27.2" && release.baseVersion == "27.0")
        #expect(release.key == nil && release.size == 3_051_441_612)
        #expect(release.fileName == "AudioAccessory5,1_27.2_24K120_OTA.zip")
        let pairings = VPhoneFirmwareCatalog.pairings(for: release.productType, hostMacOS: 27)
        let base = try #require(pairings.first { $0.iosName == "HomePod Software 27.0" })
        let ota = try #require(pairings.first { $0.iosName == "HomePod Software 27.2" })
        #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release) == base.iosURL)
        #expect(ota.iosURL == release.url && ota.cloudosURL == VPhoneFirmwareCatalog.cloud264)
        #expect(VPhoneFirmwareCatalog.otaRelease(source: "/cache/ota/\(release.fileName)") == release)
        let device = try #require(VPhoneFirmwareCatalog.report(hostMacOS: 27).devices.first { $0.productType == release.productType })
        let entry = try #require(device.pairings.first { $0.ios.url == release.url })
        #expect(entry.ios.build == "24K120")
        #expect(entry.ios.files == ["ota/\(release.fileName)", (base.iosURL as NSString).lastPathComponent])
    }

    @Test func `a Mac before macOS 27 is offered no OTA it cannot unpack`() throws {
        // tvOS 27.0 and HomePod Software 27.2 compress their chunks with LZRAVEN.
        let lzraven = VPhoneFirmwareCatalog.otaReleases.filter { $0.minimumHostMacOS == 27 }
        #expect(Set(lzraven.map(\.build)) == ["24J361", "24K120", "24V514"])
        // Every 27-series OTA is LZRAVEN so far: a new one must say so, or an
        // older Mac would be offered it and fail only after its downloads.
        for release in VPhoneFirmwareCatalog.otaReleases where Int(release.version.split(separator: ".")[0]) ?? 0 >= 27 {
            #expect(release.minimumHostMacOS == VPhoneOTARelease.lzravenMinimumMacOS, "\(release.productType) \(release.version)")
        }
        for release in lzraven {
            #expect(!release.unpacks(onMacOS: 26) && release.unpacks(onMacOS: 27))
        }
        #expect(VPhoneFirmwareCatalog.pairings(for: "AppleTV14,1", hostMacOS: 26).map(\.iosName) == ["tvOS 26.6"])
        #expect(VPhoneFirmwareCatalog.pairings(for: "AudioAccessory5,1", hostMacOS: 26).map(\.iosName) == ["HomePod Software 26.5", "HomePod Software 27.0"])
        let report = VPhoneFirmwareCatalog.report(hostMacOS: 26)
        let tv4K = try #require(report.devices.first { $0.productType == "AppleTV14,1" })
        #expect(tv4K.pairings.map(\.ios.name) == ["tvOS 26.6"])
        // Nothing else depends on the host.
        #expect(VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3", hostMacOS: 26) == VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3", hostMacOS: 27))
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPhone17,3", hostMacOS: 26) == VPhoneFirmwareCatalog.pairings)
    }

    @Test func `i pad pairings come from an IPSW that covers the device`() {
        for guest in VPhoneGuestDevice.known where guest.isPad {
            let pairings = VPhoneFirmwareCatalog.pairings(for: guest.productType)
            #expect(pairings.map(\.iosName).first == "iPadOS 26.0" || guest.productType.hasPrefix("iPad17,"))
            #expect(pairings.map(\.iosName).last == "iPadOS 27.0.1")
            for p in pairings {
                #expect(p.device == guest.productType)
                #expect(p.iosURL.hasPrefix("https://updates.cdn-apple.com/"))
                #expect(p.iosURL.hasSuffix("_Restore.ipsw"))
                #expect(p.cloudosURL.contains("/private-cloud-compute/"))
                // The iPad Pro (M4) IPSWs are named iPad_Pro_M4_…; the rest name their models.
                let name = (p.iosURL as NSString).lastPathComponent
                #expect(name.hasPrefix("iPad_Pro_M4_") || name.split(separator: "_")[0].split(separator: ",").count >= 2)
                #expect(name.contains("_\(p.iosName.dropFirst("iPadOS ".count))_"))
            }
        }
    }

    @Test func `other i phones have pairings of their own`() {
        for guest in VPhoneGuestDevice.known where guest.family == .iPhone && guest.presentsBoard && guest != .iPhone17_3 && !Self.offCatalog.contains(guest) {
            let pairings = VPhoneFirmwareCatalog.pairings(for: guest.productType)
            let firstRelease = switch guest.productType {
            case "iPhone18,5": "iOS 26.3.1"
            case "iPhone19,2": "iOS 27.0.1"
            case "iPhone19,4": "iOS 27.1"
            default: "iOS 26.0"
            }
            #expect(pairings.map(\.iosName).first == firstRelease)
            #expect(pairings.map(\.iosName).last == (guest.productType == "iPhone19,4" ? "iOS 27.2" : "iOS 27.0.1"))
            for p in pairings {
                #expect(p.device == guest.productType)
                #expect(p.iosURL.hasPrefix("https://updates.cdn-apple.com/"))
                let name = (p.iosURL as NSString).lastPathComponent
                #expect(name.hasPrefix("\(guest.productType)_\(p.iosName.dropFirst("iOS ".count))_"))
                #expect(name.hasSuffix("_Restore.ipsw"))
                #expect(p.cloudosURL == VPhoneFirmwareCatalog.recommendedCloudOS(forVersion: String(p.iosName.dropFirst("iOS ".count))).url)
            }
        }
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPhone18,1") != VPhoneFirmwareCatalog.pairings)
    }

    @Test func `an i phone XS max pairs each iOS 18 release with its own research board cloud OS, linked kernel-first`() {
        let pairings = VPhoneFirmwareCatalog.pairings(for: "iPhone11,6")
        #expect(pairings.map(\.iosName) == ["iOS 18.1", "iOS 18.2.1", "iOS 18.3.1", "iOS 18.5", "iOS 18.6", "iOS 18.7", "iOS 18.7.2"])
        for p in pairings {
            let version = p.iosName.dropFirst("iOS ".count)
            #expect(p.device == "iPhone11,6")
            #expect((p.iosURL as NSString).lastPathComponent.hasPrefix("iPhone11,2,iPhone11,4,iPhone11,6_\(version)_"))
            #expect(p.cloudosName.hasPrefix("cloudOS \(version) ("))
            #expect(p.cloudosURL.contains("/private-cloud-compute/"))
        }
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPhone11,4") == pairings)
        let devices = VPhoneFirmwareCatalog.report.devices
        #expect(devices.first { $0.productType == "iPhone11,6" }?.kernelcacheLayout == "kernel-first")
        #expect(devices.filter { $0.kernelcacheLayout != nil }.map(\.productType) == ["iPhone11,6"])
    }

    @Test func `cellular i pad gets its wi fi model's pairings`() {
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPad17,4") == VPhoneFirmwareCatalog.pairings(for: "iPad17,3"))
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPad17,3").first?.device == "iPad17,3")
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPad15,8").isEmpty)
        #expect(VPhoneFirmwareCatalog.pairings(for: "iPhone17,3") == VPhoneFirmwareCatalog.pairings)
    }

    @Test func `i pad cloud OS follows the i phone pairing of the same release`() {
        let iPhone = Dictionary(
            VPhoneFirmwareCatalog.pairings.map { ($0.iosName.replacingOccurrences(of: "iOS ", with: ""), $0.cloudosURL) },
            uniquingKeysWith: { first, _ in first },
        )
        for p in VPhoneFirmwareCatalog.pairings(for: "iPad16,1") {
            let version = p.iosName.replacingOccurrences(of: "iPadOS ", with: "")
            #expect(iPhone[version] == p.cloudosURL, "\(version)")
        }
    }

    @Test func `a resolved release gets its pairing's cloud OS, else its version's`() {
        for p in VPhoneFirmwareCatalog.pairings {
            let version = String(p.iosName.dropFirst("iOS ".count))
            #expect(VPhoneFirmwareCatalog.recommendedCloudOS(forDevice: "iPhone17,3", version: version, url: p.iosURL).url == p.cloudosURL)
        }
        // A curated pairing wins over the version rule, by URL or by name.
        #expect(VPhoneFirmwareCatalog.recommendedCloudOS(forDevice: "iPhone17,3", version: "18.6.2", url: "").url == VPhoneFirmwareCatalog.cloud261)
        #expect(VPhoneFirmwareCatalog.recommendedCloudOS(forDevice: "iPhone17,3", version: "26.2.9", url: "").url == VPhoneFirmwareCatalog.cloud262)
        #expect(VPhoneFirmwareCatalog.recommendedCloudOS(forDevice: "AppleTV5,3", version: "26.1", url: "").url == VPhoneFirmwareCatalog.cloud264)
    }

    @Test func `an iOS 18 release takes the GPU driver of its own release's cloudOS`() {
        #expect(VPhoneFirmwareCatalog.iOS18CloudOS(forVersion: "18.6.2")?.name == "cloudOS 18.6 (22G86)")
        #expect(VPhoneFirmwareCatalog.iOS18CloudOS(forVersion: "18.6")?.name == "cloudOS 18.6 (22G86)")
        #expect(VPhoneFirmwareCatalog.iOS18CloudOS(forVersion: "18.7.2")?.name.hasPrefix("cloudOS 18.7") == true)
        #expect(VPhoneFirmwareCatalog.iOS18CloudOS(forVersion: "18.4") == nil)
        #expect(VPhoneFirmwareCatalog.iOS18CloudOS(forVersion: "26.1") == nil)
    }

    @Test func `round trips JSON`() throws {
        let report = VPhoneFirmwareCatalog.report
        let back = try JSONDecoder().decode(VPhoneFirmwareCatalogReport.self, from: JSONEncoder().encode(report))
        #expect(back == report)
    }
}