Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
37.5 KB
Raw Blame
// Equivalence tests for the Swift port of the two Python heredocs that used to
// live inside scripts/fw_prepare.sh (`list_firmwares`,
// `resolve_selector_from_downloads`).
//
// The golden strings below are not hand-written. They are the bytes the Python
// produced when the two heredocs were lifted out of fw_prepare.sh verbatim
// (`diff <(sed -n '167,246p' scripts/fw_prepare.sh) ref_list_firmwares.py`
// reports no difference) and run under .venv/bin/python3 over the same fixture
// this file freezes:
//
//   DOWNLOADABLE_IPSW_URLS="$(cat fixture_urls.txt)" \
//     .venv/bin/python3 ref_list_firmwares.py iPhone17,3 fixture_readme.md
//
// Colour was compared in three conditions, each running both implementations
// through the identical wrapper: a pipe, a real pty via script(1), and NO_COLOR
// set. Those runs also covered the repository's compatibility guide against a live
// `ipsw download ipsw --device iPhone17,3 --urls` capture.
//
// Trailing spaces are written as `\u{20}` on purpose: the Python padded the
// status column to 11 *inside* the colour escape, so those spaces are real
// output bytes, and a literal trailing space is the first thing an editor or a
// formatter silently eats.
//
// One deliberate divergence, and the only one found: `version_key` built a
// tuple of mixed ints and strs, so a list holding both `27.0` and `27.beta`
// made CPython raise
// `TypeError: '<' not supported between instances of 'str' and 'int'`
// and exit 1 mid-listing. Nothing Apple serves produces that. The port orders
// numbers before text instead of crashing; `nonNumericComponentsStillOrder`
// below pins that choice down.

import Foundation
import Testing
@testable import VPhoneCoreKit

// MARK: - Frozen fixture

private enum Fixture {
    /// A verbatim slice of the real README's table, plus two decoys: a
    /// `17,3_…` cell before the section and another after it, neither of which
    /// may count, and a `16,1_…` row for a different device.
    static let readme = """
    ## Prerequisites

    Some prose with a `17,3_99.9_99Z99` cell that must NOT count, because it is
    outside the section.

    ## Tested Environments

    | Host            | iPhone                | CloudOS         |
    | --------------- | --------------------- | --------------- |
    | Mac16,11 27.0b2 | `17,3_18.6.2_22G100`  | `26.1-23B85`    |
    | Mac16,8 26.5.1  | `17,3_26.0_23A341`    | `26.1-23B85`    |
    | Mac16,12 26.3   | `17,3_26.3_23D127`    | `26.3-23D128`   |
    | Mac16,12 26.3   | `17,3_26.3.1_23D8133` | `26.3-23D128`   |
    | Mac16,11 26.2   | `17,3_26.4_23E246`    | `26.4-23E5207q` |
    | Mac16,6 26.4.1  | `17,3_27.0_24A5390f`  | `26.4-23E5207q` |
    | Mac16,6 26.6.1  | `17,3_27.0_24A435`    | `26.4-23E5207q` |
    | Mac16,3 26.0    | `16,1_26.1_23B85`     | `26.1-23B85`    |

    ## FAQ

    A later section with `17,3_88.8_88Z88`, which must NOT count either.
    """

    /// Real Apple restore URLs, plus one exact duplicate and four lines that
    /// look close enough to matter: another device, an extra `_Custom`
    /// segment, and a log line with no leading slash.
    static let urls = """
    https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw
    https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
    https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-57108/5E816D0E-89BB-4B95-8825-6A3EDF22E509/iPhone17,3_27.0_24A5390f_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringSeed/2d03d580-843b-4b2a-b09d-976b31c10744/iPhone17,3_27.0_24A5430a_Restore.ipsw
    https://updates.cdn-apple.com/2026FallFCS/2d0cd01d-b4f9-4a20-a1e8-f3be54570da7/iPhone17,3_27.0_24A435_Restore.ipsw
    https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPad16,3_26.1_23B85_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Custom_Restore.ipsw
    · Downloading iPhone17,3_26.1_23B85_Restore.ipsw
    """

    static let d = "iPhone17,3"
    static let url263 = "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw"

    static func lines(_ lines: [String]) -> String {
        lines.map { $0 + "\n" }.joined()
    }

    static let plain = VPhoneStatusStyle(isColored: false)
    static let colored = VPhoneStatusStyle(isColored: true)

    /// Writes `readme` to a scratch file, because the command-line half takes a
    /// path (that is what the shell hands it).
    static func withReadmeFile<T>(_ body: (String) throws -> T) rethrows -> T {
        let url = URL(fileURLWithPath: NSTemporaryDirectory())
            .appendingPathComponent("vphone-fwmatrix-\(UUID().uuidString).md")
        try? readme.write(to: url, atomically: true, encoding: .utf8)
        defer { try? FileManager.default.removeItem(at: url) }
        return try body(url.path)
    }
}

// MARK: - Goldens

private enum Golden {
    static let listPlain = Fixture.lines([
        "Available downloadable IPSWs for iPhone17,3:",
        "",
        "Status: Supported   Not Tested  Unsupported",
        "",
        "VERSION      BUILD      STATUS",
        "27.0         24A5430a   Not Tested\u{20}",
        "27.0         24A5390f   Supported\u{20}\u{20}",
        "27.0         24A435     Supported\u{20}\u{20}",
        "26.4.1       23E254     Not Tested\u{20}",
        "26.4         23E246     Supported\u{20}\u{20}",
        "26.3.1       23D8133    Supported\u{20}\u{20}",
        "26.3         23D127     Supported\u{20}\u{20}",
        "26.0         23A341     Supported\u{20}\u{20}",
        "18.6.2       22G100     Supported\u{20}\u{20}",
    ])

    static let listColored = Fixture.lines([
        "Available downloadable IPSWs for iPhone17,3:",
        "",
        "Status: \u{1B}[32mSupported  \u{1B}[0m \u{1B}[33mNot Tested \u{1B}[0m \u{1B}[31mUnsupported\u{1B}[0m",
        "",
        "VERSION      BUILD      STATUS",
        "27.0         24A5430a   \u{1B}[33mNot Tested \u{1B}[0m",
        "27.0         24A5390f   \u{1B}[32mSupported  \u{1B}[0m",
        "27.0         24A435     \u{1B}[32mSupported  \u{1B}[0m",
        "26.4.1       23E254     \u{1B}[33mNot Tested \u{1B}[0m",
        "26.4         23E246     \u{1B}[32mSupported  \u{1B}[0m",
        "26.3.1       23D8133    \u{1B}[32mSupported  \u{1B}[0m",
        "26.3         23D127     \u{1B}[32mSupported  \u{1B}[0m",
        "26.0         23A341     \u{1B}[32mSupported  \u{1B}[0m",
        "18.6.2       22G100     \u{1B}[32mSupported  \u{1B}[0m",
    ])

    /// The selector's status column is *not* padded — a real asymmetry between
    /// the two heredocs that the port has to keep.
    static let ambiguousColored = Fixture.lines([
        "Version 27.0 is ambiguous for iPhone17,3; specify one of these builds:",
        "BUILD      STATUS",
        "24A5430a   \u{1B}[33mNot Tested\u{1B}[0m",
        "24A5390f   \u{1B}[32mSupported\u{1B}[0m",
        "24A435     \u{1B}[32mSupported\u{1B}[0m",
    ])

    static let ambiguousPlain = Fixture.lines([
        "Version 27.0 is ambiguous for iPhone17,3; specify one of these builds:",
        "BUILD      STATUS",
        "24A5430a   Not Tested",
        "24A5390f   Supported",
        "24A435     Supported",
    ])

    static let hit = "26.3\t23D127\t\(Fixture.url263)\tSupported\n"
}

// MARK: - Byte-for-byte equivalence with the Python

struct FirmwareMatrixGoldenTests {
    @Test func `listing matches python plain`() {
        let out = VPhoneFirmwareMatrix.listing(
            device: Fixture.d, readme: Fixture.readme,
            downloadURLs: Fixture.urls, style: Fixture.plain,
        )
        #expect(out == .matrix(Golden.listPlain))
    }

    @Test func `listing matches python colored`() {
        let out = VPhoneFirmwareMatrix.listing(
            device: Fixture.d, readme: Fixture.readme,
            downloadURLs: Fixture.urls, style: Fixture.colored,
        )
        #expect(out == .matrix(Golden.listColored))
    }

    @Test func `ambiguous version matches python`() {
        for (style, golden) in [
            (Fixture.plain, Golden.ambiguousPlain),
            (Fixture.colored, Golden.ambiguousColored),
        ] {
            let out = VPhoneFirmwareMatrix.selection(
                device: Fixture.d, version: "27.0", build: "",
                readme: Fixture.readme, downloadURLs: Fixture.urls, style: style,
            )
            #expect(out == .ambiguous(golden))
        }
    }

    @Test func `resolved selector matches python`() {
        let out = VPhoneFirmwareMatrix.selection(
            device: Fixture.d, version: "26.3", build: "",
            readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.colored,
        )
        guard case let .selected(release, support) = out else {
            Issue.record("expected a selection, got \(out)")
            return
        }
        // The resolved line is plain even under colour — the shell reads it
        // back through `IFS=$'\t' read`, and an escape in field 4 would end up
        // in the "Status:" line it echoes.
        #expect(out.resolvedLine == Golden.hit)
        #expect(release.build == "23D127")
        #expect(support == .supported)
        // Only a hit has a line; the failure cases have nothing to hand back.
        #expect(VPhoneFirmwareMatrix.selection(
            device: Fixture.d, version: "99.9", build: "",
            readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.plain,
        ).resolvedLine == nil)
    }

    @Test(arguments: [
        ("99.9", "", "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n"),
        ("", "99Z99", "Unsupported: no downloadable IPSW matched device=iPhone17,3 build=99Z99\n"),
        ("99.9", "99Z99", "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9 build=99Z99\n"),
    ])
    func `miss matches python`(version: String, build: String, expected: String) {
        let out = VPhoneFirmwareMatrix.selection(
            device: Fixture.d, version: version, build: build,
            readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.plain,
        )
        #expect(out == .unmatched(expected))
        let colored = VPhoneFirmwareMatrix.selection(
            device: Fixture.d, version: version, build: build,
            readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.colored,
        )
        #expect(colored == .unmatched("\u{1B}[31mUnsupported\u{1B}[0m" + expected.dropFirst("Unsupported".count)))
    }

    @Test func `empty download list is an error`() {
        let out = VPhoneFirmwareMatrix.listing(
            device: "iPhone99,9", readme: Fixture.readme,
            downloadURLs: Fixture.urls, style: Fixture.colored,
        )
        // Plain even in colour, exactly as the Python printed it.
        #expect(out == .nothingDownloadable("No downloadable IPSWs found for iPhone99,9\n"))
    }
}

// MARK: - Parsing

struct FirmwareMatrixParsingTests {
    @Test func `reads only the tested environments section and only this device`() {
        let tested = VPhoneFirmwareMatrix.testedBuilds(readme: Fixture.readme, device: Fixture.d)
        #expect(tested.count == 7)
        #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.3.1", build: "23D8133")))
        // Before the heading.
        #expect(!tested.contains(VPhoneFirmwareBuildID(version: "99.9", build: "99Z99")))
        // After the next `## ` heading.
        #expect(!tested.contains(VPhoneFirmwareBuildID(version: "88.8", build: "88Z88")))
        // A different device's row inside the section.
        #expect(!tested.contains(VPhoneFirmwareBuildID(version: "26.1", build: "23B85")))
    }

    @Test func `a missing readme means nothing is tested`() {
        #expect(VPhoneFirmwareMatrix.testedBuilds(readme: nil, device: Fixture.d).isEmpty)
        let out = VPhoneFirmwareMatrix.listing(
            device: Fixture.d, readme: nil,
            downloadURLs: Fixture.urls, style: Fixture.plain,
        )
        guard case let .matrix(text) = out else {
            Issue.record("expected a matrix")
            return
        }
        #expect(!text.contains("Supported\u{20}\u{20}\n"))
        #expect(text.components(separatedBy: "Not Tested").count == 1 + 9 + 1)
    }

    @Test func `rejects lookalike UR ls`() {
        let found = VPhoneFirmwareMatrix.releases(downloadURLs: Fixture.urls, device: Fixture.d)
        // 9 real lines, 1 exact duplicate dropped, 3 lookalikes rejected.
        #expect(found.count == 9)
        #expect(!found.contains { $0.url.contains("iPad16,3") })
        #expect(!found.contains { $0.url.contains("_Custom_") })
        #expect(!found.contains { $0.build == "23B85" })
    }

    @Test func `tolerates surrounding whitespace and blank lines`() {
        let urls = "\n   \(Fixture.url263)   \n\n"
        let found = VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: Fixture.d)
        #expect(found.count == 1)
        // The URL is stored stripped, so the shell gets something it can fetch.
        #expect(found.first?.url == Fixture.url263)
    }

    @Test func `parses the repository compatibility guide`() throws {
        let tested = try VPhoneFirmwareMatrix.testedBuilds(
            readme: RealData.repositoryCompatibilityGuide(),
            device: Fixture.d,
        )
        #expect(tested.count == 5)
        #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.6.2", build: "23G90")))
        #expect(tested.contains(VPhoneFirmwareBuildID(version: "27.0", build: "24A435")))
        // The research board rows: each release on its own cloudOS.
        for (version, build) in [("26.4", "23E246"), ("26.5", "23F77"), ("26.6", "23G71")] {
            #expect(tested.contains(VPhoneFirmwareBuildID(version: version, build: build)))
        }
        #expect(tested.allSatisfy { !$0.version.isEmpty && !$0.build.isEmpty })
        #expect(tested.allSatisfy { !$0.version.contains("`") && !$0.build.contains("`") })
    }
}

// MARK: - Real data

/// The repository's compatibility table joined against a real `ipsw download ipsw
/// --device iPhone17,3 --urls` capture — the two inputs the shell actually fed
/// the Python, rather than anything shaped to suit the parser.
///
/// The guide is read live, so these assert invariants rather than a golden: a
/// row added to the table must not turn the suite red for the agent who added
/// it. The cross-check is against a second parser written here on purpose in a
/// different style — column splitting instead of a regex — so a regex that
/// drifts has something independent to disagree with.
private enum RealData {
    static func repositoryCompatibilityGuide() throws -> String {
        let url = URL(fileURLWithPath: #filePath)
            .deletingLastPathComponent()
            .deletingLastPathComponent()
            .deletingLastPathComponent()
            .deletingLastPathComponent()
            .appendingPathComponent("Documents/en/firmware/compatibility.md")
        return try String(contentsOf: url, encoding: .utf8)
    }

    /// Captured 2026-09-23. 31 restore images, one build per version — which is
    /// why the selector's ambiguity branch cannot be reached from live data and
    /// is exercised from `Fixture` instead.
    static let liveURLs = """
    https://updates.cdn-apple.com/2026FallFCS/5130b3f9-3b4e-469a-b60e-93f6b310cdd9/iPhone17,3_27.0_24A437_Restore.ipsw
    https://updates.cdn-apple.com/2026SummerFCS/29d685ce-f70d-45a0-9823-b1cd115f3927/iPhone17,3_26.6.2_23G90_Restore.ipsw
    https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-93817/B5362BAA-F3EE-49C8-BA43-309F0DAD1362/iPhone17,3_26.6.1_23G83_Restore.ipsw
    https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-58193/1F477C3E-934B-43C0-B428-753B9E005EC0/iPhone17,3_26.6_23G71_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/140-25549/1AFB1F72-E48E-476A-9C21-42B27C846C01/iPhone17,3_26.5.2_23F84_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-63074/5E6B4A05-BDBC-45FE-9606-22B8F4315989/iPhone17,3_26.5_23F77_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-60828/A4082066-CCC4-4903-89E6-FF4801EA609C/iPhone17,3_26.4.2_23E261_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw
    https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw
    https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw
    https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/047-34150/D14FB1F1-B8C5-4A20-9250-8DD35EF19BF5/iPhone17,3_26.2.1_23C71_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-90760/1214478F-8ED8-4AE0-B693-2F63CE0259A9/iPhone17,3_26.2_23C55_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-46329/C1717B2A-9E58-4131-A398-75D9B1D01A89/iPhone17,3_26.0.1_23A355_Restore.ipsw
    https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw
    https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw
    https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-07229/D567EFF0-6D62-461A-9F66-B2EAE22C2DD8/iPhone17,3_18.6.1_22G90_Restore.ipsw
    https://updates.cdn-apple.com/2025SummerFCS/fullrestores/082-98952/853D36FA-A5F4-4B75-B5F3-8D38430F6132/iPhone17,3_18.6_22G86_Restore.ipsw
    https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-46019/A46C805A-4915-4552-BFD4-EFD1C7BE665E/iPhone17,3_18.5_22F76_Restore.ipsw
    https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-30380/AD76C77E-51AA-4D55-A074-9C0E7545D784/iPhone17,3_18.4.1_22E252_Restore.ipsw
    https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-14688/8DC47FED-F5B6-4BE6-B75F-8E36BCC5A484/iPhone17,3_18.4_22E240_Restore.ipsw
    https://updates.cdn-apple.com/2025WinterFCS/fullrestores/082-03679/DA16409C-A02F-46E9-ADE9-ED32BDD47539/iPhone17,3_18.3.2_22D82_Restore.ipsw
    https://updates.cdn-apple.com/2025WinterFCS/fullrestores/072-85742/283FD833-D2EF-4A97-AE6F-406E1DD998DA/iPhone17,3_18.3.1_22D72_Restore.ipsw
    https://updates.cdn-apple.com/2025WinterFCS/fullrestores/072-68251/8CC707F3-9926-4ECC-B7F6-3497FE282048/iPhone17,3_18.3_22D63_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-55500/A62CEE9F-875F-4E53-9C9D-D4172E30BE88/iPhone17,3_18.2.1_22C161_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-42011/88CB7A92-6959-4FB4-A87E-77CE7CB8BB82/iPhone17,3_18.2_22C152_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-31863/D2DE541A-DC63-4016-9B22-0EED8A753FB9/iPhone17,3_18.1.1_22B91_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-12560/4A88CBAB-2F24-4173-BCFD-210325515BCA/iPhone17,3_18.1_22B83_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-02193/DD4AADB5-492C-442E-8E79-42D72EDAF958/iPhone17,3_18.0.1_22A3370_Restore.ipsw
    https://updates.cdn-apple.com/2024FallFCS/fullrestores/062-77769/2A2DBD27-47A6-40DB-AEF5-E283454A67E8/iPhone17,3_18.0_22A3354_Restore.ipsw
    """

    /// The same table, read by splitting on `|` and `_` instead of by regex.
    static func testedBuildsByColumnSplitting(
        in readme: String,
        deviceSuffix: String,
    ) -> Set<VPhoneFirmwareBuildID> {
        // A different way to find the section too: cut the document at its `## `
        // headings rather than scanning line by line for them.
        let sections = readme.components(separatedBy: "\n## ")
        guard let table = sections.first(where: { $0.hasPrefix("Tested Environments") })
        else { return [] }

        var tested: Set<VPhoneFirmwareBuildID> = []
        for row in table.components(separatedBy: "\n") {
            for cell in row.components(separatedBy: "|") {
                let trimmed = cell.trimmingCharacters(in: .whitespaces)
                guard trimmed.hasPrefix("`"), trimmed.hasSuffix("`"), trimmed.count > 2
                else { continue }
                let fields = trimmed.dropFirst().dropLast().components(separatedBy: "_")
                guard fields.count == 3, fields[0] == deviceSuffix else { continue }
                tested.insert(VPhoneFirmwareBuildID(version: fields[1], build: fields[2]))
            }
        }
        return tested
    }
}

struct FirmwareMatrixRealDataTests {
    @Test func `the compatibility parser agrees with an independent column splitter`() throws {
        let readme = try RealData.repositoryCompatibilityGuide()
        let byRegex = VPhoneFirmwareMatrix.testedBuilds(readme: readme, device: Fixture.d)
        let bySplitting = RealData.testedBuildsByColumnSplitting(in: readme, deviceSuffix: "17,3")
        #expect(!bySplitting.isEmpty, "the compatibility table moved — fix the test, not the parser")
        #expect(byRegex == bySplitting)
    }

    @Test func `a live download capture parses whole and joins against the guide`() throws {
        let releases = VPhoneFirmwareMatrix.releases(
            downloadURLs: RealData.liveURLs,
            device: Fixture.d,
        )
        // Every line of the capture is a restore image for this device, so the
        // URL parser has to claim all 31 — a silent drop is the failure mode
        // that would quietly hide a firmware from `--list`.
        #expect(releases.count == RealData.liveURLs.components(separatedBy: "\n").count)
        #expect(releases.count == 31)
        #expect(Set(releases.map(\.build)).count == 31)

        let tested = try VPhoneFirmwareMatrix.testedBuilds(
            readme: RealData.repositoryCompatibilityGuide(),
            device: Fixture.d,
        )
        var supported = 0, notTested = 0
        for release in releases {
            let id = VPhoneFirmwareBuildID(version: release.version, build: release.build)
            switch VPhoneFirmwareMatrix.support(of: release, tested: tested) {
            case .supported:
                #expect(tested.contains(id))
                supported += 1
            case .notTested:
                #expect(!tested.contains(id))
                notTested += 1
            case .unsupported:
                Issue.record("a listing row must never be Unsupported")
            }
        }
        // Neither count may be zero, or the loop above proved nothing.
        #expect(supported > 0)
        #expect(notTested > 0)
    }

    /// Apple serves one build per version, so `--list` over live data is fully
    /// ordered by version alone. This is the property the shell's `sorted(…,
    /// reverse=True)` was there to produce.
    @Test func `the live capture lists newest first`() {
        let out = VPhoneFirmwareMatrix.listing(
            device: Fixture.d, readme: nil,
            downloadURLs: RealData.liveURLs, style: Fixture.plain,
        )
        guard case let .matrix(text) = out else {
            Issue.record("expected a matrix")
            return
        }
        let versions = text.components(separatedBy: "\n")
            .dropFirst(5)
            .compactMap { $0.split(separator: " ").first.map(String.init) }
        #expect(versions.first == "27.0")
        #expect(versions.last == "18.0")
        // 26.6.2 above 26.6, and 26.2.1 above 26.2: a plain string sort puts
        // both the other way round.
        let index = { (v: String) in versions.firstIndex(of: v) ?? -1 }
        #expect(index("26.6.2") < index("26.6"))
        #expect(index("26.2.1") < index("26.2"))
        #expect(index("26.0.1") < index("26.0"))
        #expect(index("26.0") < index("18.6.2"))
    }
}

// MARK: - Ordering

struct FirmwareMatrixOrderingTests {
    private func release(_ version: String, _ build: String) -> VPhoneFirmwareRelease {
        VPhoneFirmwareRelease(version: version, build: build, url: "/\(version)_\(build)")
    }

    @Test func `sorts versions newest first with numeric components`() {
        // Lexically "18.6.2" > "26.0" and "26.4.1" > "26.4"; numerically neither.
        let sorted = [
            release("26.4", "a"), release("18.6.2", "a"), release("26.4.1", "a"),
            release("27.0", "a"), release("26.0", "a"), release("26.10", "a"),
        ].sorted { VPhoneFirmwareMatrix.isNewer($0, than: $1) }
        #expect(sorted.map(\.version) == ["27.0", "26.10", "26.4.1", "26.4", "26.0", "18.6.2"])
    }

    @Test func `sorts builds by code point descending`() {
        // 24A435 vs 24A5430a is the case that separates a string sort from a
        // "looks numeric" one: '4' < '5' at index 3, so 24A5430a wins.
        let sorted = [
            release("27.0", "24A435"), release("27.0", "24A5430a"), release("27.0", "24A5390f"),
        ].sorted { VPhoneFirmwareMatrix.hasHigherBuild($0, than: $1) }
        #expect(sorted.map(\.build) == ["24A5430a", "24A5390f", "24A435"])
    }

    @Test func `a shorter version sorts below its own prefix extension`() {
        #expect(VPhoneFirmwareMatrix.isNewer(release("26.4.1", "a"), than: release("26.4", "a")))
        #expect(!VPhoneFirmwareMatrix.isNewer(release("26.4", "a"), than: release("26.4.1", "a")))
    }

    @Test func `non numeric components still order`() {
        #expect(VPhoneFirmwareMatrix.versionKey("26.beta") == [.number(26), .text("beta")])
        #expect(VPhoneFirmwareMatrix.versionKey("") == [.text("")])
        #expect(VPhoneFirmwareMatrix.VersionPart.number(9) < .text("0"))
    }
}

// MARK: - Column padding

struct FirmwareMatrixPaddingTests {
    @Test func `left justifying never truncates`() {
        // `String.padding(toLength:)` would cut this to 12 and lose the build.
        #expect(VPhoneFirmwareMatrix.leftJustified("27.0.1.2.3.4.5", 12) == "27.0.1.2.3.4.5")
        #expect(VPhoneFirmwareMatrix.leftJustified("26.3", 12) == "26.3        ")
        #expect(VPhoneFirmwareMatrix.leftJustified("", 3) == "   ")
    }

    @Test func `padding goes inside the colour escape`() {
        // Outside the escape the text would be the same width on screen but a
        // different byte string, and every golden above would break.
        #expect(Fixture.colored.render(.supported, width: 11) == "\u{1B}[32mSupported  \u{1B}[0m")
        #expect(Fixture.colored.render(.supported) == "\u{1B}[32mSupported\u{1B}[0m")
        #expect(Fixture.plain.render(.supported, width: 11) == "Supported  ")
    }

    @Test func `an overlong version still leaves one space before the next column`() {
        let urls = "/iPhone17,3_26.4.10.20.30_23E246_Restore.ipsw"
        let out = VPhoneFirmwareMatrix.listing(
            device: Fixture.d, readme: nil, downloadURLs: urls, style: Fixture.plain,
        )
        guard case let .matrix(text) = out else {
            Issue.record("expected a matrix")
            return
        }
        #expect(text.contains("26.4.10.20.30 23E246     Not Tested\u{20}\n"))
    }
}

// MARK: - Colour policy

struct FirmwareMatrixColorPolicyTests {
    /// A pty master is a terminal; a pipe is not. Both are real file
    /// descriptors, so `isatty` is answering for real here.
    private func withTTY<T>(_ body: (Int32) throws -> T) rethrows -> T {
        let fd = posix_openpt(O_RDWR | O_NOCTTY)
        defer {
            if fd >= 0 {
                close(fd)
            }
        }
        return try body(fd)
    }

    @Test func `honours no color clicolor force and isatty per stream`() throws {
        let pipe = Pipe()
        let pipeFD = pipe.fileHandleForWriting.fileDescriptor
        try withTTY { ttyFD in
            try #require(isatty(ttyFD) != 0, "expected a pty master to be a terminal")
            #expect(isatty(pipeFD) == 0)

            func colored(_ fd: Int32, _ env: [String: String]) -> Bool {
                VPhoneStatusStyle.forStream(fd, environment: env).isColored
            }

            // A terminal colours by default; a pipe does not.
            #expect(colored(ttyFD, [:]))
            #expect(!colored(pipeFD, [:]))

            // CLICOLOR_FORCE=1 colours a pipe; any other value does not.
            #expect(colored(pipeFD, ["CLICOLOR_FORCE": "1"]))
            #expect(!colored(pipeFD, ["CLICOLOR_FORCE": "0"]))
            #expect(!colored(pipeFD, ["CLICOLOR_FORCE": "true"]))
            #expect(!colored(pipeFD, ["CLICOLOR_FORCE": ""]))

            // NO_COLOR wins over both the terminal and CLICOLOR_FORCE …
            #expect(!colored(ttyFD, ["NO_COLOR": "1"]))
            #expect(!colored(pipeFD, ["NO_COLOR": "1", "CLICOLOR_FORCE": "1"]))
            // … but only when it is set to something. Empty is "not set", which
            // is how both the shell (`-z`) and the Python (falsy) read it.
            #expect(colored(ttyFD, ["NO_COLOR": ""]))
            #expect(!colored(pipeFD, ["NO_COLOR": ""]))
        }
        try pipe.fileHandleForWriting.close()
        try pipe.fileHandleForReading.close()
    }
}

// MARK: - Exit codes and stream routing

struct FirmwareMatrixCommandLineTests {
    private func capture(
        _ body: (FileHandle, FileHandle) -> Int32,
    ) -> (code: Int32, out: String, err: String) {
        let outPipe = Pipe(), errPipe = Pipe()
        let code = body(outPipe.fileHandleForWriting, errPipe.fileHandleForWriting)
        try? outPipe.fileHandleForWriting.close()
        try? errPipe.fileHandleForWriting.close()
        let out = String(decoding: outPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
        let err = String(decoding: errPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
        return (code, out, err)
    }

    @Test func `list goes to stdout and exits zero`() {
        let r = Fixture.withReadmeFile { path in
            capture { out, err in
                VPhoneFirmwareMatrixCommandLine.list(
                    device: Fixture.d, readmePath: path, downloadURLs: Fixture.urls,
                    environment: [:], stdout: out, stderr: err,
                )
            }
        }
        #expect(r.code == 0)
        #expect(r.out == Golden.listPlain)
        #expect(r.err.isEmpty)
    }

    @Test func `an empty device list goes to stderr and exits one`() {
        let r = Fixture.withReadmeFile { path in
            capture { out, err in
                VPhoneFirmwareMatrixCommandLine.list(
                    device: "iPhone99,9", readmePath: path, downloadURLs: Fixture.urls,
                    environment: [:], stdout: out, stderr: err,
                )
            }
        }
        #expect(r.code == 1)
        #expect(r.out.isEmpty)
        #expect(r.err == "No downloadable IPSWs found for iPhone99,9\n")
    }

    @Test func `a resolved selector goes to stdout and exits zero`() {
        let r = Fixture.withReadmeFile { path in
            capture { out, err in
                VPhoneFirmwareMatrixCommandLine.resolve(
                    device: Fixture.d, version: "26.3", build: "", readmePath: path,
                    downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err,
                )
            }
        }
        #expect(r.code == 0)
        #expect(r.out == Golden.hit)
        #expect(r.err.isEmpty)
    }

    /// 2, not 1. `fw_prepare.sh` forwards this status verbatim so a caller can
    /// tell "pick a build" from "there is no such firmware".
    @Test func `an ambiguous version goes to stderr and exits two`() {
        let r = Fixture.withReadmeFile { path in
            capture { out, err in
                VPhoneFirmwareMatrixCommandLine.resolve(
                    device: Fixture.d, version: "27.0", build: "", readmePath: path,
                    downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err,
                )
            }
        }
        #expect(r.code == 2)
        #expect(r.out.isEmpty)
        #expect(r.err == Golden.ambiguousPlain)
    }

    @Test func `a miss goes to stderr and exits one`() {
        let r = Fixture.withReadmeFile { path in
            capture { out, err in
                VPhoneFirmwareMatrixCommandLine.resolve(
                    device: Fixture.d, version: "99.9", build: "", readmePath: path,
                    downloadURLs: Fixture.urls, environment: [:],
                    stdout: out, stderr: err,
                )
            }
        }
        #expect(r.code == 1)
        #expect(r.out.isEmpty)
        #expect(r.err == "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n")
    }

    @Test func `an unreadable readme path is not an error`() {
        let r = capture { out, err in
            VPhoneFirmwareMatrixCommandLine.list(
                device: Fixture.d, readmePath: "/nonexistent/README.md",
                downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err,
            )
        }
        #expect(r.code == 0)
        #expect(r.out.contains("Not Tested"))
        #expect(!r.out.contains("Supported\u{20}\u{20}\n"))
    }

    /// The half that is easy to get wrong: each command styles the stream it
    /// writes to, not the process. `list` writes its table to stdout, so a
    /// terminal on stderr must not colour it.
    @Test func `list styles stdout not stderr`() throws {
        let fd = posix_openpt(O_RDWR | O_NOCTTY)
        try #require(fd >= 0)
        defer { close(fd) }
        let tty = FileHandle(fileDescriptor: fd, closeOnDealloc: false)
        let outPipe = Pipe()
        let code = Fixture.withReadmeFile { path in
            VPhoneFirmwareMatrixCommandLine.list(
                device: Fixture.d, readmePath: path, downloadURLs: Fixture.urls,
                environment: [:], stdout: outPipe.fileHandleForWriting, stderr: tty,
            )
        }
        try outPipe.fileHandleForWriting.close()
        let out = String(decoding: outPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
        #expect(code == 0)
        #expect(out == Golden.listPlain)
        #expect(!out.contains("\u{1B}["))
    }

    /// And the mirror image: the selector's failures are stderr's, so a
    /// terminal on stdout must not colour them. This is the case that keeps
    /// escapes out of `selection="$(resolve_selector_from_downloads …)"`.
    @Test func `resolve styles stderr not stdout`() throws {
        let fd = posix_openpt(O_RDWR | O_NOCTTY)
        try #require(fd >= 0)
        defer { close(fd) }
        let tty = FileHandle(fileDescriptor: fd, closeOnDealloc: false)
        let errPipe = Pipe()
        let code = Fixture.withReadmeFile { path in
            VPhoneFirmwareMatrixCommandLine.resolve(
                device: Fixture.d, version: "99.9", build: "", readmePath: path,
                downloadURLs: Fixture.urls, environment: [:],
                stdout: tty, stderr: errPipe.fileHandleForWriting,
            )
        }
        try errPipe.fileHandleForWriting.close()
        let err = String(decoding: errPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
        #expect(code == 1)
        #expect(err == "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n")
        #expect(!err.contains("\u{1B}["))
    }

    @Test func `an IPSW naming several models matches each of them`() {
        let urls = """
        https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw
        https://updates.cdn-apple.com/2026SummerFCS/x/iPad16,10,iPad16,11_26.6.2_23G90_Restore.ipsw
        """
        let wifi = VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad16,1")
        #expect(wifi.map(\.build) == ["23G90"])
        #expect(wifi.first?.version == "26.6.2")
        #expect(wifi.first?.url.contains("iPad16,1,iPad16,2_") == true)
        #expect(VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad16,2").count == 1)
        // A longer model number is a different device.
        #expect(VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad16,11").count == 1)
    }

    @Test func `an IPSW named after its family matches the family's models`() {
        let urls = """
        https://updates.cdn-apple.com/2026FallFCS/7532c1a2-9d94-419d-ad88-bd0e3a0e2bbc/iPad_Pro_M4_27.0.1_24A446_Restore.ipsw
        https://updates.cdn-apple.com/2026FallFCS/6074e110-d48d-40c2-b0e8-b611520941a3/iPad17,1,iPad17,2,iPad17,3,iPad17,4_27.0.1_24A446_Restore.ipsw
        """
        let pro = VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad16,5")
        #expect(pro.map(\.version) == ["27.0.1"])
        #expect(pro.map(\.build) == ["24A446"])
        #expect(pro.first?.url.hasSuffix("/iPad_Pro_M4_27.0.1_24A446_Restore.ipsw") == true)
        #expect(VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad17,1").count == 1)
        #expect(VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: "iPad16,1").isEmpty)
    }
}