Test Store documentation updates (#1129)

Author: stephencelis

Sources/ComposableArchitecture/Internal/Deprecations.swift

@@ -134,10 +134,10 @@ extension Reducer {
       func assert(step: Step) {
         switch step.type {
         case let .send(action, update):
-          self.send(action, file: step.file, line: step.line, update)
+          self.send(action, update, file: step.file, line: step.line)
 
         case let .receive(expectedAction, update):
-          self.receive(expectedAction, file: step.file, line: step.line, update)
+          self.receive(expectedAction, update, file: step.file, line: step.line)
 
         case let .environment(work):
           if !self.receivedActions.isEmpty {

Sources/ComposableArchitecture/TestSupport/TestStore.swift

@@ -167,15 +167,24 @@
   /// not expect it would cause a test failure.
   ///
   public final class TestStore<State, LocalState, Action, LocalAction, Environment> {
+    /// The current environment.
+    ///
+    /// The environment can be modified throughout a test store's lifecycle in order to influence
+    /// how it produces effects.
     public var environment: Environment
 
+    /// The current state.
+    ///
+    /// When read from a trailing closure assertion in ``send`` or ``receive``, it will equal the
+    /// `inout` state passed to the closure.
+    public private(set) var state: State
+
     private let file: StaticString
     private let fromLocalAction: (LocalAction) -> Action
     private var line: UInt
     private var inFlightEffects: Set<LongLivingEffect> = []
     var receivedActions: [(action: Action, state: State)] = []
     private let reducer: Reducer<State, Action, Environment>
-    public private(set) var state: State
     private var store: Store<State, TestAction>!
     private let toLocalState: (State) -> LocalState
 
@@ -332,11 +341,19 @@
   }
 
   extension TestStore where LocalState: Equatable {
+    /// Sends an action to the store and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action.
+    ///   - updateExpectingResult: A closure that asserts state changed by sending the action to the
+    ///     store. The mutable state sent to this closure must be modified to match the state of the
+    ///     store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
     public func send(
       _ action: LocalAction,
+      _ updateExpectingResult: ((inout LocalState) throws -> Void)? = nil,
       file: StaticString = #file,
-      line: UInt = #line,
-      _ update: ((inout LocalState) throws -> Void)? = nil
+      line: UInt = #line
     ) {
       if !self.receivedActions.isEmpty {
         var actions = ""
@@ -361,7 +378,7 @@
 
         try self.expectedStateShouldChange(
           expected: &expectedState,
-          update: update,
+          modify: updateExpectingResult,
           file: file,
           line: line
         )
@@ -381,19 +398,20 @@
 
     private func expectedStateShouldChange(
       expected: inout LocalState,
-      update: ((inout LocalState) throws -> Void)? = nil,
+      modify: ((inout LocalState) throws -> Void)? = nil,
       file: StaticString,
       line: UInt
     ) throws {
-      guard let update = update else { return }
+      guard let modify = modify else { return }
       let current = expected
-      try update(&expected)
+      try modify(&expected)
       if expected == current {
         XCTFail(
           """
-          Expected to modify the expected state, but no change occurred.
+          Expected state to change, but no change occurred.
 
-          Ensure that the state was modified or remove the closure to assert no change.
+          The trailing closure made no observable modifications to state. If no change to state is \
+          expected, omit the trailing closure.
           """,
           file: file, line: line
         )
@@ -432,11 +450,19 @@
   }
 
   extension TestStore where LocalState: Equatable, Action: Equatable {
+    /// Asserts an action was received from an effect and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - expectedAction: An action expected from an effect.
+    ///   - updateExpectingResult: A closure that asserts state changed by sending the action to the
+    ///     store. The mutable state sent to this closure must be modified to match the state of the
+    ///     store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
     public func receive(
       _ expectedAction: Action,
+      _ updateExpectingResult: ((inout LocalState) throws -> Void)? = nil,
       file: StaticString = #file,
-      line: UInt = #line,
-      _ update: ((inout LocalState) throws -> Void)? = nil
+      line: UInt = #line
     ) {
       guard !self.receivedActions.isEmpty else {
         XCTFail(
@@ -473,7 +499,7 @@
       do {
         try self.expectedStateShouldChange(
           expected: &expectedState,
-          update: update,
+          modify: updateExpectingResult,
           file: file,
           line: line
         )