Add XCTAssertDifference for exhaustively testing changes to values

Sources/CustomDump/XCTAssertDifference.swift

@@ -0,0 +1,95 @@
+import XCTestDynamicOverlay
+
+/// Asserts that two values have no difference.
+///
+/// Similar to `XCTAssertEqual`, but that function uses either `TextOutputStreamable`,
+/// `CustomStringConvertible` or `CustomDebugStringConvertible` in order to display a failure
+/// message:
+///
+/// ```swift
+/// XCTAssertEqual(user1, user2)
+/// ```
+/// ```text
+/// XCTAssertEqual failed: ("User(id: 42, name: "Blob")") is not equal to ("User(id: 42, name: "Blob, Esq.")")
+/// ```
+///
+/// `XCTAssertNoDifference` uses the output of ``diff(_:_:format:)`` to display a failure message,
+/// which helps highlight the differences between the given values:
+///
+/// ```swift
+/// XCTAssertNoDifference(user1, user2)
+/// ```
+/// ```text
+/// XCTAssertNoDifference failed: …
+///
+///     User(
+///       id: 42,
+///   -   name: "Blob"
+///   +   name: "Blob, Esq."
+///     )
+///
+/// (First: -, Second: +)
+/// ```
+///
+/// - Parameters:
+///   - expression1: An expression of type `T`, where `T` is `Equatable`.
+///   - expression2: A second expression of type `T`, where `T` is `Equatable`.
+///   - message: An optional description of a failure.
+///   - file: The file where the failure occurs. The default is the filename of the test case where
+///     you call this function.
+///   - line: The line number where the failure occurs. The default is the line number where you
+///     call this function.
+@available(iOS 13, macOS 10.15, tvOS 13, watchOS 6, *)
+public func XCTAssertDifference<T>(
+  _ expression: @autoclosure () throws -> T,
+  _ message: @autoclosure () -> String = "",
+  execute: () throws -> Void,
+  updateExpectingResult: (inout T) throws -> Void,
+  file: StaticString = #filePath,
+  line: UInt = #line
+) where T: Equatable {
+  do {
+    var expression1 = try expression()
+    try updateExpectingResult(&expression1)
+    try execute()
+    let expression2 = try expression()
+    let message = message()
+    guard expression1 != expression2 else { return }
+    let format = DiffFormat.proportional
+    guard let difference = diff(expression1, expression2, format: format)
+    else {
+      XCTFail(
+        """
+        XCTAssertDifference failed: An unexpected failure occurred. Please report the issue to https://github.com/pointfreeco/swift-custom-dump …
+
+        ("\(expression1)" is not equal to ("\(expression2)")
+
+        But no difference was detected.
+        """,
+        file: file,
+        line: line
+      )
+      return
+    }
+    let failure = """
+      XCTAssertDifference failed: …
+
+      \(difference.indenting(by: 2))
+
+      (Expected: \(format.first), Actual: \(format.second))
+      """
+    XCTFail(
+      "\(failure)\(message.isEmpty ? "" : " - \(message)")",
+      file: file,
+      line: line
+    )
+  } catch {
+    XCTFail(
+      """
+      XCTAssertDifference failed: threw error "\(error)"
+      """,
+      file: file,
+      line: line
+    )
+  }
+}

Tests/CustomDumpTests/XCTAssertDifferencesTests.swift

@@ -0,0 +1,45 @@
+import CustomDump
+import XCTest
+
+@available(iOS 13, macOS 10.15, tvOS 13, watchOS 6, *)
+class XCTAssertDifferencesTests: XCTestCase {
+  func testXCTAssertDifference() {
+    var user = User(id: 42, name: "Blob")
+    func increment<Value>(_ root: inout Value, at keyPath: WritableKeyPath<Value, Int>) {
+      root[keyPath: keyPath] += 1
+    }
+
+    XCTAssertDifference(user) {
+      increment(&user, at: \.id)
+    } updateExpectingResult: {
+      $0.id = 43
+    }
+  }
+
+  #if compiler(>=5.4) && (os(iOS) || os(macOS) || os(tvOS) || os(watchOS))
+    func testXCTAssertDifference_Failure() {
+      var user = User(id: 42, name: "Blob")
+      func increment<Value>(_ root: inout Value, at keyPath: WritableKeyPath<Value, Int>) {
+        root[keyPath: keyPath] += 1
+      }
+
+      XCTExpectFailure()
+
+      XCTAssertDifference(user) {
+        increment(&user, at: \.id)
+      } updateExpectingResult: {
+        $0.id = 44
+      }
+    }
+
+    func testXCTAssertNoDifference() {
+      XCTExpectFailure()
+
+      let user = User(id: 42, name: "Blob")
+      var other = user
+      other.name += " Sr."
+
+      XCTAssertNoDifference(user, other)
+    }
+  #endif
+}