New materialize() operator over BlockingObservable

Documentation/UnitTests.md

@@ -86,7 +86,9 @@ It's easy to define `RxTests` extensions so you can write your tests in a readab
 
 It is also possible to write integration tests by using `RxBlocking` operators.
 
-Importing operators from `RxBlocking` library will enable blocking the current thread and wait for sequence results.
+Importing operators from the `RxBlocking` library will enable blocking the current thread and wait for sequence results.
+
+A simple way to test the result of your sequence is using the `toArray` method. It will return an array of all elements emitted once a sequence has completed successfully, or `throw` if an error caused the sequence to terminate.
 
 ```swift
 let result = try fetchResource(location)
@@ -95,3 +97,19 @@ let result = try fetchResource(location)
 
 XCTAssertEqual(result, expectedResult)
 ```
+
+Another option is to use the `materialize` operator which allows you to more granularly examine your sequence. It will return a `MaterializedSequenceResult` enumeration that could be either `.completed` along with the emitted elements if the sequence completed successfully, or `failed` if the sequence terminated with an error, along with the emitted error.
+
+```swift
+let result = try fetchResource(location)
+ .toBlocking()
+ .materialize()
+
+switch result {
+ case .completed:
+ XCTFail("Expected result to be complete eith error, but result was successful.")
+ case .failed(let elements, let error):
+ XCTAssertEqual(elements, expectedResult)
+ XCTAssertErrorEqual(error, expectedError)
+ }
+```

RxBlocking/BlockingObservable+Operators.swift

@@ -10,14 +10,20 @@
  import RxSwift
 #endif
 
+public enum MaterializedSequenceResult<T> {
+ case completed(elements: [T])
+ case failed(elements: [T], error: Error)
+}
+
 extension BlockingObservable {
  /// Blocks current thread until sequence terminates.
  ///
  /// If sequence terminates with error, terminating error will be thrown.
  ///
  /// - returns: All elements of sequence.
  public func toArray() throws -> [E] {
- return try convertToArray()
+ let results = materializeResult()
+ return try elementsOrThrow(results)
  }
 }
 
@@ -28,7 +34,8 @@ extension BlockingObservable {
  ///
  /// - returns: First element of sequence. If sequence is empty `nil` is returned.
  public func first() throws -> E? {
- return try convertToArray(max: 1).first
+ let results = materializeResult(max: 1)
+ return try elementsOrThrow(results).first
  }
 }
 
@@ -39,7 +46,8 @@ extension BlockingObservable {
  ///
  /// - returns: Last element in the sequence. If sequence is empty `nil` is returned.
  public func last() throws -> E? {
- return try convertToArray().last
+ let results = materializeResult()
+ return try elementsOrThrow(results).last
  }
 }
 
@@ -60,7 +68,8 @@ extension BlockingObservable {
  /// - parameter predicate: A function to test each source element for a condition.
  /// - returns: Returns the only element of an sequence that satisfies the condition in the predicate, and reports an error if there is not exactly one element in the sequence.
  public func single(_ predicate: @escaping (E) throws -> Bool) throws -> E? {
- let elements = try convertToArray(max: 2, predicate: predicate)
+ let results = materializeResult(max: 2, predicate: predicate)
+ let elements = try elementsOrThrow(results)
 
  switch elements.count {
  case 0:
@@ -74,9 +83,19 @@ extension BlockingObservable {
 }
 
 extension BlockingObservable {
- fileprivate func convertToArray(max: Int? = nil, predicate: @escaping (E) throws -> Bool = { _ in true }) throws -> [E] {
+ /// Blocks current thread until sequence terminates.
+ ///
+ /// The sequence is materialized as a result type capturing how the sequence terminated (completed or error), along with any elements up to that point.
+ ///
+ /// - returns: On completion, returns the list of elements in the sequence. On error, returns the list of elements up to that point, along with the error itself.
+ public func materialize() -> MaterializedSequenceResult<E> {
+ return materializeResult()
+ }
+}
+
+extension BlockingObservable {
+ fileprivate func materializeResult(max: Int? = nil, predicate: @escaping (E) throws -> Bool = { _ in true }) -> MaterializedSequenceResult<E> {
  var elements: [E] = Array<E>()
-
  var error: Swift.Error?
 
  let lock = RunLoopLock(timeout: timeout)
@@ -127,9 +146,18 @@ extension BlockingObservable {
  }
 
  if let error = error {
- throw error
+ return MaterializedSequenceResult.failed(elements: elements, error: error)
  }
 
- return elements
+ return MaterializedSequenceResult.completed(elements: elements)
+ }
+
+ fileprivate func elementsOrThrow(_ results: MaterializedSequenceResult<E>) throws -> [E] {
+ switch results {
+ case .failed(_, let error):
+ throw error
+ case .completed(let elements):
+ return elements
+ }
  }
 }

RxBlocking/README.md

@@ -23,6 +23,10 @@ extension BlockingObservable {
  public func single() throws -> E? {}
  public func single(_ predicate: @escaping (E) throws -> Bool) throws -> E? {}
 }
+
+extension BlockingObservable {
+ public func materialize() -> MaterializedSequenceResult<E>
+}
 ```
 
 

Sources/AllTestz/main.swift

@@ -238,6 +238,10 @@ final class ObservableBlockingTest_ : ObservableBlockingTest, RxTestCase {
  ("testSingle_independent", ObservableBlockingTest.testSingle_independent),
  ("testSingle_timeout", ObservableBlockingTest.testSingle_timeout),
  ("testSinglePredicate_timeout", ObservableBlockingTest.testSinglePredicate_timeout),
+ ("testMaterialize_empty", ObservableBlockingTest.testMaterialize_empty),
+ ("testMaterialize_empty_fail", ObservableBlockingTest.testMaterialize_empty_fail),
+ ("testMaterialize_someData", ObservableBlockingTest.testMaterialize_someData),
+ ("testMaterialize_someData_fail", ObservableBlockingTest.testMaterialize_someData_fail),
  ] }
 }
 

Tests/RxBlockingTests/Observable+BlockingTest.swift

@@ -337,3 +337,54 @@ extension ObservableBlockingTest {
  }
  }
 }
+
+// materialize
+
+extension ObservableBlockingTest {
+ func testMaterialize_empty() {
+ let result = Observable<Int>.empty().toBlocking().materialize()
+
+ switch result {
+ case .completed(let elements):
+ XCTAssertEqual(elements, [])
+ case .failed:
+ XCTFail("Expected result to be complete successfully, but result was failed.")
+ }
+ }
+
+ func testMaterialize_empty_fail() {
+ let result = Observable<Int>.error(testError).toBlocking().materialize()
+
+ switch result {
+ case .completed:
+ XCTFail("Expected result to be complete eith error, but result was successful.")
+ case .failed(let elements, let error):
+ XCTAssertEqual(elements, [])
+ XCTAssertErrorEqual(error, testError)
+ }
+ }
+
+ func testMaterialize_someData() {
+ let result = Observable.of(42, 43, 44, 45).toBlocking().materialize()
+
+ switch result {
+ case .completed(let elements):
+ XCTAssertEqual(elements, [42, 43, 44, 45])
+ case .failed:
+ XCTFail("Expected result to be complete successfully, but result was failed.")
+ }
+ }
+
+ func testMaterialize_someData_fail() {
+ let sequence = Observable.concat(Observable.of(42, 43, 44, 45), Observable<Int>.error(testError))
+ let result = sequence.toBlocking().materialize()
+
+ switch result {
+ case .completed:
+ XCTFail("Expected result to be complete eith error, but result was successful.")
+ case .failed(let elements, let error):
+ XCTAssertEqual(elements, [42, 43, 44, 45])
+ XCTAssertErrorEqual(error, testError)
+ }
+ }
+}