Custom Dump

The library provides conformance for many Apple ecosystem types to CustomDumpStringConvertible to ensure they dump to readable strings instead of unhelpful Objective-C internal representations (e.g., __C.UNNotificationSetting).

You can implement this protocol yourself to provide a custom string representation for your own types when using customDump.

To use Custom Dump in a Swift Package Manager (SwiftPM) project, add the repository URL to your Package.swift dependencies clause.

dependencies: [
  .package(url: "https://github.com/pointfreeco/swift-custom-dump", from: "1.0.0")
]

You can add Custom Dump to an Xcode project by adding it as a package dependency using the following URL:

https://github.com/pointfreeco/swift-custom-dump

The following XCTAssert functions are deprecated. If you are using them in your test suites, you should migrate to their respective replacements to ensure future compatibility.

Deprecated APIs:

• XCTAssertNoDifference(_:_:_:file:line:)
• XCTAssertDifference(_:_:operation:changes:file:line:) (various overloads)

The diff function allows you to textually compare two values by generating a color-coded diff (using + and - notation) based on their customDump output. It is optimized to minimize the diff size, showing only the parts of the structure that have changed, even in large collections.

var other = user
other.favoriteNumbers[1] = 91

print(diff(user, other)!) // Returns an optional string

The customDump function provides a more refined and readable output of nested structures compared to Swift's standard dump. It optimizes for readability by:

• Mimicking Swift struct syntax for structs.
• Including indices for array elements (e.g., [0]: value).
• Using a compact, ordered format for dictionaries.
• Providing a simplified tree structure for enums and deeply nested types.

import CustomDump

struct User {
  var favoriteNumbers: [Int]
  var id: Int
  var name: String
}

let user = User(
  favoriteNumbers: [42, 1729],
  id: 2,
  name: "Blob"
)

customDump(user)

In testing environments (XCTest or Swift Testing), expectNoDifference provides a superior alternative to XCTAssertEqual or #expect. When an assertion fails, instead of a hard-to-read equality message, it produces a formatted diff showing exactly which field or value changed.

var other = user
other.name += "!"

// Instead of XCTAssertEqual(user, other)
expectNoDifference(user, other)

The diff(_:_:format:) function allows you to perform a textual diff between two values. It produces a formatted string showing additions (+) and removals (-), similar to standard diff tools. It is optimized to minimize the diff size by omitting unchanged parts of large collections (using ... (n unchanged) notation).

var other = user
other.favoriteNumbers[1] = 91

print(diff(user, other)!)

When testing, XCTAssertEqual often produces hard-to-read failure messages for complex types. Use expectNoDifference(_:_:_:file:line:) to assert that two values are equal. If they are not, it provides a beautifully formatted diff in the test failure message, making it easy to see exactly which field changed.

var other = user
other.name += "!"

expectNoDifference(user, other)

The expectDifference function asserts that a specific operation causes a predictable set of changes to a value.

Exhaustive Assertion: Pass an operation in a closure and describe all expected changes in a changes closure. The assertion fails if the changes are not exhaustive.

Non-exhaustive Assertion: Omit the operation closure to simply assert that a value matches a specific state for certain fields, ignoring others.

struct Counter {
  var count = 0
  var isOdd = false
  mutating func increment() {
    self.count += 1
    self.isOdd.toggle()
  }
}

var counter = Counter()

// Exhaustive: checks that count and isOdd changed as specified
expectDifference(counter) { 
  counter.increment() 
} changes: {
  $0.count = 1
  $0.isOdd = true
}

// Non-exhaustive: only asserts that count is 1
counter.increment()
expectDifference(counter) { 
  $0.count = 1
}

The expectDifference function allows you to assert that an asynchronous operation results in a difference between the current state and a previous state (or between two states). This is useful for testing side effects or state changes that occur within an async context.

// Example usage of the async version of expectDifference
// Note: The exact signature depends on the operation provided
await expectDifference(value, operation: { await performAsyncAction() })

The customDump(_:name:indent:maxDepth:) function provides a more readable and structured output than Swift's built-in dump. It optimizes for readability by:

• Mimicking Swift struct syntax for structs.
• Including indices for array elements (e.g., [0]: value).
• Using a compact, ordered format for dictionaries.
• Providing a simplified tree structure for enums and deeply nested types.

import CustomDump

struct User {
  var favoriteNumbers: [Int]
  var id: Int
  var name: String
}

let user = User(
  favoriteNumbers: [42, 1729],
  id: 2,
  name: "Blob"
)

customDump(user)