如何以编程方式解析 XCResult 包的内容

介绍

XCResult 包是一个包含运行一组测试结果详细信息的包或目录。这些包由 Xcode（或命令行中的 xcodebuild）生成，并提供了有关所运行测试的丰富信息，包括测试的名称、持续时间、状态以及它们生成的任何附件（如截图或日志）。

查找 XCResult 包

在 Xcode 中，你可以在测试运行后通过转到"报告导航器"并从列表中选择你感兴趣的包来查找和检查 XCResult 包：

分享 XCResult 包

如果你想与其他人分享该包，可以右键单击"报告导航器"中的包并选择"在 Finder 中显示"以打开包所在的目录。无论你是从命令行使用 xcodebuild 运行测试还是在 Xcode 中运行测试，所有 .xcresult 包都生成在应用的 Logs/Test 目录中的 Derived Data 中，你可以双击 .xcresult 文件在 Xcode 中打开并检查包的内容。

解析 XCResult 包

当你在 CI/CD 环境中运行应用的测试时，XCResult 包变得更加重要，因为没有它们，关于测试失败的唯一信息将是 xcodebuild 命令的日志。此外，对 CI/CD 机器的访问通常受到限制且繁琐，因此检索特定运行的 .xcresult 包并不总是那么简单。

这就是为什么通常最好让你选择的 CI/CD 服务在测试失败时将 XCResult 包作为工件上传到你的工作流程中，以便开发人员可以下载并检查结果。虽然这在开发者体验方面是一个重大改进，但反馈并不是即时的，因为需要开发人员下载包并在他们的机器上打开它。

自动解析 XCResult 包的内容

如果你能够以编程方式解析 XCResult 包的内容并提取所需信息，而无需打开 Xcode，那不是很好吗？这样，你可以自动化检查测试结果的过程，并为开发人员提供有关测试失败的即时反馈。这听起来很不错，但当你检查 .xcresult 包的内容时，你很快会发现内容不可读，这使得以编程方式解析它们的任务变得有些挑战性：

使用 XCResultKit 解析包的内容

幸运的是，对于我们来说，有一些工具可以在解析 XCResult 包的内容时使我们的生活变得更轻松。其中一个用 Swift 编写的库，我们将在本文中使用的是 David House 的 XCResultKit。

初始化库

首先，我们需要将库导入到我们的项目中作为 Swift Package。在这种情况下，我们将构建一个 Swift 可执行文件，该文件将使用 XCResultKit 从 .xcresult 包中提取信息：

Package.swift

swift 复制代码

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "ResultAnalyzer",
    platforms: [
        .macOS(.v13)
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser.git", exact: "1.5.0"),
        .package(url: "https://github.com/davidahouse/XCResultKit.git", exact: "1.2.0")
    ],
    targets: [
        .executableTarget(
            name: "ResultAnalyzer",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "XCResultKit", package: "XCResultKit")
            ]
        ),
    ]
)

在可执行文件的主文件中，我们现在可以导入库，要求提供 .xcresult 包的路径，并使用用户提供的路径初始化一个 XCResult 对象：

XCResultAnalyzer.swift

swift 复制代码

import ArgumentParser
import Foundation
import XCResultKit

@main
struct XCResultAnalyzer: ParsableCommand {
    @Argument(help: "The path to an `.xcresult` bundle")
    var bundle: String
    
    func run() throws {
        guard let url = URL(string: bundle) else { return }
        let result = XCResultFile(url: url)
    }
}

获取调用记录

读取包内容的第一步是获取信息记录。该记录包含所有元数据和信息，用于从包中检索其余数据：

XCResultAnalyzer.swift

swift 复制代码

func run() throws {
    guard let url = URL(string: bundle) else { return }
    let result = XCResultFile(url: url)

    guard let invocationRecord = result.getInvocationRecord() else { return }
}

信息记录包含有关测试运行的一些顶级信息，例如发生的操作、遇到的问题的详细摘要以及测试运行的指标：

XCResultAnalyzer.swift

swift 复制代码

func run() throws {
    guard let url = URL(string: bundle) else { return }
    let result = XCResultFile(url: url)

    guard let invocationRecord = result.getInvocationRecord() else { return }

    print("✅ Ran \(invocationRecord.metrics.testsCount ?? .zero) tests and skipped \(invocationRecord.metrics.testsSkippedCount ?? .zero)")
    print("❌ \(invocationRecord.issues.testFailureSummaries.count) test failures")
    print("🧐 Ran actions: \(invocationRecord.actions.compactMap { $0.testPlanName })")
}

使用我们之前检查的 .xcresult 包运行可执行文件，我们会得到以下输出：

text 复制代码

✅ Ran 3 tests and skipped 0
❌ 1 test failures
🧐 Ran actions: ["AutomatedTesting"]

获取测试信息

获取给定测试的特定信息要复杂一些，因为你需要遍历包中的所有操作，获取测试计划信息，然后才能访问个别测试的特定信息。

让我们首先从包中检索所有失败的测试：

XCResultAnalyzer.swift

swift 复制代码

func run() throws {
    guard let url = URL(string: bundle) else { return }
    let result = XCResultFile(url: url)
    
    guard let invocationRecord = result.getInvocationRecord() else { return }
    
    // 1
    let testBundles = invocationRecord
        .actions
        .compactMap { action -> ActionTestPlanRunSummaries? in
            guard let id = action.actionResult.testsRef?.id, let summaries = result.getTestPlanRunSummaries(id: id) else {
                return nil
            }
            
            return summaries
        }
        .flatMap(\.summaries)
        .flatMap(\.testableSummaries)
    
    let allFailingTests = testBundles
        // 2
        .flatMap(\.tests)
        // 3
        .flatMap(\.subtests)
        .filter { $0.testStatus.lowercased() == "failure" }
}

让我们回顾一下包，并将其结构映射到代码中的注释：

导出屏幕录制

现在我们有了失败的测试，我们可以获取包含所有步骤的摘要，检索第一步的屏幕录制附件并导出它：

XCResultAnalyzer.swift

swift 复制代码

func run() throws {
    // ...
    let screenRecordings = allFailingTests
    .compactMap { test -> ActionTestSummary? in
        guard let id = test.summaryRef?.id else { return nil }
        
        return result.getActionTestSummary(id: id)
    }
    // 1
    .flatMap(\.activitySummaries)
    // 2
    .first?
    // 3
    .attachments
    .filter { $0.name == "kXCTAttachmentScreenRecording" && $0.uniformTypeIdentifier == "public.mpeg-4" } ?? []
        
    for screenRecording in screenRecordings {
        let tempFileDirectory = URL.temporaryDirectory
        result.exportAttachment(attachment: screenRecording, outputPath: tempFileDirectory.path())
    }
}

让我们再次查看包，并将其结构映射到代码中的注释。

可运行 Demo

上面详细介绍了理论逻辑。下面根据这个些功能提供一个可以运行的 Demo。

这个 Demo 将使用 XCResultKit 库来解析 XCResult 包的内容，并提取测试运行的基本信息和失败测试的屏幕录制。

初始化 Swift Package

首先，我们创建一个新的 Swift Package 项目。在终端中运行以下命令来创建项目：

bash 复制代码

swift package init --type executable
cd [YourProjectName]

然后编辑 Package.swift 文件以添加依赖项：

swift 复制代码

// swift-tools-version: 5.6

import PackageDescription

let package = Package(
    name: "XCResultParserDemo",
    platforms: [
        .macOS(.v12)
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-argument-parser.git", exact: "1.5.0"),
        .package(url: "https://github.com/davidahouse/XCResultKit.git", exact: "1.2.0")
    ],
    targets: [
        .executableTarget(
            name: "XCResultParserDemo",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "XCResultKit", package: "XCResultKit")
            ]
        ),
    ]
)

编写主文件

接下来，我们在 Sources/XCResultParserDemo/main.swift 中编写主文件代码。这个文件将导入库，处理命令行参数，并解析 XCResult 包的内容。

swift 复制代码

import ArgumentParser
import Foundation
import XCResultKit

@main
struct XCResultAnalyzer: ParsableCommand {
    @Argument(help: "The path to an `.xcresult` bundle")
    var bundle: String
    
    func run() throws {
        guard let url = URL(string: bundle) else {
            print("Invalid URL")
            return
        }
        let result = XCResultFile(url: url)

        // 获取调用记录
        guard let invocationRecord = result.getInvocationRecord() else {
            print("Could not retrieve invocation record")
            return
        }

        // 输出基本信息
        print("✅ Ran \(invocationRecord.metrics.testsCount ?? .zero) tests and skipped \(invocationRecord.metrics.testsSkippedCount ?? .zero)")
        print("❌ \(invocationRecord.issues.testFailureSummaries.count) test failures")
        print("🧐 Ran actions: \(invocationRecord.actions.compactMap { $0.testPlanName })")

        // 获取失败的测试
        let testBundles = invocationRecord
            .actions
            .compactMap { action -> ActionTestPlanRunSummaries? in
                guard let id = action.actionResult.testsRef?.id, let summaries = result.getTestPlanRunSummaries(id: id) else {
                    return nil
                }
                
                return summaries
            }
            .flatMap(\.summaries)
            .flatMap(\.testableSummaries)
        
        let allFailingTests = testBundles
            .flatMap(\.tests)
            .flatMap(\.subtests)
            .filter { $0.testStatus.lowercased() == "failure" }

        // 导出失败测试的屏幕录制
        let screenRecordings = allFailingTests
        .compactMap { test -> ActionTestSummary? in
            guard let id = test.summaryRef?.id else { return nil }
            
            return result.getActionTestSummary(id: id)
        }
        .flatMap(\.activitySummaries)
        .first?
        .attachments
        .filter { $0.name == "kXCTAttachmentScreenRecording" && $0.uniformTypeIdentifier == "public.mpeg-4" } ?? []
            
        for screenRecording in screenRecordings {
            let tempFileDirectory = URL.temporaryDirectory
            let outputPath = tempFileDirectory.appendingPathComponent(UUID().uuidString).appendingPathExtension("mp4")
            try result.exportAttachment(attachment: screenRecording, outputPath: outputPath.path)
            print("Screen recording exported to: \(outputPath.path)")
        }
    }
}

代码解释

导入库和定义命令 ：我们导入了 ArgumentParser、Foundation 和 XCResultKit 库，并定义了一个主结构体 XCResultAnalyzer，它遵循 ParsableCommand 协议以处理命令行参数。
处理命令行参数 ：@Argument 属性包装器用于定义命令行参数。在这里，我们要求用户提供一个 .xcresult 包的路径。
解析 URL 和初始化 XCResultFile ：我们将用户提供的路径转换为 URL 对象，并使用 XCResultFile 类初始化它。
获取调用记录 ：我们调用 getInvocationRecord() 方法来获取调用记录，这包含了测试运行的元数据和详细信息。
输出基本信息：我们输出了测试的总数、跳过的测试数量、失败的测试数量和执行的操作计划名称。
获取失败的测试：我们遍历调用记录中的操作，获取测试计划运行摘要，过滤出所有失败的测试。
导出屏幕录制：我们遍历失败测试的活动摘要，过滤出屏幕录制附件，并将它们导出到临时目录中。

运行 Demo

确保你的项目目录中有一个 .xcresult 包。然后，在终端中导航到项目目录并运行以下命令：

bash 复制代码

swift run XCResultParserDemo /path/to/your.xcresult

这将解析提供的 XCResult 包，并输出测试运行的基本信息和任何失败测试的屏幕录制路径。

通过这个 Demo，你可以以编程方式解析 XCResult 包的内容，并提取有用的信息以改进测试和 CI/CD 工作流。

结论

就是这样！下次运行可执行文件并提供 .xcresult 包的路径时，你将获得导出到临时目录的失败测试的屏幕录制，随时可以分享至任何需要的地方。