Package rx.observers

Class TestSubscriber<T>

java.lang.Object

rx.Subscriber<T>

rx.observers.TestSubscriber<T>

Type Parameters:

T - the value type

All Implemented Interfaces:

Observer<T>, Subscription

public class TestSubscriber<T>
extends Subscriber<T>

A TestSubscriber is a variety of Subscriber that you can use for unit testing, to perform assertions, inspect received events, or wrap a mocked Subscriber.

Field Summary

Fields

Modifier and Type	Field	Description
private int	completions	The number of onCompleted() calls.
private final Observer<T>	delegate
private final List<Throwable>	errors
private static final Observer<Object>	INERT	The shared no-op observer.
private Thread	lastSeenThread
private final CountDownLatch	latch
private int	valueCount	Written after an onNext value has been added to the values list.
private final List<T>	values

Constructor Summary

Constructors

Constructor	Description
TestSubscriber()	Constructs a TestSubscriber with an initial request of Long.MAX_VALUE and no delegation.
TestSubscriber(long initialRequest)	Constructs a TestSubscriber with the initial request to be requested from upstream.
TestSubscriber(Observer<T> delegate)	Constructs a TestSubscriber which requests Long.MAX_VALUE and delegates events to the given Observer.
TestSubscriber(Observer<T> delegate, long initialRequest)	Constructs a TestSubscriber with the initial request to be requested from upstream and a delegate Observer to wrap.
TestSubscriber(Subscriber<T> delegate)	Constructs a TestSubscriber which requests Long.MAX_VALUE and delegates events to the given Subscriber.

Method Summary

Modifier and Type	Method	Description
void	assertCompleted()	Asserts that there is exactly one completion event.
void	assertError(Class<? extends Throwable> clazz)	Asserts that there is exactly one error event which is a subclass of the given class.
void	assertError(Throwable throwable)	Asserts that there is a single onError event with the exact exception.
(package private) final void	assertionError(String message)	Combines an assertion error message with the current completion and error state of this TestSubscriber, giving more information when some assertXXX check fails.
void	assertNoErrors()	Asserts that this Subscriber has received no onError notifications.
void	assertNotCompleted()	Asserts that there is no completion event.
void	assertNoTerminalEvent()	Asserts that there are no onError and onCompleted events.
void	assertNoValues()	Asserts that there are no onNext events received.
void	assertReceivedOnNext(List<T> items)	Asserts that a particular sequence of items was received by this Subscriber in order.
void	assertTerminalEvent()	Asserts that a single terminal event occurred, either onCompleted() or onError(java.lang.Throwable).
void	assertUnsubscribed()	Asserts that this Subscriber is unsubscribed.
void	assertValue(T value)	Asserts that there is only a single received onNext event and that it marks the emission of a specific item.
void	assertValueCount(int count)	Asserts that the given number of onNext events are received.
void	assertValues(T... values)	Asserts that the received onNext events, in order, are the specified items.
void	awaitTerminalEvent()	Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification).
void	awaitTerminalEvent(long timeout, TimeUnit unit)	Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification), or until a timeout expires.
void	awaitTerminalEventAndUnsubscribeOnTimeout(long timeout, TimeUnit unit)	Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification), or until a timeout expires; if the Subscriber is interrupted before either of these events take place, this method unsubscribes the Subscriber from the Observable).
final boolean	awaitValueCount(int expected, long timeout, TimeUnit unit)	Wait until the current committed value count is less than the expected amount by sleeping 1 unit at most timeout times and return true if at least the required amount of onNext values have been received.
static <T> TestSubscriber<T>	create()	Factory method to construct a TestSubscriber with an initial request of Long.MAX_VALUE and no delegation.
static <T> TestSubscriber<T>	create(long initialRequest)	Factory method to construct a TestSubscriber with the given initial request amount and no delegation.
static <T> TestSubscriber<T>	create(Observer<T> delegate)	Factory method to construct a TestSubscriber which delegates events to the given Observer and an issues an initial request of Long.MAX_VALUE.
static <T> TestSubscriber<T>	create(Observer<T> delegate, long initialRequest)	Factory method to construct a TestSubscriber which delegates events to the given Observer and issues the given initial request amount.
static <T> TestSubscriber<T>	create(Subscriber<T> delegate)	Factory method to construct a TestSubscriber which delegates events to the given Subscriber and an issues an initial request of Long.MAX_VALUE.
final int	getCompletions()	Returns the number of times onCompleted was called on this TestSubscriber.
Thread	getLastSeenThread()	Returns the last thread that was in use when an item or notification was received by this Subscriber.
List<Notification<T>>	getOnCompletedEvents()	Deprecated. use getCompletions() instead.
List<Throwable>	getOnErrorEvents()	Returns the Throwables this Subscriber was notified of via onError(java.lang.Throwable) as a List.
List<T>	getOnNextEvents()	Returns the sequence of items observed by this Subscriber, as an ordered List.
final int	getValueCount()	Returns the committed number of onNext elements that are safe to be read from getOnNextEvents() other threads.
void	onCompleted()	Notifies the Subscriber that the Observable has finished sending push-based notifications.
void	onError(Throwable e)	Notifies the Subscriber that the Observable has experienced an error condition.
void	onNext(T t)	Provides the Subscriber with a new item to observe.
void	requestMore(long n)	Allows calling the protected Subscriber.request(long) from unit tests.

Methods inherited from class rx.Subscriber

add, isUnsubscribed, onStart, request, setProducer, unsubscribe

Methods inherited from class java.lang.Object

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

Field Details

delegate

private final Observer<T> delegate

values

private final List<T> values

errors

private final List<Throwable> errors

completions

private int completions

The number of onCompleted() calls.

latch

private final CountDownLatch latch

valueCount

private volatile int valueCount

Written after an onNext value has been added to the values list.

lastSeenThread

private volatile Thread lastSeenThread

INERT

private static final Observer<Object> INERT

The shared no-op observer.

Constructor Details

TestSubscriber

public TestSubscriber(long initialRequest)

Constructs a TestSubscriber with the initial request to be requested from upstream.

Parameters:

initialRequest - the initial request value, negative value will revert to the default unbounded behavior

Since:

1.1.0

TestSubscriber

public TestSubscriber(Observer<T> delegate,
 long initialRequest)

Constructs a TestSubscriber with the initial request to be requested from upstream and a delegate Observer to wrap.

Parameters:

delegate - the Observer instance to wrap

initialRequest - the initial request value, negative value will revert to the default unbounded behavior

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

TestSubscriber

public TestSubscriber(Subscriber<T> delegate)

Constructs a TestSubscriber which requests Long.MAX_VALUE and delegates events to the given Subscriber.

Parameters:

delegate - the subscriber to delegate to.

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

TestSubscriber

public TestSubscriber(Observer<T> delegate)

Constructs a TestSubscriber which requests Long.MAX_VALUE and delegates events to the given Observer.

Parameters:

delegate - the observer to delegate to.

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

TestSubscriber

public TestSubscriber()

Constructs a TestSubscriber with an initial request of Long.MAX_VALUE and no delegation.

Method Details

create

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

Factory method to construct a TestSubscriber with an initial request of Long.MAX_VALUE and no delegation.

Type Parameters:

T - the value type

Returns:

the created TestSubscriber instance

Since:

1.1.0

create

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

Factory method to construct a TestSubscriber with the given initial request amount and no delegation.

Type Parameters:

T - the value type

Parameters:

initialRequest - the initial request amount, negative values revert to the default unbounded mode

Returns:

the created TestSubscriber instance

Since:

1.1.0

create

public static <T> TestSubscriber<T> create(Observer<T> delegate,
 long initialRequest)

Factory method to construct a TestSubscriber which delegates events to the given Observer and issues the given initial request amount.

Type Parameters:

T - the value type

Parameters:

delegate - the observer to delegate events to

initialRequest - the initial request amount, negative values revert to the default unbounded mode

Returns:

the created TestSubscriber instance

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

create

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

Factory method to construct a TestSubscriber which delegates events to the given Subscriber and an issues an initial request of Long.MAX_VALUE.

Type Parameters:

T - the value type

Parameters:

delegate - the subscriber to delegate events to

Returns:

the created TestSubscriber instance

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

create

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

Factory method to construct a TestSubscriber which delegates events to the given Observer and an issues an initial request of Long.MAX_VALUE.

Type Parameters:

T - the value type

Parameters:

delegate - the observer to delegate events to

Returns:

the created TestSubscriber instance

Throws:

NullPointerException - if delegate is null

Since:

1.1.0

onCompleted

public void onCompleted()

Notifies the Subscriber that the Observable has finished sending push-based notifications.

The Observable will not call this method if it calls onError(java.lang.Throwable).

getOnCompletedEvents

@Deprecated
public List<Notification<T>> getOnCompletedEvents()

Deprecated.

use getCompletions() instead.

Returns the Notifications representing each time this Subscriber was notified of sequence completion via onCompleted(), as a List.

Returns:

a list of Notifications representing calls to this Subscriber's onCompleted() method

getCompletions

@Experimental
public final int getCompletions()

Returns the number of times onCompleted was called on this TestSubscriber.

Returns:

the number of times onCompleted was called on this TestSubscriber.

Since:

(if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)

onError

public void onError(Throwable e)

Notifies the Subscriber that the Observable has experienced an error condition.

If the Observable calls this method, it will not thereafter call onNext(T) or onCompleted().

Parameters:

e - the exception encountered by the Observable

getOnErrorEvents

public List<Throwable> getOnErrorEvents()

Returns the Throwables this Subscriber was notified of via onError(java.lang.Throwable) as a List.

Returns:

a list of the Throwables that were passed to this Subscriber's onError(java.lang.Throwable) method

onNext

public void onNext(T t)

Provides the Subscriber with a new item to observe.

The Observable may call this method 0 or more times.

The Observable will not call this method again after it calls either onCompleted() or onError(java.lang.Throwable).

Parameters:

t - the item emitted by the Observable

getValueCount

public final int getValueCount()

Returns the committed number of onNext elements that are safe to be read from getOnNextEvents() other threads.

Returns:

the committed number of onNext elements

requestMore

public void requestMore(long n)

Allows calling the protected Subscriber.request(long) from unit tests.

Parameters:

n - the maximum number of items you want the Observable to emit to the Subscriber at this time, or Long.MAX_VALUE if you want the Observable to emit items at its own pace

getOnNextEvents

public List<T> getOnNextEvents()

Returns the sequence of items observed by this Subscriber, as an ordered List.

Returns:

a list of items observed by this Subscriber, in the order in which they were observed

assertReceivedOnNext

public void assertReceivedOnNext(List<T> items)

Asserts that a particular sequence of items was received by this Subscriber in order.

Parameters:

items - the sequence of items expected to have been observed

Throws:

AssertionError - if the sequence of items observed does not exactly match items

awaitValueCount

@Experimental
public final boolean awaitValueCount(int expected,
 long timeout,
 TimeUnit unit)
                              throws InterruptedException

Wait until the current committed value count is less than the expected amount by sleeping 1 unit at most timeout times and return true if at least the required amount of onNext values have been received.

Parameters:

expected - the expected number of onNext events

timeout - the time to wait for the events

unit - the time unit of waiting

Returns:

true if the expected number of onNext events happened

Throws:

InterruptedException - if the sleep is interrupted

Since:

(if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)

assertTerminalEvent

public void assertTerminalEvent()

Asserts that a single terminal event occurred, either onCompleted() or onError(java.lang.Throwable).

Throws:

AssertionError - if not exactly one terminal event notification was received

assertUnsubscribed

public void assertUnsubscribed()

Asserts that this Subscriber is unsubscribed.

Throws:

AssertionError - if this Subscriber is not unsubscribed

assertNoErrors

public void assertNoErrors()

Asserts that this Subscriber has received no onError notifications.

Throws:

AssertionError - if this Subscriber has received one or more onError notifications

awaitTerminalEvent

public void awaitTerminalEvent()

Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification).

Throws:

RuntimeException - if the Subscriber is interrupted before the Observable is able to complete

awaitTerminalEvent

public void awaitTerminalEvent(long timeout,
 TimeUnit unit)

Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification), or until a timeout expires.

Parameters:

timeout - the duration of the timeout

unit - the units in which timeout is expressed

Throws:

RuntimeException - if the Subscriber is interrupted before the Observable is able to complete

awaitTerminalEventAndUnsubscribeOnTimeout

public void awaitTerminalEventAndUnsubscribeOnTimeout(long timeout,
 TimeUnit unit)

Blocks until this Subscriber receives a notification that the Observable is complete (either an onCompleted or onError notification), or until a timeout expires; if the Subscriber is interrupted before either of these events take place, this method unsubscribes the Subscriber from the Observable). If timeout expires then the Subscriber is unsubscribed from the Observable.

Parameters:

timeout - the duration of the timeout

unit - the units in which timeout is expressed

getLastSeenThread

public Thread getLastSeenThread()

Returns the last thread that was in use when an item or notification was received by this Subscriber.

Returns:

the Thread on which this Subscriber last received an item or notification from the Observable it is subscribed to

assertCompleted

public void assertCompleted()

Asserts that there is exactly one completion event.

Throws:

AssertionError - if there were zero, or more than one, onCompleted events

Since:

1.1.0

assertNotCompleted

public void assertNotCompleted()

Asserts that there is no completion event.

Throws:

AssertionError - if there were one or more than one onCompleted events

Since:

1.1.0

assertError

public void assertError(Class<? extends Throwable> clazz)

Asserts that there is exactly one error event which is a subclass of the given class.

Parameters:

clazz - the class to check the error against.

Throws:

AssertionError - if there were zero, or more than one, onError events, or if the single onError event did not carry an error of a subclass of the given class

Since:

1.1.0

assertError

public void assertError(Throwable throwable)

Asserts that there is a single onError event with the exact exception.

Parameters:

throwable - the throwable to check

Throws:

AssertionError - if there were zero, or more than one, onError events, or if the single onError event did not carry an error that matches the specified throwable

Since:

1.1.0

assertNoTerminalEvent

public void assertNoTerminalEvent()

Asserts that there are no onError and onCompleted events.

Throws:

AssertionError - if there was either an onError or onCompleted event

Since:

1.1.0

assertNoValues

public void assertNoValues()

Asserts that there are no onNext events received.

Throws:

AssertionError - if there were any onNext events

Since:

1.1.0

assertValueCount

public void assertValueCount(int count)

Asserts that the given number of onNext events are received.

Parameters:

count - the expected number of onNext events

Throws:

AssertionError - if there were more or fewer onNext events than specified by count

Since:

1.1.0

assertValues

public void assertValues(T... values)

Asserts that the received onNext events, in order, are the specified items.

Parameters:

values - the items to check

Throws:

AssertionError - if the items emitted do not exactly match those specified by values

Since:

1.1.0

assertValue

public void assertValue(T value)

Asserts that there is only a single received onNext event and that it marks the emission of a specific item.

Parameters:

value - the item to check

Throws:

AssertionError - if the Observable does not emit only the single item specified by value

Since:

1.1.0

assertionError

final void assertionError(String message)

Combines an assertion error message with the current completion and error state of this TestSubscriber, giving more information when some assertXXX check fails.

Parameters:

message - the message to use for the error