Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

17.3 KB
Raw Blame
import XCTest
@testable import HighballKit

/// The arm64 engine line (private/notes/rosetta-transition-plan.md, for macOS 28's end of Rosetta):
/// the app derives every architecture-specific path from the manifest, needs Rosetta only for the
/// engines that say so, and runs an arm64 engine through the signed loader helper in Highball.app,
/// never through the engine's own loader. Nothing here runs Wine; the layouts are what the M4 spike
/// of 2026-10-04 measured working.
final class EngineArchTests: XCTestCase {
    private func manifest(_ arch: String, requires: [String]? = nil) -> EngineManifest {
        var m = EngineManifest(id: "\(arch == "arm64" ? "arm64" : "x64")-test-r1", displayName: "test", arch: arch, minMacOS: "26.5", components: [:])
        m.requires = requires
        return m
    }

    private func tempRoot(_ name: String) -> URL {
        let root = FileManager.default.temporaryDirectory.appending(path: "\(name)-\(UUID().uuidString)")
        addTeardownBlock { try? FileManager.default.removeItem(at: root) }
        return root
    }

    private func touch(_ url: URL) throws {
        try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
        try Data("x".utf8).write(to: url)
        try FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: url.path)
    }

    // MARK: Environments stay on one architecture

    /// No prefix has been moved between the Intel engines and the arm64 line, so the picker and
    /// the failure advice never offer it; a recipe's engine ask offers a new environment instead.
    func testEnvironmentsMoveOnlyWithinOneArchitecture() {
        let intel = manifest("x86_64"), arm = manifest("arm64")
        var intel2 = intel; intel2.id = "x64-test-r2"
        let root = tempRoot("hb-arch-move")
        let installed = [InstalledEngine(manifest: intel, root: root.appending(path: intel.id)),
                         InstalledEngine(manifest: arm, root: root.appending(path: arm.id))]
        XCTAssertEqual(EngineStore.offeredEngines(installed: installed, known: [intel2], current: intel.id, macOS: "27.0").map(\.id),
                       ["x64-test-r1", "x64-test-r2"])
        XCTAssertEqual(EngineStore.offeredEngines(installed: installed, known: [intel2], current: arm.id, macOS: "27.0").map(\.id),
                       ["arm64-test-r1"])
        XCTAssertEqual(Set(EngineStore.offeredEngines(installed: installed, known: [intel2], current: "gone-r1", macOS: "27.0").map(\.id)),
                       ["x64-test-r1", "arm64-test-r1", "x64-test-r2", "gone-r1"], "an environment whose engine is gone keeps every choice")
        XCTAssertNil(EngineStore.alternateEngine(for: arm.id, installed: installed, defaultID: intel.id), "an Intel default is no advice for an arm64 environment")
        XCTAssertNil(EngineStore.alternateEngine(for: intel.id, installed: installed, defaultID: nil))
        XCTAssertTrue(EngineStore.sameArch(current: nil, target: "arm64"))
        XCTAssertFalse(EngineStore.sameArch(current: "x86_64", target: "arm64"))
        XCTAssertFalse(EngineStore.sameArch(current: "arm64", target: "x86_64"))
    }

    /// highball-db#537: with the preview key set, the arm64 line showed nowhere a player could pick it.
    /// New environment offers the newest revision of each line of the other architecture, and nothing
    /// when there is none.
    func testNewEnvironmentOffersTheOtherArchitecturesNewestRevision() {
        let intel = manifest("x86_64", requires: ["rosetta2"])
        var arm1 = manifest("arm64"), arm6 = manifest("arm64"), arm10 = manifest("arm64"), future = manifest("arm64"), other = manifest("arm64")
        arm1.id = "arm64-wine11.18-r1"; arm6.id = "arm64-wine11.18-r6"; arm10.id = "arm64-wine11.18-r10"
        future.id = "arm64-wine12.0-r1"; future.minMacOS = "28.0"
        other.id = "arm64-wine11.20-r2"
        let root = tempRoot("hb-new-env")
        let installed = [InstalledEngine(manifest: intel, root: root.appending(path: intel.id)),
                         InstalledEngine(manifest: arm1, root: root.appending(path: arm1.id))]
        XCTAssertEqual(EngineStore.newEnvironmentAlternatives(defaultArch: "x86_64", installed: installed, known: [arm6, arm10, future, other], macOS: "27.0.1"),
                       ["arm64-wine11.20-r2", "arm64-wine11.18-r10"], "one row per line, newest revision, nothing above this macOS")
        XCTAssertEqual(EngineStore.newEnvironmentAlternatives(defaultArch: "x86_64", installed: installed, known: [], macOS: "27.0"),
                       ["arm64-wine11.18-r1"], "an installed engine counts without its manifest")
        XCTAssertEqual(EngineStore.newEnvironmentAlternatives(defaultArch: "x86_64", installed: Array(installed.prefix(1)), known: [], macOS: "27.0"), [],
                       "nothing to choose, nothing asked")
        XCTAssertEqual(EngineStore.newEnvironmentAlternatives(defaultArch: "arm64", installed: installed, known: [arm6], macOS: "27.0"),
                       ["x64-test-r1"], "the same rule the other way round")
    }

    /// highball#413: Rosetta would not install, so Get started failed while the arm64 line was bundled.
    func testSetupWithoutRosettaTakesTheNewestNativeEngineItSees() {
        let intel = manifest("x86_64", requires: ["rosetta2"])
        var arm5 = manifest("arm64", requires: []), arm6 = manifest("arm64", requires: []), floor28 = manifest("arm64", requires: [])
        arm5.id = "arm64-wine11.18-r5"; arm6.id = "arm64-wine11.18-r6"; floor28.id = "arm64-wine11.18-r9"; floor28.minMacOS = "28.0"
        XCTAssertEqual(EngineStore.startingEngineWithoutRosetta(known: [intel, arm5, arm6, floor28], macOS: "27.0.1")?.id, "arm64-wine11.18-r6")
        XCTAssertNil(EngineStore.startingEngineWithoutRosetta(known: [intel], macOS: "27.0.1"), "without the preview key there is none")
    }

    func testTheDownloadSizeCountsEachArchiveOnce() {
        var m = manifest("arm64")
        let renderers = URL(string: "https://example.com/renderers-arm64.tar.xz")!
        m.components["vkd3d"] = EngineManifest.Component(kind: "renderer", url: renderers, sha256: "a", size: 100)
        m.components["dxvk"] = EngineManifest.Component(kind: "renderer", url: renderers, sha256: "a", size: 100)
        m.components["wine"] = EngineManifest.Component(kind: "wine", url: URL(string: "https://example.com/wine.tar.xz")!, sha256: "b", size: 50)
        XCTAssertEqual(m.downloadBytes, 150, "two folders of one archive are one download")
    }

    func testDirectoriesFollowTheArchitecture() {
        let intel = manifest("x86_64"), arm = manifest("arm64")
        XCTAssertEqual(intel.pe64LibDir, "x86_64-windows")
        XCTAssertEqual(intel.unixLibDir, "x86_64-unix")
        XCTAssertEqual(arm.pe64LibDir, "aarch64-windows", "Wine's ARM64X builtins, with the ARM64EC code x86-64 programs call into")
        XCTAssertEqual(arm.unixLibDir, "aarch64-unix")
        XCTAssertEqual(EngineManifest.pe32LibDir, "i386-windows", "32-bit programs run through WoW64 on both lines")
        XCTAssertFalse(intel.isNativeARM64); XCTAssertTrue(arm.isNativeARM64)
        XCTAssertEqual(EngineIntegrity.libraryDirectories(engineRoot: URL(fileURLWithPath: "/e"), arch: "arm64").map(\.lastPathComponent),
                       ["aarch64-windows", "i386-windows"])
        XCTAssertEqual(EngineIntegrity.libraryDirectories(engineRoot: URL(fileURLWithPath: "/e")).map(\.lastPathComponent),
                       ["x86_64-windows", "i386-windows"], "the default stays the Intel layout every shipped engine has")
    }

    /// An arm64 engine's Wine opens MoltenVK and its other host libraries by leaf name, and the
    /// GStreamer framework carries a stock libMoltenVK: the engine's lib leads the fallback path so
    /// winevulkan gets the patched copy (the first app launch got the framework's, 2026-10-15).
    func testAnArm64EngineOpensItsOwnHostLibrariesFirst() {
        let root = URL(fileURLWithPath: "/e")
        let arm = InstalledEngine(manifest: manifest("arm64"), root: root).baseEnvironment()["DYLD_FALLBACK_LIBRARY_PATH"]!
        XCTAssertTrue(arm.hasPrefix("/e/engine/lib:"), arm)
        XCTAssertTrue(arm.contains("/e/frameworks/GStreamer.framework/Versions/1.0/lib"), "the framework's plugins still find their libraries")
        let intel = InstalledEngine(manifest: manifest("x86_64"), root: root).baseEnvironment()["DYLD_FALLBACK_LIBRARY_PATH"]!
        XCTAssertTrue(intel.hasPrefix("/e/frameworks:"), "the Intel line is unchanged, its engine/lib links resolve through rpath")
    }

    func testOnlyEnginesThatSaySoNeedRosetta() throws {
        XCTAssertTrue(manifest("x86_64", requires: ["rosetta2"]).requiresRosetta)
        XCTAssertFalse(manifest("arm64", requires: []).requiresRosetta)
        XCTAssertFalse(manifest("arm64").requiresRosetta, "no requires at all means nothing is required")
        // Every Intel engine shipped must keep saying so, or the app would stop installing Rosetta
        // for it; the native arm64 line (arm64-wine11.18-r1 since 2026-10-15) runs x86-64 code
        // through FEX inside Wine and must not ask for Rosetta.
        let dir = URL(fileURLWithPath: #filePath).deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent().appending(path: "spike")
        var files = try FileManager.default.contentsOfDirectory(at: dir.appending(path: "engines"), includingPropertiesForKeys: nil).filter { $0.pathExtension == "json" }
        files.append(dir.appending(path: "engine-manifest.json"))
        var intel = 0, arm = 0
        for f in files {
            let m = try EngineManifest.load(from: f)
            if m.isNativeARM64 {
                arm += 1
                XCTAssertFalse(m.requiresRosetta, "\(m.id) is native arm64 and must not ask for Rosetta")
            } else {
                intel += 1
                XCTAssertEqual(m.arch, "x86_64", "\(m.id) is not an Intel engine")
                XCTAssertTrue(m.requiresRosetta, "\(m.id) no longer declares rosetta2")
            }
        }
        XCTAssertGreaterThan(intel, 0, "the Intel engines are still shipped")
        XCTAssertGreaterThan(arm, 0, "the arm64 line's manifest is shipped")
    }

    func testAnARM64EngineNeedsFEXAndTheSignedLoader() throws {
        let arm = manifest("arm64")
        let files = InstalledEngine.requiredFiles(for: arm)
        XCTAssertTrue(files.contains("engine/lib/wine/aarch64-windows/kernel32.dll"))
        XCTAssertTrue(files.contains("engine/lib/wine/aarch64-unix/ntdll.so"))
        XCTAssertTrue(files.contains("engine/lib/wine/i386-windows/kernel32.dll"))
        XCTAssertFalse(files.contains { $0.contains("x86_64") }, "nothing Intel is expected of an arm64 engine")
        for fex in ["engine/lib/wine/aarch64-windows/xtajit64.dll", "engine/lib/wine/aarch64-windows/xtajit.dll",
                    "engine/lib/wine/aarch64-unix/libarm64ecfex.so", "engine/lib/wine/aarch64-unix/libwow64fex.so"] {
            XCTAssertTrue(files.contains(fex), "\(fex) is what makes x86 programs run at all")
        }
        XCTAssertEqual(InstalledEngine.requiredFiles, InstalledEngine.requiredFiles(for: manifest("x86_64")), "the Intel list is unchanged")

        // A tree with every file, but the loader is the engine's own: not complete.
        let root = tempRoot("arm64-engine")
        for f in files { try touch(root.appending(path: f)) }
        let engine = InstalledEngine(manifest: arm, root: root)
        XCTAssertEqual(engine.missingFiles, [InstalledEngine.signedLoaderName])
        XCTAssertFalse(engine.usesSignedLoader)

        // Linking the signed helper completes it, sets the engine's loader aside once, and makes
        // bin/wine the relative link Wine itself installs, so a start through either path reaches
        // the helper and finds ntdll.so beside the Unix-side link.
        let app = tempRoot("Highball.app").appendingPathExtension("app")
        let helper = WineLoaderHelper.binary(inAppBundle: app)
        try touch(helper)
        try EngineStore().linkSignedLoader(root, manifest: arm, helper: helper)
        let unixLink = root.appending(path: "engine/lib/wine/aarch64-unix/wine")
        XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: unixLink.path), helper.path)
        XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: root.appending(path: "engine/bin/wine").path), "../lib/wine/aarch64-unix/wine")
        XCTAssertTrue(FileManager.default.fileExists(atPath: root.appending(path: "engine/bin/wine.unsigned").path), "the engine's own loader is kept aside")
        XCTAssertTrue(engine.usesSignedLoader)
        XCTAssertEqual(engine.missingFiles, [])
        XCTAssertEqual(engine.wineBinary.resolvingSymlinksInPath().path, helper.resolvingSymlinksInPath().path, "a launch runs the helper")

        // The app moved: the next read repoints the link and nothing else changes.
        let moved = tempRoot("Moved.app").appendingPathExtension("app")
        let helper2 = WineLoaderHelper.binary(inAppBundle: moved)
        try touch(helper2)
        try EngineStore().linkSignedLoader(root, manifest: arm, helper: helper2)
        XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: unixLink.path), helper2.path)
        XCTAssertEqual(engine.missingFiles, [])

        // An Intel engine is never touched.
        let intelRoot = tempRoot("x64-engine")
        try touch(intelRoot.appending(path: "engine/bin/wine"))
        try EngineStore().linkSignedLoader(intelRoot, manifest: manifest("x86_64", requires: ["rosetta2"]), helper: helper)
        XCTAssertNil(try? FileManager.default.destinationOfSymbolicLink(atPath: intelRoot.appending(path: "engine/bin/wine").path))
    }

    func testTheHelperIsFoundInTheEnvironmentThenTheAppThenApplications() throws {
        let app = tempRoot("App").appendingPathExtension("app"), installed = tempRoot("Installed").appendingPathExtension("app")
        let nowhere = URL(fileURLWithPath: "/nonexistent/Highball.app")
        XCTAssertNil(WineLoaderHelper.locate(environment: [:], appBundle: app, applications: nowhere), "nothing on disk yet")
        try touch(WineLoaderHelper.binary(inAppBundle: installed))
        XCTAssertEqual(WineLoaderHelper.locate(environment: [:], appBundle: app, applications: installed), WineLoaderHelper.binary(inAppBundle: installed))
        try touch(WineLoaderHelper.binary(inAppBundle: app))
        XCTAssertEqual(WineLoaderHelper.locate(environment: [:], appBundle: app, applications: installed), WineLoaderHelper.binary(inAppBundle: app),
                       "the running app's own helper wins over the one in Applications")
        let override = tempRoot("Override").appendingPathExtension("app")
        try touch(WineLoaderHelper.binary(inAppBundle: override))
        let bundlePath = override.appending(path: "Contents/Helpers/WineLoader.app").path
        XCTAssertEqual(WineLoaderHelper.locate(environment: [WineLoaderHelper.environmentKey: bundlePath], appBundle: app, applications: installed),
                       WineLoaderHelper.binary(inAppBundle: override), "the environment names the bundle")
        XCTAssertEqual(WineLoaderHelper.locate(environment: [WineLoaderHelper.environmentKey: WineLoaderHelper.binary(inAppBundle: override).path], appBundle: app, applications: installed),
                       WineLoaderHelper.binary(inAppBundle: override), "or the binary")
        XCTAssertEqual(WineLoaderHelper.locate(environment: [WineLoaderHelper.environmentKey: "/nonexistent/wine"], appBundle: app, applications: installed),
                       WineLoaderHelper.binary(inAppBundle: app), "a wrong override falls through")
        // The CLI on a Mac without the app: a non-bundle main executable has no helper of its own.
        XCTAssertEqual(WineLoaderHelper.locate(environment: [:], appBundle: URL(fileURLWithPath: "/usr/local/bin/highball"), applications: installed),
                       WineLoaderHelper.binary(inAppBundle: installed))
    }

    func testTheRosettaSwitchOnlyReachesRosettaEngines() throws {
        // Bottle.environment sets ROSETTA_ADVERTISE_AVX for an Intel engine (EnvironmentTests) and
        // must not for an arm64 one, where x86 code runs through FEX and the variable means nothing.
        var bottle = Bottle(url: URL(fileURLWithPath: "/tmp/hb-arch-test-bottle"), settings: BottleSettings(name: "t", engineID: "arm64-test-r1"))
        bottle.settings.advertiseAVX = true
        let arm = InstalledEngine(manifest: manifest("arm64"), root: tempRoot("arm64-engine"))
        XCTAssertNil(try bottle.environment(engine: arm, renderer: .wined3d)["ROSETTA_ADVERTISE_AVX"])
        let intel = InstalledEngine(manifest: manifest("x86_64", requires: ["rosetta2"]), root: tempRoot("x64-engine"))
        XCTAssertEqual(try bottle.environment(engine: intel, renderer: .wined3d)["ROSETTA_ADVERTISE_AVX"], "1")
    }

    func testMoltenVKLogsWarningsNotItsExtensionList() throws {
        var bottle = Bottle(url: URL(fileURLWithPath: "/tmp/hb-arch-test-bottle"), settings: BottleSettings(name: "t", engineID: "x64-test-r1"))
        let intel = InstalledEngine(manifest: manifest("x86_64", requires: ["rosetta2"]), root: tempRoot("x64-engine"))
        XCTAssertEqual(try bottle.environment(engine: intel, renderer: .wined3d)["MVK_CONFIG_LOG_LEVEL"], "2", "warnings and errors only")
        bottle.settings.environment["MVK_CONFIG_LOG_LEVEL"] = "3"
        XCTAssertEqual(try bottle.environment(engine: intel, renderer: .wined3d)["MVK_CONFIG_LOG_LEVEL"], "3", "a player's own level wins")
    }
}