io.reactivex.subscribers

Class TestSubscriber<T>

java.lang.Object

io.reactivex.subscribers.TestSubscriber<T>

Type Parameters:

T - the value type

All Implemented Interfaces:

Disposable, org.reactivestreams.Subscriber<T>, org.reactivestreams.Subscription

public class TestSubscriber<T>
extends java.lang.Object
implements org.reactivestreams.Subscriber<T>, org.reactivestreams.Subscription, Disposable

A subscriber that records events and allows making assertions about them.

You can override the onSubscribe, onNext, onError, onComplete, request and cancel methods but not the others (this is by design).

The TestSubscriber implements Disposable for convenience where dispose calls cancel.

When calling the default request method, you are requesting on behalf of the wrapped actual subscriber.

Constructor Summary

Constructors

Constructor and Description
TestSubscriber() Constructs a non-forwarding TestSubscriber with an initial request value of Long.MAX_VALUE.
TestSubscriber(long initialRequest) Constructs a non-forwarding TestSubscriber with the specified initial request value.
TestSubscriber(org.reactivestreams.Subscriber<? super T> actual) Constructs a forwarding TestSubscriber but leaves the requesting to the wrapped subscriber.
TestSubscriber(org.reactivestreams.Subscriber<? super T> actual, long initialRequest) Constructs a forwarding TestSubscriber with the specified initial request value.

Method Summary

Methods

Modifier and Type	Method and Description
TestSubscriber<T>	assertComplete() Assert that this TestSubscriber received exactly one onComplete event.
TestSubscriber<T>	assertEmpty() Assert that the TestSubscriber has received a Subscription but no other events.
TestSubscriber<T>	assertError(java.lang.Class<? extends java.lang.Throwable> errorClass) Asserts that this TestSubscriber received exactly one onError event which is an instance of the specified errorClass class.
TestSubscriber<T>	assertError(Predicate<java.lang.Throwable> errorPredicate) Asserts that this TestSubscriber received exactly one onError event for which the provided predicate returns true.
TestSubscriber<T>	assertError(java.lang.Throwable error) Assert that this TestSubscriber received exactly the specified onError event value.
TestSubscriber<T>	assertErrorMessage(java.lang.String message) Assert that there is only a single error with the given message.
TestSubscriber<T>	assertFailure(java.lang.Class<? extends java.lang.Throwable> error, T... values) Assert that the upstream signalled the specified values in order and then failed with a specific class or subclass of Throwable.
TestSubscriber<T>	assertFailure(Predicate<java.lang.Throwable> errorPredicate, T... values) Assert that the upstream signalled the specified values in order and then failed with a Throwable for which the provided predicate returns true.
TestSubscriber<T>	assertFailureAndMessage(java.lang.Class<? extends java.lang.Throwable> error, java.lang.String message, T... values) Assert that the upstream signalled the specified values in order, then failed with a specific class or subclass of Throwable and with the given exact error message.
TestSubscriber<T>	assertNoErrors() Assert that this TestSubscriber has not received any onError event.
TestSubscriber<T>	assertNotComplete() Assert that this TestSubscriber has not received any onComplete event.
TestSubscriber<T>	assertNotSubscribed() Assert that the onSubscribe method hasn't been called at all.
TestSubscriber<T>	assertNotTerminated() Assert that the TestSubscriber has not terminated (i.e., the terminal latch is still non-zero).
TestSubscriber<T>	assertNoValues() Assert that this TestSubscriber has not received any onNext events.
TestSubscriber<T>	assertOf(Consumer<? super TestSubscriber<T>> check) Run a check consumer with this TestSubscriber instance.
TestSubscriber<T>	assertResult(T... values) Assert that the upstream signalled the specified values in order and completed normally.
TestSubscriber<T>	assertSubscribed() Assert that the onSubscribe method was called exactly once.
TestSubscriber<T>	assertTerminated() Assert that the TestSubscriber terminated (i.e., the terminal latch reached zero).
TestSubscriber<T>	assertValue(T value) Assert that this TestSubscriber received exactly one onNext value which is equal to the given value with respect to Objects.equals.
TestSubscriber<T>	assertValueCount(int count) Assert that this TestSubscriber received the specified number onNext events.
TestSubscriber<T>	assertValues(T... values) Assert that the TestSubscriber received only the specified values in the specified order.
TestSubscriber<T>	assertValueSequence(java.lang.Iterable<? extends T> sequence) Assert that the TestSubscriber received only the specified sequence of values in the same order.
TestSubscriber<T>	assertValueSet(java.util.Collection<? extends T> expected) Assert that the TestSubscriber received only the specified values in any order.
TestSubscriber<T>	await() Awaits until this TestSubscriber receives an onError or onComplete events.
boolean	await(long time, java.util.concurrent.TimeUnit unit) Awaits the specified amount of time or until this TestSubscriber receives an onError or onComplete events, whichever happens first.
TestSubscriber<T>	awaitDone(long time, java.util.concurrent.TimeUnit unit) Awaits until the internal latch is counted down for the specified duration.
boolean	awaitTerminalEvent() Waits until the any terminal event has been received by this TestSubscriber or returns false if the wait has been interrupted.
boolean	awaitTerminalEvent(long duration, java.util.concurrent.TimeUnit unit) Awaits the specified amount of time or until this TestSubscriber receives an onError or onComplete events, whichever happens first.
void	cancel()
long	completions() Returns the number of times onComplete was called.
static <T> TestSubscriber<T>	create() Creates a TestSubscriber with Long.MAX_VALUE initial request.
static <T> TestSubscriber<T>	create(long initialRequested) Creates a TestSubscriber with the given initial request.
static <T> TestSubscriber<T>	create(org.reactivestreams.Subscriber<? super T> delegate) Constructs a forwarding TestSubscriber.
void	dispose() Dispose the resource, the operation should be idempotent.
int	errorCount() Returns the number of onError exceptions received.
java.util.List<java.lang.Throwable>	errors() Returns a shared list of received onError exceptions.
java.util.List<java.util.List<java.lang.Object>>	getEvents() Returns a list of 3 other lists: the first inner list contains the plain values received; the second list contains the potential errors and the final list contains the potential completions as Notifications.
boolean	hasSubscription() Returns true if this TestSubscriber received a subscription.
boolean	isCancelled() Returns true if this TestSubscriber has been cancelled.
boolean	isDisposed() Returns true if this resource has been disposed.
boolean	isTerminated() Returns true if TestSubscriber received any onError or onComplete events.
java.lang.Thread	lastThread() Returns the last thread which called the onXXX methods of this TestSubscriber.
void	onComplete()
void	onError(java.lang.Throwable t)
void	onNext(T t)
protected void	onStart() Called after the onSubscribe is called and handled.
void	onSubscribe(org.reactivestreams.Subscription s)
void	request(long n)
int	valueCount() Returns the number of onNext values received.
java.util.List<T>	values() Returns a shared list of received onNext values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TestSubscriber

public TestSubscriber()

Constructs a non-forwarding TestSubscriber with an initial request value of Long.MAX_VALUE.

TestSubscriber

public TestSubscriber(long initialRequest)

Constructs a non-forwarding TestSubscriber with the specified initial request value.

The TestSubscriber doesn't validate the initialRequest value so one can test sources with invalid values as well.

Parameters:

initialRequest - the initial request value

TestSubscriber

public TestSubscriber(org.reactivestreams.Subscriber<? super T> actual)

Constructs a forwarding TestSubscriber but leaves the requesting to the wrapped subscriber.

Parameters:

actual - the actual Subscriber to forward events to

TestSubscriber

public TestSubscriber(org.reactivestreams.Subscriber<? super T> actual,
              long initialRequest)

Constructs a forwarding TestSubscriber with the specified initial request value.

The TestSubscriber doesn't validate the initialRequest value so one can test sources with invalid values as well.

Parameters:

actual - the actual Subscriber to forward events to

initialRequest - the initial request value

Method Detail

create

public static <T> TestSubscriber<T> create()

Creates a TestSubscriber with Long.MAX_VALUE initial request.

Type Parameters:

T - the value type

Returns:

the new TestSubscriber instance.

create

public static <T> TestSubscriber<T> create(long initialRequested)

Creates a TestSubscriber with the given initial request.

Type Parameters:

T - the value type

Parameters:

initialRequested - the initial requested amount

Returns:

the new TestSubscriber instance.

create

public static <T> TestSubscriber<T> create(org.reactivestreams.Subscriber<? super T> delegate)

Constructs a forwarding TestSubscriber.

Type Parameters:

T - the value type received

Parameters:

delegate - the actual Subscriber to forward events to

Returns:

the new TestObserver instance

onSubscribe

public void onSubscribe(org.reactivestreams.Subscription s)

Specified by:

onSubscribe in interface org.reactivestreams.Subscriber<T>

onStart

protected void onStart()

Called after the onSubscribe is called and handled.

onNext

public void onNext(T t)

Specified by:

onNext in interface org.reactivestreams.Subscriber<T>

onError

public void onError(java.lang.Throwable t)

Specified by:

onError in interface org.reactivestreams.Subscriber<T>

onComplete

public void onComplete()

Specified by:

onComplete in interface org.reactivestreams.Subscriber<T>

request

public final void request(long n)

Specified by:

request in interface org.reactivestreams.Subscription

cancel

public final void cancel()

Specified by:

cancel in interface org.reactivestreams.Subscription

isCancelled

public final boolean isCancelled()

Returns true if this TestSubscriber has been cancelled.

Returns:

true if this TestSubscriber has been cancelled

dispose

public final void dispose()

Description copied from interface: Disposable

Dispose the resource, the operation should be idempotent.

Specified by:

dispose in interface Disposable

isDisposed

public final boolean isDisposed()

Description copied from interface: Disposable

Returns true if this resource has been disposed.

Specified by:

isDisposed in interface Disposable

Returns:

true if this resource has been disposed

lastThread

public final java.lang.Thread lastThread()

Returns the last thread which called the onXXX methods of this TestSubscriber.

Returns:

the last thread which called the onXXX methods

values

public final java.util.List<T> values()

Returns a shared list of received onNext values.

Returns:

a list of received onNext values

errors

public final java.util.List<java.lang.Throwable> errors()

Returns a shared list of received onError exceptions.

Returns:

a list of received events onError exceptions

completions

public final long completions()

Returns the number of times onComplete was called.

Returns:

the number of times onComplete was called

isTerminated

public final boolean isTerminated()

Returns true if TestSubscriber received any onError or onComplete events.

Returns:

true if TestSubscriber received any onError or onComplete events

valueCount

public final int valueCount()

Returns the number of onNext values received.

Returns:

the number of onNext values received

errorCount

public final int errorCount()

Returns the number of onError exceptions received.

Returns:

the number of onError exceptions received

hasSubscription

public final boolean hasSubscription()

Returns true if this TestSubscriber received a subscription.

Returns:

true if this TestSubscriber received a subscription

await

public final TestSubscriber<T> await()
                              throws java.lang.InterruptedException

Awaits until this TestSubscriber receives an onError or onComplete events.

Returns:

this

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting

See Also:

awaitTerminalEvent()

assertComplete

public final TestSubscriber<T> assertComplete()

Assert that this TestSubscriber received exactly one onComplete event.

Returns:

this

assertNotComplete

public final TestSubscriber<T> assertNotComplete()

Assert that this TestSubscriber has not received any onComplete event.

Returns:

this

assertNoErrors

public final TestSubscriber<T> assertNoErrors()

Assert that this TestSubscriber has not received any onError event.

Returns:

this

assertError

public final TestSubscriber<T> assertError(java.lang.Throwable error)

Assert that this TestSubscriber received exactly the specified onError event value.

The comparison is performed via Objects.equals(); since most exceptions don't implement equals(), this assertion may fail. Use the assertError(Class) overload to test against the class of an error instead of an instance of an error or assertError(Predicate) to test with different condition.

Parameters:

error - the error to check

Returns:

this

See Also:

assertError(Class), assertError(Predicate)

assertError

public final TestSubscriber<T> assertError(java.lang.Class<? extends java.lang.Throwable> errorClass)

Asserts that this TestSubscriber received exactly one onError event which is an instance of the specified errorClass class.

Parameters:

errorClass - the error class to expect

Returns:

this

assertError

public final TestSubscriber<T> assertError(Predicate<java.lang.Throwable> errorPredicate)

Asserts that this TestSubscriber received exactly one onError event for which the provided predicate returns true.

Parameters:

errorPredicate - the predicate that receives the error Throwable and should return true for expected errors.

Returns:

this

assertValue

public final TestSubscriber<T> assertValue(T value)

Assert that this TestSubscriber received exactly one onNext value which is equal to the given value with respect to Objects.equals.

Parameters:

value - the value to expect

Returns:

this

assertValueCount

public final TestSubscriber<T> assertValueCount(int count)

Assert that this TestSubscriber received the specified number onNext events.

Parameters:

count - the expected number of onNext events

Returns:

this

assertNoValues

public final TestSubscriber<T> assertNoValues()

Assert that this TestSubscriber has not received any onNext events.

Returns:

this

assertValues

public final TestSubscriber<T> assertValues(T... values)

Assert that the TestSubscriber received only the specified values in the specified order.

Parameters:

values - the values expected

Returns:

this

See Also:

assertValueSet(Collection)

assertValueSet

public final TestSubscriber<T> assertValueSet(java.util.Collection<? extends T> expected)

Assert that the TestSubscriber received only the specified values in any order.

This helps asserting when the order of the values is not guaranteed, i.e., when merging asynchronous streams.

Parameters:

expected - the collection of values expected in any order

Returns:

this

assertValueSequence

public final TestSubscriber<T> assertValueSequence(java.lang.Iterable<? extends T> sequence)

Assert that the TestSubscriber received only the specified sequence of values in the same order.

Parameters:

sequence - the sequence of expected values in order

Returns:

this

assertTerminated

public final TestSubscriber<T> assertTerminated()

Assert that the TestSubscriber terminated (i.e., the terminal latch reached zero).

Returns:

this

assertNotTerminated

public final TestSubscriber<T> assertNotTerminated()

Assert that the TestSubscriber has not terminated (i.e., the terminal latch is still non-zero).

Returns:

this

assertSubscribed

public final TestSubscriber<T> assertSubscribed()

Assert that the onSubscribe method was called exactly once.

Returns:

this

assertNotSubscribed

public final TestSubscriber<T> assertNotSubscribed()

Assert that the onSubscribe method hasn't been called at all.

Returns:

this

awaitTerminalEvent

public final boolean awaitTerminalEvent()

Waits until the any terminal event has been received by this TestSubscriber or returns false if the wait has been interrupted.

Returns:

true if the TestSubscriber terminated, false if the wait has been interrupted

awaitTerminalEvent

public final boolean awaitTerminalEvent(long duration,
                         java.util.concurrent.TimeUnit unit)

Awaits the specified amount of time or until this TestSubscriber receives an onError or onComplete events, whichever happens first.

Parameters:

duration - the waiting time

unit - the time unit of the waiting time

Returns:

true if the TestSubscriber terminated, false if timeout or interrupt happened

assertErrorMessage

public final TestSubscriber<T> assertErrorMessage(java.lang.String message)

Assert that there is only a single error with the given message.

Parameters:

message - the message to check

Returns:

this

getEvents

public final java.util.List<java.util.List<java.lang.Object>> getEvents()

Returns a list of 3 other lists: the first inner list contains the plain values received; the second list contains the potential errors and the final list contains the potential completions as Notifications.

Returns:

a list of (values, errors, completion-notifications)

assertOf

public final TestSubscriber<T> assertOf(Consumer<? super TestSubscriber<T>> check)

Run a check consumer with this TestSubscriber instance.

Parameters:

check - the check consumer to run

Returns:

this

assertResult

public final TestSubscriber<T> assertResult(T... values)

Assert that the upstream signalled the specified values in order and completed normally.

Parameters:

values - the expected values, asserted in order

Returns:

this

See Also:

assertFailure(Class, Object...), assertFailure(Predicate, Object...), assertFailureAndMessage(Class, String, Object...)

assertFailure

public final TestSubscriber<T> assertFailure(java.lang.Class<? extends java.lang.Throwable> error,
                              T... values)

Assert that the upstream signalled the specified values in order and then failed with a specific class or subclass of Throwable.

Parameters:

error - the expected exception (parent) class

values - the expected values, asserted in order

Returns:

this

assertFailure

public final TestSubscriber<T> assertFailure(Predicate<java.lang.Throwable> errorPredicate,
                              T... values)

Assert that the upstream signalled the specified values in order and then failed with a Throwable for which the provided predicate returns true.

Parameters:

errorPredicate - the predicate that receives the error Throwable and should return true for expected errors.

values - the expected values, asserted in order

Returns:

this

assertFailureAndMessage

public final TestSubscriber<T> assertFailureAndMessage(java.lang.Class<? extends java.lang.Throwable> error,
                                        java.lang.String message,
                                        T... values)

Assert that the upstream signalled the specified values in order, then failed with a specific class or subclass of Throwable and with the given exact error message.

Parameters:

error - the expected exception (parent) class

message - the expected failure message

values - the expected values, asserted in order

Returns:

this

await

public final boolean await(long time,
            java.util.concurrent.TimeUnit unit)
                    throws java.lang.InterruptedException

Awaits the specified amount of time or until this TestSubscriber receives an onError or onComplete events, whichever happens first.

Parameters:

time - the waiting time

unit - the time unit of the waiting time

Returns:

true if the TestSubscriber terminated, false if timeout happened

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting

See Also:

awaitTerminalEvent(long, TimeUnit)

awaitDone

public final TestSubscriber<T> awaitDone(long time,
                          java.util.concurrent.TimeUnit unit)

Awaits until the internal latch is counted down for the specified duration.

If the wait times out or gets interrupted, the TestSubscriber is cancelled.

Parameters:

time - the waiting time

unit - the time unit of the waiting time

Returns:

this

Throws:

java.lang.RuntimeException - wrapping an InterruptedException if the wait is interrupted

assertEmpty

public final TestSubscriber<T> assertEmpty()

Assert that the TestSubscriber has received a Subscription but no other events.

Returns:

this