DBXCResultParser

The DBXCResultParser package provides a Swift module for parsing .xcresult files generated by Xcode to produce a structured report of build and test results. It allows developers to programmatically access detailed information about test cases, code coverage, and warnings from their CI/CD pipelines or automated scripts.

Features

• Parses .xcresult files to create a typed model of the test results and code coverage.
• Filters out coverage data related to test helpers and test cases.
• Provides a detailed breakdown of modules, files, and repeatable tests.
• Calculates total and average test durations, as well as combined test statuses.
• Supports identifying slow tests based on average duration.
• Includes utility functions for filtering tests based on status.
• Can be executed as a command-line tool to generate test reports directly from the terminal.

Usage

To use DBXCResultParser in your Swift package, add it to the dependencies for your Package.swift file:

let package = Package(
    name: "YourPackageName",
    dependencies: [
        .package(url: "https://github.com/dodobrands/DBXCResultParser", .upToNextMajor(from: "3.0.0"))
    ],
    targets: [
        .target(
            name: "YourTargetName",
            dependencies: ["DBXCResultParser"]
        )
    ]
)

To parse an .xcresult file and access the report data, initialize a DBXCReportModel with the path to the .xcresult file:

import DBXCResultParser

let xcresultPath = URL(fileURLWithPath: "/path/to/your.xcresult")
do {
    let reportModel = try DBXCReportModel(xcresultPath: xcresultPath)
    
    // Access different parts of the report:
    let modules = reportModel.modules
    let warningCount = reportModel.warningCount
    let totalCoverage = reportModel.totalCoverage
    
    // Iterate over modules, files, and tests:
    for module in modules {
        print("Module: \(module.name)")
        for file in module.files {
            print("  File: \(file.name)")
            for repeatableTest in file.repeatableTests {
                print("    Repeatable Test: \(repeatableTest.name)")
                for test in repeatableTest.tests {
                    print("      Test: \(test.status.icon) - Duration: \(test.duration)")
                }
            }
        }
    }
    
} catch {
    print("An error occurred while parsing the .xcresult file: \(error)")
}

Formatting Test Reports with DBXCTextFormatter

The DBXCTextFormatter class provides a way to format the data from a DBXCReportModel into a human-readable string. It supports two output formats: a detailed list of test results and a summary count of test results.

Usage

To format your test report data, create an instance of DBXCTextFormatter:

import DBXCResultParser

// Assuming you have already created a `DBXCReportModel` instance as `reportModel`
let reportModel: DBXCReportModel = ...

// Create a text formatter
let formatter = DBXCTextFormatter()

// Format the report data into a string
let formattedOutput = formatter.format(reportModel)

// Print the formatted output
print("Formatted Output:\n\(formattedOutput)")

The format method can also take an array of DBXCReportModel.Module.File.RepeatableTest.Test.Status to filter which test results are included in the output. By default, it includes all test statuses.

let formattedOutput = formatter.format(reportModel, include: [.failure])

Output Formats

List Format

Outputs a detailed list of test results, including the name of each file and the status of each test.

FileA.swift
✅ TestA1
❌ TestA2 (Failure reason)

FileB.swift
✅ TestB1
⚠️ TestB2

Count Format

Outputs a summary count of test results, including the total number of tests and their combined duration.

12 tests (1m 23s)

Customizing Number and Measurement Formatting

The DBXCTextFormatter allows you to specify a locale when formatting the report. This locale is used to format numbers and measurements according to the provided locale's conventions.

let formatter = DBXCTextFormatter()
let output = formatter.format(reportModel, locale: Locale(identifier: "fr_FR"))
print(output) // Will output numbers and durations formatted in French

Command-Line Tool Usage

The package includes a command-line tool that can be executed to generate test reports. Here is an example of how to run it:

swift run DBXCResultParser-TextFormatterExec --xcresult-path path/to/tests.xcresult

The available options are:

• --xcresult-path: Specifies the path to the .xcresult file.
• --format: Determines the output format (list or count).
• --locale: Sets the locale for number and measurement formatting (e.g., "en-GB").
• --include: Filters the test results to include only certain statuses (e.g., failure,skipped).

License

This code is released under the Apache License. See LICENSE for more information.