Rename expect(worker:producingOutput:) to be more clear about what it is asserting (#323)

amayers · web-flow · commit 01389e288c1e · 2025-04-08T11:30:33.000-05:00
When I first saw tests that used this function, I thought it was
asserting that the `worker` passed in, matches the `workflow.worker`
(which it does do), and that it was asserting that `producingOutput ==
workflow.worker.output` (which it does NOT do). Instead, neither of the
workers are ever run. The `producingOutput` is used as mock output. So
renaming these to make it more clear what is going on.


## Checklist

- [x] Unit Tests
- [x] UI Tests
- [x] Snapshot Tests (iOS only)
- [x] I have made corresponding changes to the documentation
diff --git a/Samples/TicTacToe/Tests/AuthenticationWorkflowTests.swift b/Samples/TicTacToe/Tests/AuthenticationWorkflowTests.swift
@@ -218,13 +218,11 @@ class AuthenticationWorkflowTests: XCTestCase {
                     onLoginTapped: {}
                 )
             )
-            .expect(
-                worker: AuthenticationWorkflow.AuthorizingEmailPasswordWorker(
-                    authenticationService: authenticationService,
-                    email: "reza@example.com",
-                    password: "password"
-                )
-            )
+            .expectWorker(AuthenticationWorkflow.AuthorizingEmailPasswordWorker(
+                authenticationService: authenticationService,
+                email: "reza@example.com",
+                password: "password"
+            ))
             .render { screen in
                 XCTAssertNil(screen.alert)
             }
@@ -252,13 +250,11 @@ class AuthenticationWorkflowTests: XCTestCase {
                     onLoginTapped: {}
                 )
             )
-            .expect(
-                worker: AuthenticationWorkflow.AuthorizingTwoFactorWorker(
-                    authenticationService: authenticationService,
-                    intermediateToken: "intermediateSession",
-                    twoFactorCode: "twoFactorCode"
-                )
-            )
+            .expectWorker(AuthenticationWorkflow.AuthorizingTwoFactorWorker(
+                authenticationService: authenticationService,
+                intermediateToken: "intermediateSession",
+                twoFactorCode: "twoFactorCode"
+            ))
             .render { screen in
                 XCTAssertNil(screen.alert)
             }
diff --git a/Samples/Tutorial/Tutorial5.md b/Samples/Tutorial/Tutorial5.md
@@ -334,10 +334,7 @@ workflow
         producingRendering: ChildScreen(),
         producingOutput: .closed
     )
-    .expect(
-        worker: TestWorker(),
-        producingOutput: .finished
-    )
+    .expectWorker(TestWorker(), mockingOutput: .finished)
     .render { rendering in
         XCTAssertEqual("expected text on rendering", rendering.text)
     }
diff --git a/WorkflowCombine/Testing/WorkerTesting.swift b/WorkflowCombine/Testing/WorkerTesting.swift
@@ -21,29 +21,49 @@ import XCTest
 @testable import WorkflowCombine
 
 extension RenderTester {
-    /// Expect the given worker. It will be checked for `isEquivalent(to:)` with the requested worker.
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `worker`.
     ///
     /// - Parameters:
-    ///   - worker: The worker to be expected
-    ///   - producingOutput: An output that will be returned when this worker is requested, if any.
+    ///   - worker: The worker that we expect was created by the workflow. Will be compared using
+    ///             `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - producingOutput: The output to be used instead of actually running the worker.
+    ///                      If the workflow never tries to run the worker, then this won't be used.
     ///   - key: Key to expect this `Workflow` to be rendered with.
+    @available(*, deprecated, renamed: "expectedWorker(_:mockingOutput:key:file:line:)", message: "renamed")
     public func expect<ExpectedWorkerType: Worker>(
         worker: ExpectedWorkerType,
         producingOutput output: ExpectedWorkerType.Output? = nil,
         key: String = "",
         file: StaticString = #file, line: UInt = #line
+    ) -> RenderTester<WorkflowType> {
+        expectWorker(worker, mockingOutput: output, key: key, file: file, line: line)
+    }
+
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `expectedWorker`.
+    ///
+    /// - Parameters:
+    ///   - expectedWorker: The worker that we expect was created by the workflow. Will be compared using
+    ///                     `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - mockingOutput: The output to be used instead of actually running the worker.
+    ///                    If the workflow never tries to run the worker, then this won't be used.
+    ///   - key: Key to expect this `Workflow` to be rendered with.
+    public func expectWorker<ExpectedWorkerType: Worker>(
+        _ expectedWorker: ExpectedWorkerType,
+        mockingOutput output: ExpectedWorkerType.Output? = nil,
+        key: String = "",
+        file: StaticString = #file, line: UInt = #line
     ) -> RenderTester<WorkflowType> {
         expectWorkflow(
             type: WorkerWorkflow<ExpectedWorkerType>.self,
             key: key,
             producingRendering: (),
             producingOutput: output,
             assertions: { workflow in
-                guard !workflow.worker.isEquivalent(to: worker) else {
+                guard !workflow.worker.isEquivalent(to: expectedWorker) else {
                     return
                 }
                 XCTFail(
-                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(worker). Got: \(workflow.worker)",
+                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(expectedWorker). Got: \(workflow.worker)",
                     file: file,
                     line: line
                 )
diff --git a/WorkflowCombine/TestingTests/TestingTests.swift b/WorkflowCombine/TestingTests/TestingTests.swift
@@ -27,7 +27,7 @@ class WorkflowCombineTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(worker: TestWorker(input: "otherText"))
+            .expectWorker(TestWorker(input: "otherText"))
             .render { _ in }
     }
 
@@ -36,10 +36,7 @@ class WorkflowCombineTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(
-                worker: TestWorker(input: "otherText"),
-                producingOutput: "otherText"
-            )
+            .expectWorker(TestWorker(input: "otherText"), mockingOutput: "otherText")
             .render { _ in }
             .verifyState { state in
                 XCTAssertEqual(state, TestWorkflow.State(mode: .worker(input: "otherText"), output: "otherText"))
@@ -49,9 +46,7 @@ class WorkflowCombineTestingTests: XCTestCase {
     func test_worker_missing() {
         let tester = TestWorkflow()
             .renderTester()
-            .expect(
-                worker: TestWorker(input: "input")
-            )
+            .expectWorker(TestWorker(input: "input"))
 
         expectingFailure(#"Expected child workflow of type: WorkerWorkflow<TestWorker>, key: """#) {
             tester.render { _ in }
@@ -61,9 +56,7 @@ class WorkflowCombineTestingTests: XCTestCase {
     func test_worker_mismatch() {
         let tester = TestWorkflow()
             .renderTester(initialState: .init(mode: .worker(input: "test"), output: ""))
-            .expect(
-                worker: TestWorker(input: "not-test")
-            )
+            .expectWorker(TestWorker(input: "not-test"))
 
         expectingFailures([
             #"Workers of type TestWorker not equivalent. Expected: TestWorker(input: "not-test"). Got: TestWorker(input: "test")"#,
diff --git a/WorkflowConcurrency/Testing/WorkerTesting.swift b/WorkflowConcurrency/Testing/WorkerTesting.swift
@@ -21,17 +21,37 @@ import XCTest
 @testable import WorkflowConcurrency
 
 extension RenderTester {
-    /// Expect the given worker. It will be checked for `isEquivalent(to:)` with the requested worker.
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `worker`.
     ///
     /// - Parameters:
-    ///   - worker: The worker to be expected
-    ///   - producingOutput: An output that will be returned when this worker is requested, if any.
+    ///   - worker: The worker that we expect was created by the workflow. Will be compared using
+    ///             `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - producingOutput: The output to be used instead of actually running the worker.
+    ///                      If the workflow never tries to run the worker, then this won't be used.
     ///   - key: Key to expect this `Workflow` to be rendered with.
+    @available(*, deprecated, renamed: "expectedWorker(_:mockingOutput:key:file:line:)", message: "Renamed")
     public func expect<ExpectedWorkerType: Worker>(
         worker: ExpectedWorkerType,
         producingOutput output: ExpectedWorkerType.Output? = nil,
         key: String = "",
         file: StaticString = #file, line: UInt = #line
+    ) -> RenderTester<WorkflowType> {
+        expectWorker(worker, mockingOutput: output, key: key, file: file, line: line)
+    }
+
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `worker`.
+    ///
+    /// - Parameters:
+    ///   - worker: The worker that we expect was created by the workflow. Will be compared using
+    ///                     `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - mockingOutput: The output to be used instead of actually running the worker.
+    ///                    If the workflow never tries to run the worker, then this won't be used.
+    ///   - key: Key to expect this `Workflow` to be rendered with.
+    public func expectWorker<ExpectedWorkerType: Worker>(
+        _ worker: ExpectedWorkerType,
+        mockingOutput output: ExpectedWorkerType.Output? = nil,
+        key: String = "",
+        file: StaticString = #file, line: UInt = #line
     ) -> RenderTester<WorkflowType> {
         expectWorkflow(
             type: WorkerWorkflow<ExpectedWorkerType>.self,
diff --git a/WorkflowConcurrency/TestingTests/TestingTests.swift b/WorkflowConcurrency/TestingTests/TestingTests.swift
@@ -26,7 +26,7 @@ class WorkflowConcurrencyTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(worker: TestWorker(input: "otherText"))
+            .expectWorker(TestWorker(input: "otherText"))
             .render { _ in }
     }
 
@@ -35,10 +35,7 @@ class WorkflowConcurrencyTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(
-                worker: TestWorker(input: "otherText"),
-                producingOutput: "otherText"
-            )
+            .expectWorker(TestWorker(input: "otherText"), mockingOutput: "otherText")
             .render { _ in }
             .verifyState { state in
                 XCTAssertEqual(state, TestWorkflow.State(mode: .worker(input: "otherText"), output: "otherText"))
@@ -48,9 +45,7 @@ class WorkflowConcurrencyTestingTests: XCTestCase {
     func test_worker_missing() {
         let tester = TestWorkflow()
             .renderTester()
-            .expect(
-                worker: TestWorker(input: "input")
-            )
+            .expectWorker(TestWorker(input: "input"))
 
         expectingFailure(#"Expected child workflow of type: WorkerWorkflow<TestWorker>, key: """#) {
             tester.render { _ in }
@@ -60,9 +55,7 @@ class WorkflowConcurrencyTestingTests: XCTestCase {
     func test_worker_mismatch() {
         let tester = TestWorkflow()
             .renderTester(initialState: .init(mode: .worker(input: "test"), output: ""))
-            .expect(
-                worker: TestWorker(input: "not-test")
-            )
+            .expectWorker(TestWorker(input: "not-test"))
 
         expectingFailures([
             #"Workers of type TestWorker not equivalent. Expected: TestWorker(input: "not-test"). Got: TestWorker(input: "test")"#,
diff --git a/WorkflowReactiveSwift/Testing/WorkerTesting.swift b/WorkflowReactiveSwift/Testing/WorkerTesting.swift
@@ -21,29 +21,49 @@ import XCTest
 @testable import WorkflowReactiveSwift
 
 extension RenderTester {
-    /// Expect the given worker. It will be checked for `isEquivalent(to:)` with the requested worker.
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `worker`.
     ///
     /// - Parameters:
-    ///   - worker: The worker to be expected
-    ///   - producingOutput: An output that will be returned when this worker is requested, if any.
+    ///   - worker: The worker that we expect was created by the workflow. Will be compared using
+    ///             `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - producingOutput: The output to be used instead of actually running the worker.
+    ///                      If the workflow never tries to run the worker, then this won't be used.
     ///   - key: Key to expect this `Workflow` to be rendered with.
+    @available(*, deprecated, renamed: "expectedWorker(_:mockingOutput:key:file:line:)", message: "Renamed")
     public func expect<ExpectedWorkerType: Worker>(
         worker: ExpectedWorkerType,
         producingOutput output: ExpectedWorkerType.Output? = nil,
         key: String = "",
         file: StaticString = #file, line: UInt = #line
+    ) -> RenderTester<WorkflowType> {
+        expectWorker(worker, mockingOutput: output, key: key, file: file, line: line)
+    }
+
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `expectedWorker`.
+    ///
+    /// - Parameters:
+    ///   - expectedWorker: The worker that we expect was created by the workflow. Will be compared using
+    ///                     `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - mockingOutput: The output to be used instead of actually running the worker.
+    ///                    If the workflow never tries to run the worker, then this won't be used.
+    ///   - key: Key to expect this `Workflow` to be rendered with.
+    public func expectWorker<ExpectedWorkerType: Worker>(
+        _ expectedWorker: ExpectedWorkerType,
+        mockingOutput output: ExpectedWorkerType.Output? = nil,
+        key: String = "",
+        file: StaticString = #file, line: UInt = #line
     ) -> RenderTester<WorkflowType> {
         expectWorkflow(
             type: WorkerWorkflow<ExpectedWorkerType>.self,
             key: key,
             producingRendering: (),
             producingOutput: output,
             assertions: { workflow in
-                guard !workflow.worker.isEquivalent(to: worker) else {
+                guard !workflow.worker.isEquivalent(to: expectedWorker) else {
                     return
                 }
                 XCTFail(
-                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(worker). Got: \(workflow.worker)",
+                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(expectedWorker). Got: \(workflow.worker)",
                     file: file,
                     line: line
                 )
diff --git a/WorkflowReactiveSwift/TestingTests/TestingTests.swift b/WorkflowReactiveSwift/TestingTests/TestingTests.swift
@@ -27,7 +27,7 @@ class WorkflowReactiveSwiftTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(worker: TestWorker(input: "otherText"))
+            .expectWorker(TestWorker(input: "otherText"))
             .render { _ in }
     }
 
@@ -36,10 +36,7 @@ class WorkflowReactiveSwiftTestingTests: XCTestCase {
             .renderTester(initialState: .init(mode: .worker(input: "otherText"), output: ""))
 
         renderTester
-            .expect(
-                worker: TestWorker(input: "otherText"),
-                producingOutput: "otherText"
-            )
+            .expectWorker(TestWorker(input: "otherText"), mockingOutput: "otherText")
             .render { _ in }
             .verifyState { state in
                 XCTAssertEqual(state, TestWorkflow.State(mode: .worker(input: "otherText"), output: "otherText"))
@@ -49,9 +46,7 @@ class WorkflowReactiveSwiftTestingTests: XCTestCase {
     func test_worker_missing() {
         let tester = TestWorkflow()
             .renderTester()
-            .expect(
-                worker: TestWorker(input: "input")
-            )
+            .expectWorker(TestWorker(input: "input"))
 
         expectingFailure(#"Expected child workflow of type: WorkerWorkflow<TestWorker>, key: """#) {
             tester.render { _ in }
@@ -61,9 +56,7 @@ class WorkflowReactiveSwiftTestingTests: XCTestCase {
     func test_worker_mismatch() {
         let tester = TestWorkflow()
             .renderTester(initialState: .init(mode: .worker(input: "test"), output: ""))
-            .expect(
-                worker: TestWorker(input: "not-test")
-            )
+            .expectWorker(TestWorker(input: "not-test"))
 
         expectingFailures([
             #"Workers of type TestWorker not equivalent. Expected: TestWorker(input: "not-test"). Got: TestWorker(input: "test")"#,
diff --git a/WorkflowRxSwift/Testing/WorkerTesting.swift b/WorkflowRxSwift/Testing/WorkerTesting.swift
@@ -21,28 +21,49 @@ import XCTest
 @testable import WorkflowRxSwift
 
 extension RenderTester {
-    /// Expect the given worker. It will be checked for `isEquivalent(to:)` with the requested worker.
-
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `worker`.
+    ///
     /// - Parameters:
-    ///   - worker: The worker to be expected
-    ///   - output: An output that will be returned when this worker is requested, if any.
+    ///   - worker: The worker that we expect was created by the workflow. Will be compared using
+    ///             `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - producingOutput: The output to be used instead of actually running the worker.
+    ///                      If the workflow never tries to run the worker, then this won't be used.
+    ///   - key: Key to expect this `Workflow` to be rendered with.
+    @available(*, deprecated, renamed: "expectedWorker(_:mockingOutput:key:file:line:)", message: "Renamed")
     public func expect<ExpectedWorkerType: Worker>(
         worker: ExpectedWorkerType,
         producingOutput output: ExpectedWorkerType.Output? = nil,
         key: String = "",
         file: StaticString = #file, line: UInt = #line
+    ) -> RenderTester<WorkflowType> {
+        expectWorker(worker, mockingOutput: output, key: key, file: file, line: line)
+    }
+
+    /// Mock the given worker's output, and assert that the workflow's worker `isEquivalent(to:)` the `expectedWorker`.
+    ///
+    /// - Parameters:
+    ///   - expectedWorker: The worker that we expect was created by the workflow. Will be compared using
+    ///                     `isEquivalent(to:)` to assert that the workflow's worker matches.
+    ///   - mockingOutput: The output to be used instead of actually running the worker.
+    ///                    If the workflow never tries to run the worker, then this won't be used.
+    ///   - key: Key to expect this `Workflow` to be rendered with.
+    public func expectWorker<ExpectedWorkerType: Worker>(
+        _ expectedWorker: ExpectedWorkerType,
+        mockingOutput output: ExpectedWorkerType.Output? = nil,
+        key: String = "",
+        file: StaticString = #file, line: UInt = #line
     ) -> RenderTester<WorkflowType> {
         expectWorkflow(
             type: WorkerWorkflow<ExpectedWorkerType>.self,
             key: key,
             producingRendering: (),
             producingOutput: output,
             assertions: { workflow in
-                guard !workflow.worker.isEquivalent(to: worker) else {
+                guard !workflow.worker.isEquivalent(to: expectedWorker) else {
                     return
                 }
                 XCTFail(
-                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(worker). Got: \(workflow.worker)",
+                    "Workers of type \(ExpectedWorkerType.self) not equivalent. Expected: \(expectedWorker). Got: \(workflow.worker)",
                     file: file,
                     line: line
                 )
diff --git a/WorkflowRxSwift/TestingTests/TestingTests.swift b/WorkflowRxSwift/TestingTests/TestingTests.swift
diff --git a/WorkflowTesting/Sources/WorkflowRenderTester.swift b/WorkflowTesting/Sources/WorkflowRenderTester.swift

Original file line number	Diff line number	Diff line change
`@@ -334,10 +334,7 @@ workflow`
`334`	`334`	`producingRendering: ChildScreen(),`
`335`	`335`	`producingOutput: .closed`
`336`	`336`	`)`
`337`		`- .expect(`
`338`		`- worker: TestWorker(),`
`339`		`- producingOutput: .finished`
`340`		`- )`
	`337`	`+ .expectWorker(TestWorker(), mockingOutput: .finished)`
`341`	`338`	`.render { rendering in`
`342`	`339`	`XCTAssertEqual("expected text on rendering", rendering.text)`
`343`	`340`	`}`