CombineExpectations

CombineExpectations streamlines testing Combine publishers by reducing the boilerplate required when using XCTestExpectation.

Core Workflow

1. Record: Call .record() on a publisher to create a recorder object.
2. Wait or Get: Use wait(for:timeout:description:) to asynchronously wait for a specific state (like elements being emitted or the publisher finishing), or use .get() for synchronous retrieval if the expectation is already met.
3. Assert: Use standard XCTAssert methods on the returned values.

Behavior Rules

• Timeouts: The test fails if an expectation is not fulfilled within the specified timeout.
• Errors: If a publisher completes with a failure, the wait method throws that publisher error.
• Immediate Return: The wait method returns immediately if the expectation has already reached the desired state.
• Multiple Waits: You can call wait multiple times on the same recorder to step through a publisher's lifecycle (e.g., waiting for the first element, then the second, then completion).

import XCTest
import CombineExpectations

class PublisherTests: XCTestCase {
    func testElements() throws {
        let publisher = ...
        let recorder = publisher.record()
        
        // Wait for a publisher expectation
        let elements = try wait(for: recorder.elements, timeout: ..., description: "Elements")
        
        XCTAssertEqual(elements, ["Hello", "World!"])
    }
}

The recorder.recording expectation waits for the recorded publisher to complete and returns the full Record.Recording object.

Key Behaviors:

• Return Value: Returns a Record.Recording containing the output (array of elements) and the completion status.
• Error Handling: Throws RecordingError.notCompleted if the publisher does not complete within the timeout.

Use this when you need to inspect both the emitted values and the final completion status (success or failure) in a single assertion.

// SUCCESS: no timeout, no error
func testArrayPublisherRecording() throws {
    let publisher = ["foo", "bar", "baz"].publisher
    let recorder = publisher.record()
    let recording = try wait(for: recorder.recording, timeout: ...)
    XCTAssertEqual(recording.output, ["foo", "bar", "baz"])
    if case let .failure(error) = recording.completion {
        XCTFail("Unexpected error \(error)")
    }
}

The recorder.availableElements expectation waits for the expectation to expire or for the recorded publisher to complete.

Key Behaviors:

• Timeout Behavior: Unlike most other expectations, availableElements does not make a test fail on timeout expiration. It simply returns the array of elements published up to that point.
• Error Handling: If the publisher fails (emits an error) before the expectation expires, the publisher's error is thrown.

Use this when you want to assert on whatever data has arrived within a specific timeframe without requiring the publisher to finish.

// SUCCESS: no timeout, no error
func testTimerPublishesIncreasingDates() throws {
    let publisher = Timer.publish(every: 0.01, on: .main, in: .common).autoconnect()
    let recorder = publisher.record()
    let dates = try wait(for: recorder.availableElements, timeout: ...)
    XCTAssertEqual(dates.sorted(), dates)
}

The recorder.next(count) expectation waits for the recorded publisher to emit a specific number of elements (count), or to complete.

Key Behaviors:

• Return Value: Returns an array containing exactly count elements.
• Error Handling:
  • Throws RecordingError.notEnoughElements if the publisher completes before emitting the requested count.
  • Throws the publisher's error if it fails before the count is met.

Use this to verify that a publisher emits a specific batch of values.

// SUCCESS: no timeout, no error
func testArrayOfThreeElementsPublishesTwoThenOneElement() throws {
    let publisher = ["foo", "bar", "baz"].publisher
    let recorder = publisher.record()
    
    var elements = try wait(for: recorder.next(2), timeout: ...)
    XCTAssertEqual(elements, ["foo", "bar"])
    
    elements = try wait(for: recorder.next(1), timeout: ...)
    XCTAssertEqual(elements, ["baz"])
}

The recorder.prefix(maxLength) expectation waits for the recorded publisher to emit up to maxLength elements, or to complete.

Key Behaviors:

• Return Value: Returns an array of received elements. This array contains at most maxLength elements, but may contain fewer if the publisher completes early.
• Error Handling: Throws the publisher's error if it fails before maxLength elements are published.
• Inversion: Can be used with .inverted to assert that no more than a certain number of elements are published.

Use this when you want to capture a subset of a stream without requiring the stream to reach a specific count or complete.

// SUCCESS: no timeout, no error
func testArrayOfThreeElementsPublishesTwoFirstElementsWithoutError() throws {
    let publisher = ["foo", "bar", "baz"].publisher
    let recorder = publisher.record()
    let elements = try wait(for: recorder.prefix(2), timeout: ...)
    XCTAssertEqual(elements, ["foo", "bar"])
}