Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
9.5 KB
Raw Blame
// PatchComparisonTests.swift — Compare Swift patcher output against Python reference patches.
//
// Loads firmware binaries (pre-extracted raw payloads), runs Swift patchers,
// and verifies byte-exact match with the pre-generated Python reference JSON files.
//
// THESE ARE GATED ON A FIXTURE THAT CANNOT BE REGENERATED, and that is worth
// being plain about. `ipsws/patch_refactor_input/raw_payloads/` can be rebuilt
// from any IPSW — `vphone-cli fw im4p-extract` does it, and the payloads are
// whatever the firmware holds. `reference_patches/*.json` cannot: it is the
// output of the Python patchers this project replaced, they are deleted, and
// nothing here can produce those records again.
//
// So the suites below run when someone still has the JSON and skip when they
// do not, rather than erroring on a missing file and reading as a regression.
// What still guards the patchers without them is the frozen-digest work
// elsewhere in this directory — `FrozenReference` in DyldSharedCacheHypervisorVirtualMachinePatcherTests and
// the `matchesTheFrozenReference*` tests — which carry the reference values in
// the source instead of in a file nobody has.

@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

/// True when the unreproducible Python reference records are present.
private var hasReferencePatches: Bool {
    FileManager.default.fileExists(
        atPath: baseDir.appendingPathComponent("reference_patches").path,
    )
}

private let referenceMissing: Comment = """
ipsws/patch_refactor_input/reference_patches/ is absent. It is the output of \
the deleted Python patchers and cannot be regenerated; see this file's header.
"""

// MARK: - Reference patch JSON format

private struct ReferencePatch: Decodable {
    let file_offset: Int
    let patch_bytes: String
    let patch_size: Int
    let description: String
    let component: String
}

private struct TXMDevReference: Decodable {
    let base: [ReferencePatch]
    let dev: [ReferencePatch]
}

// MARK: - Test helpers

private let baseDir = URL(fileURLWithPath: #filePath)
    .deletingLastPathComponent()
    .deletingLastPathComponent()
    .deletingLastPathComponent()
    .deletingLastPathComponent()
    .deletingLastPathComponent()
    .appendingPathComponent("ipsws/patch_refactor_input")

private func loadRawPayload(_ name: String) throws -> Data {
    let url = baseDir.appendingPathComponent("raw_payloads/\(name)")
    return try Data(contentsOf: url)
}

private func loadReference(_ name: String) throws -> [ReferencePatch] {
    let url = baseDir.appendingPathComponent("reference_patches/\(name).json")
    let data = try Data(contentsOf: url)
    return try JSONDecoder().decode([ReferencePatch].self, from: data)
}

private func comparePatchRecords(
    swift swiftPatches: [PatchRecord],
    reference refPatches: [ReferencePatch],
    component: String,
) {
    // Sort both by file_offset for stable comparison
    let sortedSwift = swiftPatches.sorted { $0.fileOffset < $1.fileOffset }
    let sortedRef = refPatches.sorted { $0.file_offset < $1.file_offset }

    // Compare counts
    if swiftPatches.count != refPatches.count {
        print("  ✗ \(component): patch count mismatch — Swift=\(swiftPatches.count), Python=\(refPatches.count)")

        // Show what Swift found
        print("    Swift patches:")
        for p in sortedSwift {
            print("      0x\(String(format: "%06X", p.fileOffset)) \(p.patchedBytes.hex) [\(p.patchID)]")
        }
        print("    Python patches:")
        for p in sortedRef {
            print("      0x\(String(format: "%06X", p.file_offset)) \(p.patch_bytes) [\(p.description)]")
        }
    }

    #expect(swiftPatches.count == refPatches.count,
            "\(component): patch count mismatch — Swift=\(swiftPatches.count), Python=\(refPatches.count)")

    let count = min(sortedSwift.count, sortedRef.count)
    var mismatches = 0
    for i in 0 ..< count {
        let s = sortedSwift[i]
        let r = sortedRef[i]
        let swiftHex = s.patchedBytes.hex

        if s.fileOffset != r.file_offset || swiftHex != r.patch_bytes {
            mismatches += 1
            print("  ✗ \(component) patch \(i): Swift=0x\(String(format: "%X", s.fileOffset)):\(swiftHex) vs Python=0x\(String(format: "%X", r.file_offset)):\(r.patch_bytes) [\(r.description)]")
        }

        #expect(s.fileOffset == r.file_offset,
                "\(component) patch \(i): offset mismatch — Swift=0x\(String(format: "%X", s.fileOffset)), Python=0x\(String(format: "%X", r.file_offset)) [\(r.description)]")
        #expect(swiftHex == r.patch_bytes,
                "\(component) patch \(i) @ 0x\(String(format: "%X", s.fileOffset)): bytes mismatch — Swift=\(swiftHex), Python=\(r.patch_bytes) [\(r.description)]")
    }

    if mismatches == 0, swiftPatches.count == refPatches.count {
        print("  ✓ \(component): all \(count) patches match exactly")
    }
}

// MARK: - AVPBooter Tests

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct AVPBooterComparisonTests {
    @Test func `compare AVP booter`() throws {
        let data = try loadRawPayload("avpbooter.bin")
        let patcher = AVPBooterPatcher(data: data, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("avpbooter")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "avpbooter")
    }
}

// MARK: - iBoot Tests

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct IBSSComparisonTests {
    @Test func `compare IBSS`() throws {
        let data = try loadRawPayload("ibss.bin")
        let patcher = IBootPatcher(data: data, mode: .ibss, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("ibss")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "ibss")
    }
}

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct IBECComparisonTests {
    @Test func `compare IBEC`() throws {
        let data = try loadRawPayload("ibec.bin")
        let patcher = IBootPatcher(data: data, mode: .ibec, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("ibec")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "ibec")
    }
}

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct LLBComparisonTests {
    @Test func `compare LLB`() throws {
        let data = try loadRawPayload("llb.bin")
        let patcher = IBootPatcher(data: data, mode: .llb, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("llb")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "llb")
    }
}

// MARK: - TXM Tests

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct TXMComparisonTests {
    @Test func `compare TXM`() throws {
        let data = try loadRawPayload("txm.bin")
        let patcher = TXMPatcher(data: data, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("txm")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "txm")
    }
}

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct TXMDevComparisonTests {
    @Test func `compare TXM dev`() throws {
        let url = baseDir.appendingPathComponent("reference_patches/txm_dev.json")
        let jsonData = try Data(contentsOf: url)
        let ref = try JSONDecoder().decode(TXMDevReference.self, from: jsonData)

        let data = try loadRawPayload("txm.bin")
        let patcher = TXMDevPatcher(data: data, verbose: false)
        let swiftPatches = try patcher.findAll()

        // TXM dev includes base + dev patches
        let allRef = ref.base + ref.dev
        comparePatchRecords(swift: swiftPatches, reference: allRef, component: "txm_dev")
    }
}

// MARK: - Kernel Tests

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct KernelcacheComparisonTests {
    @Test func `compare kernelcache`() throws {
        let data = try loadRawPayload("kernelcache.bin")
        let patcher = KernelPatcher(data: data, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("kernelcache")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "kernelcache")
    }
}

// MARK: - JB Tests

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct IBSSCustomFirmwareComparisonTests {
    @Test func `compare IBSSCustomFirmware`() throws {
        let data = try loadRawPayload("ibss.bin")
        let patcher = IBootCustomFirmwarePatcher(data: data, mode: .ibss, verbose: false)
        // IBootCustomFirmwarePatcher only adds CFW-specific patches on top of base
        // We need to run findAll() first (base patches), then add the CFW patch
        patcher.patches = []
        patcher.patchSkipGenerateNonce()
        let refPatches = try loadReference("ibss_jb")
        comparePatchRecords(swift: patcher.patches, reference: refPatches, component: "ibss_jb")
    }
}

@Suite(.enabled(if: hasReferencePatches, referenceMissing))
struct KernelcacheCustomFirmwareComparisonTests {
    @Test func `compare kernelcache CFW`() throws {
        let data = try loadRawPayload("kernelcache.bin")
        let patcher = KernelCustomFirmwarePatcher(data: data, verbose: false)
        let swiftPatches = try patcher.findAll()
        let refPatches = try loadReference("kernelcache_jb")
        comparePatchRecords(swift: swiftPatches, reference: refPatches, component: "kernelcache_jb")
    }
}