Update docs for Effect.timer and TestStore. (#220)

* Update docs for Effect.timer and TestStore.

* format

* update

* Update Sources/ComposableArchitecture/Effects/Timer.swift

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

* Update Sources/ComposableArchitecture/TestSupport/TestStore.swift

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

* wip

* Update TestStore.swift

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

Author: mluisbrown

Sources/ComposableArchitecture/Effects/Timer.swift

@@ -2,23 +2,72 @@ import Foundation
 import ReactiveSwift
 
 extension Effect where Value == Date, Error == Never {
-  /// Returns an effect that repeatedly emits the current time of the given
-  /// scheduler on the given interval.
-  ///
-  /// This effect serves as a testable alternative to `Timer.publish`, which
-  /// performs its work on a run loop, _not_ a scheduler.
-  ///
-  ///     struct TimerId: Hashable {}
-  ///
-  ///     switch action {
-  ///     case .startTimer:
-  ///       return Effect.timer(id: TimerId(), every: 1, on: environment.scheduler)
-  ///         .map { .timerUpdated($0) }
-  ///     case let .timerUpdated(date):
-  ///       state.date = date
-  ///       return .none
-  ///     case .stopTimer:
-  ///       return .cancel(id: TimerId())
+  /// Returns an effect that repeatedly emits the current time of the given scheduler on the given
+  /// interval.
+  ///
+  /// This is basically a wrapper around the ReactiveSwift `SignalProducer.timer` function
+  /// and which adds the the ability to be cancelled via the `id`.
+  ///
+  /// To start and stop a timer in your feature you can create the timer effect from an action
+  /// and then use the `.cancel(id:)` effect to stop the timer:
+  ///
+  ///     struct AppState {
+  ///       var count = 0
+  ///     }
+  ///
+  ///     enum AppAction {
+  ///       case startButtonTapped, stopButtonTapped, timerTicked
+  ///     }
+  ///
+  ///     struct AppEnvironment {
+  ///       var mainQueue: AnySchedulerOf<DispatchQueue>
+  ///     }
+  ///
+  ///     let appReducer = Reducer<AppState, AppAction, AppEnvironment> { state, action, env in
+  ///       struct TimerId: Hashable {}
+  ///
+  ///       switch action {
+  ///       case .startButtonTapped:
+  ///         return Effect.timer(id: TimerId(), every: 1, on: env.mainQueue)
+  ///           .map { _ in .timerTicked }
+  ///
+  ///       case .stopButtonTapped:
+  ///         return .cancel(id: TimerId())
+  ///
+  ///       case let .timerTicked:
+  ///         state.count += 1
+  ///         return .none
+  ///     }
+  ///
+  /// Then to test the timer in this feature you can use a test scheduler to advance time:
+  ///
+  ///   func testTimer() {
+  ///     let scheduler = TestScheduler()
+  ///
+  ///     let store = TestStore(
+  ///       initialState: .init(),
+  ///       reducer: appReducer,
+  ///       envirnoment: .init(
+  ///         mainQueue: scheduler
+  ///       )
+  ///     )
+  ///
+  ///     store.assert(
+  ///       .send(.startButtonTapped),
+  ///
+  ///       .do { scheduler.advance(by: .seconds(1)) },
+  ///       .receive(.timerTicked) { $0.count = 1 },
+  ///
+  ///       .do { scheduler.advance(by: .seconds(5)) },
+  ///       .receive(.timerTicked) { $0.count = 2 },
+  ///       .receive(.timerTicked) { $0.count = 3 },
+  ///       .receive(.timerTicked) { $0.count = 4 },
+  ///       .receive(.timerTicked) { $0.count = 5 },
+  ///       .receive(.timerTicked) { $0.count = 6 },
+  ///
+  ///       .send(.stopButtonTapped)
+  ///     )
+  ///   }
   ///
   /// - Parameters:
   ///   - interval: The time interval on which to publish events. For example, a value of `0.5`

Sources/ComposableArchitecture/TestSupport/TestStore.swift

@@ -4,20 +4,55 @@
 
   /// A testable runtime for a reducer.
   ///
+  /// This object aids in writing expressive and exhaustive tests for features built in the
+  /// Composable Architecture. It allows you to send a sequence of actions to the store, and each
+  /// step of the way you must assert exactly how state changed, and how effect emissions were fed
+  /// back into the system.
+  ///
+  /// There are multiple ways the test store forces you to exhaustively assert on how your feature
+  /// behaves:
+  ///
+  /// * After each action is sent you must describe precisely how the state changed from before the
+  ///   action was sent to after it was sent.
+  ///
+  ///   If even the smallest piece of data differs the test will fail. This guarantees that you are
+  ///   proving you know precisely how the state of the system changes.
+  ///
+  /// * Sending an action can sometimes cause an effect to be executed, and if that effect emits an
+  ///   action that is fed back into the system, you **must** explicitly assert that you expect to
+  ///   receive that action from the effect, _and_ you must assert how state changed as a result.
+  ///
+  ///   If you try to send another action before you have handled all effect emissions the assertion
+  ///   will fail. This guarantees that you do not accidentally forget about an effect emission, and
+  ///   that the sequence of steps you are describing will mimic how the application behaves in
+  ///   reality.
+  ///
+  /// * All effects must complete by the time the assertion has finished running the steps you
+  ///   specify.
+  ///
+  ///   If at the end of the assertion there is still an in-flight effect running, the assertion
+  ///   will fail. This helps exhaustively prove that you know what effects are in flight and forces
+  ///   you to prove that effects will not cause any future changes to your state.
+  ///
   /// For example, given a simple counter reducer:
   ///
+  ///     struct CounterState {
+  ///       var count = 0
+  ///     }
+  ///
   ///     enum CounterAction: Equatable {
   ///       case decrementButtonTapped
   ///       case incrementButtonTapped
   ///     }
   ///
-  ///     let counterReducer = Reducer<Int, CounterAction, Void> { count, action, _ in
+  ///     let counterReducer = Reducer<CounterState, CounterAction, Void> { state, action, _ in
   ///       switch action {
   ///       case .decrementButtonTapped:
-  ///         count -= 1
+  ///         state.count -= 1
   ///         return .none
+  ///
   ///       case .incrementButtonTapped:
-  ///         count += 1
+  ///         state.count += 1
   ///         return .none
   ///       }
   ///     }
@@ -27,50 +62,56 @@
   ///     class CounterTests: XCTestCase {
   ///       func testCounter() {
   ///         let store = TestStore(
-  ///           initialState: 0,                // GIVEN counter state of 0
+  ///           initialState: .init(count: 0),  // GIVEN counter state of 0
   ///           reducer: counterReducer,
   ///           environment: ()
   ///         )
   ///
   ///         store.assert(
   ///           .send(.incrementButtonTapped) { // WHEN the increment button is tapped
-  ///             $0 = 1                        // THEN the count should be 1
+  ///             $0.count = 1                  // THEN the count should be 1
   ///           }
   ///         )
   ///       }
   ///     }
   ///
-  /// For a more complex example, including timing and effects, consider the following bare-bones
-  /// search feature:
+  /// Note that in the trailing closure of `.send(.incrementButtonTapped)` we are given a single
+  /// mutable value of the state before the action was sent, and it is our job to mutate the value
+  /// to match the state after the action was sent. In this case the `count` field changes to `1`.
+  ///
+  /// For a more complex example, consider the following bare-bones search feature that uses the
+  /// `.debounce` operator to wait for the user to stop typing before making a network request:
   ///
   ///     struct SearchState: Equatable {
   ///       var query = ""
   ///       var results: [String] = []
   ///     }
+  ///
   ///     enum SearchAction: Equatable {
   ///       case queryChanged(String)
   ///       case response([String])
   ///     }
+  ///
   ///     struct SearchEnvironment {
   ///       var mainQueue: DateScheduler
   ///       var request: (String) -> Effect<[String], Never>
   ///     }
-  ///     let searchReducer = Reducer<
-  ///       SearchState, SearchAction, SearchEnvironment
-  ///     > { state, action, environment in
   ///
-  ///       // A local identifier for debouncing and canceling the search request effect.
-  ///       struct SearchId: Hashable {}
+  ///     let searchReducer = Reducer<SearchState, SearchAction, SearchEnvironment> {
+  ///       state, action, environment in
   ///
-  ///       switch action {
-  ///       case let .queryChanged(query):
-  ///         state.query = query
-  ///         return environment.request(self.query)
-  ///           .debounce(id: SearchId(), interval: 0.5, scheduler: environment.mainQueue)
-  ///       case let .response(results):
-  ///         state.results = results
-  ///         return .none
-  ///       }
+  ///         struct SearchId: Hashable {}
+  ///
+  ///         switch action {
+  ///         case let .queryChanged(query):
+  ///           state.query = query
+  ///           return environment.request(self.query)
+  ///             .debounce(id: SearchId(), interval: 0.5, scheduler: environment.mainQueue)
+  ///
+  ///         case let .response(results):
+  ///           state.results = results
+  ///           return .none
+  ///         }
   ///     }
   ///
   /// It can be fully tested by controlling the environment's scheduler and effect:
@@ -82,8 +123,7 @@
   ///       initialState: SearchState(),
   ///       reducer: searchReducer,
   ///       environment: SearchEnvironment(
-  ///         // Wrap the test scheduler in a type-erased scheduler
-  ///         mainQueue: scheduler.eraseToAnyScheduler(),
+  ///         mainQueue: scheduler,
   ///         // Simulate a search response with one item
   ///         request: { _ in Effect(value: ["Composable Architecture"]) }
   ///       )
@@ -94,22 +134,31 @@
   ///         // Assert that state updates accordingly
   ///         $0.query = "c"
   ///       },
+  ///
   ///       // Advance the scheduler by a period shorter than the debounce
   ///       .do { scheduler.advance(by: .millseconds(250)) },
+  ///
   ///       // Change the query again
   ///       .send(.searchFieldChanged("co") {
   ///         $0.query = "co"
   ///       },
+  ///
   ///       // Advance the scheduler by a period shorter than the debounce
   ///       .do { scheduler.advance(by: .millseconds(250)) },
   ///       // Advance the scheduler to the debounce
   ///       .do { scheduler.advance(by: .millseconds(250)) },
+  ///
   ///       // Assert that the expected response is received
   ///       .receive(.response(["Composable Architecture"])) {
   ///         // Assert that state updates accordingly
   ///         $0.results = ["Composable Architecture"]
   ///       }
   ///     )
+  ///
+  /// This test is proving that the debounced network requests are correctly canceled when we do not
+  /// wait longer than the 0.5 seconds, because if it wasn't and it delivered an action when we did
+  /// not expect it would cause a test failure.
+  ///
   public final class TestStore<State, LocalState, Action: Equatable, LocalAction, Environment> {
     private var environment: Environment
     private let fromLocalAction: (LocalAction) -> Action