Add TestStore.assert. (#2123)

* Add TestStore.assert.

* wip

* Update Sources/ComposableArchitecture/TestStore.swift

Co-authored-by: Stephen Celis <[email protected]>

* Update Sources/ComposableArchitecture/Documentation.docc/Extensions/TestStore.md

Co-authored-by: Stephen Celis <[email protected]>

* fix tests

---------

Co-authored-by: Stephen Celis <[email protected]>

Author: mbrandonw

Sources/ComposableArchitecture/Documentation.docc/Extensions/TestStore.md

@@ -20,6 +20,7 @@
 - ``receive(_:timeout:assert:file:line:)-1rwdd``
 - ``receive(_:timeout:assert:file:line:)-8xkqt``
 - ``receive(_:timeout:assert:file:line:)-2ju31``
+- ``assert(_:file:line:)``
 - ``finish(timeout:file:line:)``
 - ``TestStoreTask``
 

Sources/ComposableArchitecture/TestStore.swift

@@ -1053,6 +1053,56 @@ extension TestStore where ScopedState: Equatable {
     return .init(rawValue: task, timeout: self.timeout)
   }
 
+  /// Assert against the current state of the store.
+  ///
+  /// The trailing closure provided is given a mutable argument that represents the current state,
+  /// and you can provide any mutations you want to the state. If your mutations cause the argument
+  /// to differ from the current state of the test store, a test failure will be triggered.
+  ///
+  /// This tool is most useful in non-exhaustive test stores (see
+  /// <doc:Testing#Non-exhaustive-testing>), which allow you to assert on a subset of the things
+  /// happening inside your features. For example, you can send an action in a child feature
+  /// without asserting on how many changes in the system, and then tell the test store to
+  /// ``finish(timeout:file:line:)`` by executing all of its effects and receiving all actions.
+  /// After that is done you can assert on the final state of the store:
+  ///
+  /// ```swift
+  /// store.exhaustivity = .off
+  /// await store.send(.child(.closeButtonTapped))
+  /// await store.finish()
+  /// store.assert {
+  ///   $0.child = nil
+  /// }
+  /// ```
+  ///
+  /// > Note: This helper is only intended to be used with non-exhaustive test stores. It is not
+  /// needed in exhaustive test stores since any assertion you may make inside the trailing closure
+  /// has already been handled by a previous `send` or `receive`.
+  ///
+  /// - Parameters:
+  ///   - updateStateToExpectedResult: A closure that asserts against the current state of the test
+  ///   store.
+  @MainActor
+  public func assert(
+    _ updateStateToExpectedResult: ((inout ScopedState) throws -> Void)?,
+    file: StaticString = #file,
+    line: UInt = #line
+  ) {
+    let expectedState = self.toScopedState(self.state)
+    let currentState = self.reducer.state
+    do {
+      try self.expectedStateShouldMatch(
+        expected: expectedState,
+        actual: self.toScopedState(currentState),
+        updateStateToExpectedResult: updateStateToExpectedResult,
+        file: file,
+        line: line
+      )
+    } catch {
+      XCTFail("Threw error: \(error)", file: file, line: line)
+    }
+  }
+
   /// Sends an action to the store and asserts when state changes.
   ///
   /// This method returns a ``TestStoreTask``, which represents the lifecycle of the effect started

Tests/ComposableArchitectureTests/TestStoreTests.swift

@@ -431,6 +431,62 @@ final class TestStoreTests: BaseTCATestCase {
       $0 = 42
     }
   }
+
+  #if DEBUG
+  func testAssert_ExhaustiveTestStore() async {
+    let store = TestStore(initialState: 0) {
+      EmptyReducer<Int, Void>()
+    }
+
+    XCTExpectFailure {
+      store.assert {
+        $0 = 0
+      }
+    } issueMatcher: {
+      $0.compactDescription == """
+        Expected state to change, but no change occurred.
+
+        The trailing closure made no observable modifications to state. If no change to state is \
+        expected, omit the trailing closure.
+        """
+    }
+  }
+  #endif
+
+  func testAssert_NonExhaustiveTestStore() async {
+    let store = TestStore(initialState: 0) {
+      EmptyReducer<Int, Void>()
+    }
+    store.exhaustivity = .off
+
+    store.assert {
+      $0 = 0
+    }
+  }
+
+  #if DEBUG
+  func testAssert_NonExhaustiveTestStore_Failure() async {
+    let store = TestStore(initialState: 0) {
+      EmptyReducer<Int, Void>()
+    }
+    store.exhaustivity = .off
+
+    XCTExpectFailure {
+      store.assert {
+        $0 = 1
+      }
+    } issueMatcher: {
+      $0.compactDescription == """
+        A state change does not match expectation: …
+
+            − 1
+            + 0
+
+        (Expected: −, Actual: +)
+        """
+    }
+  }
+  #endif
 }
 
 private struct Client: DependencyKey {