Top Description Fields Constructors Methods
rx.observers

public Class TestSubscriber<T>

extends Subscriber<T>
Class Inheritance
Type Parameters
<T>
the value type
Imports
java.util.*, java.util.concurrent.*, rx.*, .Observer, rx.exceptions.CompositeException

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

Modifier and TypeField and Description
private int
completions

The number of onCompleted() calls.

private final Observer<T>
private final List<Throwable>
private static final Observer<Object>
INERT

The shared no-op observer.

private volatile Thread
private final CountDownLatch
private volatile int
valueCount

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

private final List<T>

Constructor Summary

AccessConstructor and Description
public
TestSubscriber(long
the initial request value, negative value will revert to the default unbounded behavior
initialRequest
)

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

public
TestSubscriber(Observer<T>
the Observer instance to wrap
delegate
,
long
the initial request value, negative value will revert to the default unbounded behavior
initialRequest
)

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

public
TestSubscriber(Subscriber<T>
the subscriber to delegate to.
delegate
)

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

public
TestSubscriber(Observer<T>
the observer to delegate to.
delegate
)

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

public
TestSubscriber()

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

Method Summary

Modifier and TypeMethod and Description
public void
assertCompleted()

Asserts that there is exactly one completion event.

public void
assertError(Class<? extends Throwable>
the class to check the error against.
clazz
)

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

public void
assertError(Throwable
the throwable to check
throwable
)

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

pack-priv final void
assertionError(String
the message to use for the error
message
)

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

private void
assertItem(T expected, int i)

public void
assertNoErrors()

Asserts that this Subscriber has received no onError notifications.

public void
assertNotCompleted()

Asserts that there is no completion event.

public void
assertNoTerminalEvent()

Asserts that there are no onError and onCompleted events.

public void
assertNoValues()

Asserts that there are no onNext events received.

public void
assertReceivedOnNext(List<T>
the sequence of items expected to have been observed
items
)

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

public void
assertTerminalEvent()

Asserts that a single terminal event occurred, either onCompleted or onError.

public void
assertUnsubscribed()

Asserts that this Subscriber is unsubscribed.

public void
assertValue(T
the item to check
value
)

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

public void
assertValueCount(int
the expected number of onNext events
count
)

Asserts that the given number of onNext events are received.

public void
assertValues(T...
the items to check
values
)

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

public final void
assertValuesAndClear(T
the expected first value
expectedFirstValue
,
T...
the optional rest values
expectedRestValues
)

Assert that the TestSubscriber contains the given first and optional rest values exactly and if so, clears the internal list of values.

public void
awaitTerminalEvent()

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

public void
awaitTerminalEvent(long
the duration of the timeout
timeout
,
TimeUnit
the units in which timeout is expressed
unit
)

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

public void
awaitTerminalEventAndUnsubscribeOnTimeout(long
the duration of the timeout
timeout
,
TimeUnit
the units in which timeout is expressed
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).

public final boolean

Returns:

true if the expected number of onNext events happened
awaitValueCount
(int
the expected number of onNext events
expected
,
long
the time to wait for the events
timeout
,
TimeUnit
the time unit of waiting
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.

public static <
the value type
T
>
TestSubscriber<T>

Returns:

the created TestSubscriber instance
create
()

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

public static <
the value type
T
>
TestSubscriber<T>

Returns:

the created TestSubscriber instance
create
(long
the initial request amount, negative values revert to the default unbounded mode
initialRequest
)

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

public static <
the value type
T
>
TestSubscriber<T>

Returns:

the created TestSubscriber instance
create
(Observer<T>
the observer to delegate events to
delegate
,
long
the initial request amount, negative values revert to the default unbounded mode
initialRequest
)

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

public static <
the value type
T
>
TestSubscriber<T>

Returns:

the created TestSubscriber instance
create
(Subscriber<T>
the subscriber to delegate events to
delegate
)

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

public static <
the value type
T
>
TestSubscriber<T>

Returns:

the created TestSubscriber instance
create
(Observer<T>
the observer to delegate events to
delegate
)

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

public final int

Returns:

the number of times onCompleted was called on this TestSubscriber.
getCompletions
()

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

public Thread

Returns:

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

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

public List<Notification<T>>

Returns:

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

Deprecated use getCompletions() instead.
Returns the Notifications representing each time this Subscriber was notified of sequence completion via onCompleted, as a List.
public List<Throwable>

Returns:

a list of the Throwables that were passed to this Subscriber's onError method
getOnErrorEvents
()

Returns the Throwables this Subscriber was notified of via onError as a List.

public List<T>

Returns:

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

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

public final int

Returns:

the committed number of onNext elements
getValueCount
()

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

public void
onCompleted()

Implements rx.Observer.onCompleted.

Notifies the Subscriber that the Observable has finished sending push-based notifications.
public void
onError(Throwable
the exception encountered by the Observable
e
)

Implements rx.Observer.onError.

Notifies the Subscriber that the Observable has experienced an error condition.
public void
onNext(T
the item emitted by the Observable
t
)

Implements rx.Observer.onNext.

Provides the Subscriber with a new item to observe.
public void
requestMore(long
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
n
)

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

Inherited from rx.Subscriber:
addisUnsubscribedonStartrequestsetProducerunsubscribe

Field Detail

completionsback to summary
private int completions

The number of onCompleted() calls.

delegateback to summary
private final Observer<T> delegate
errorsback to summary
private final List<Throwable> errors
INERTback to summary
private static final Observer<Object> INERT

The shared no-op observer.

lastSeenThreadback to summary
private volatile Thread lastSeenThread
latchback to summary
private final CountDownLatch latch
valueCountback to summary
private volatile int valueCount

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

valuesback to summary
private final List<T> values

Constructor Detail

TestSubscriberback to summary
public TestSubscriber(long initialRequest)

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

Parameters
initialRequest:long

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

Annotations
@SuppressWarnings:unchecked
Since
1.1.0
TestSubscriberback to summary
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:Observer<T>

the Observer instance to wrap

initialRequest:long

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

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
TestSubscriberback to summary
public TestSubscriber(Subscriber<T> delegate)

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

Parameters
delegate:Subscriber<T>

the subscriber to delegate to.

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
TestSubscriberback to summary
public TestSubscriber(Observer<T> delegate)

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

Parameters
delegate:Observer<T>

the observer to delegate to.

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
TestSubscriberback to summary
public TestSubscriber()

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

Method Detail

assertCompletedback to summary
public void assertCompleted()

Asserts that there is exactly one completion event.

Exceptions
AssertionError:
if there were zero, or more than one, onCompleted events
Since
1.1.0
assertErrorback to summary
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:Class<? extends Throwable>

the class to check the error against.

Exceptions
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
assertErrorback to summary
public void assertError(Throwable throwable)

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

Parameters
throwable:Throwable

the throwable to check

Exceptions
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
assertionErrorback to summary
pack-priv 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:String

the message to use for the error

assertItemback to summary
private void assertItem(T expected, int i)
assertNoErrorsback to summary
public void assertNoErrors()

Asserts that this Subscriber has received no onError notifications.

Exceptions
AssertionError:
if this Subscriber has received one or more onError notifications
assertNotCompletedback to summary
public void assertNotCompleted()

Asserts that there is no completion event.

Exceptions
AssertionError:
if there were one or more than one onCompleted events
Since
1.1.0
assertNoTerminalEventback to summary
public void assertNoTerminalEvent()

Asserts that there are no onError and onCompleted events.

Exceptions
AssertionError:
if there was either an onError or onCompleted event
Since
1.1.0
assertNoValuesback to summary
public void assertNoValues()

Asserts that there are no onNext events received.

Exceptions
AssertionError:
if there were any onNext events
Since
1.1.0
assertReceivedOnNextback to summary
public void assertReceivedOnNext(List<T> items)

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

Parameters
items:List<T>

the sequence of items expected to have been observed

Exceptions
AssertionError:
if the sequence of items observed does not exactly match items
assertTerminalEventback to summary
public void assertTerminalEvent()

Asserts that a single terminal event occurred, either onCompleted or onError.

Exceptions
AssertionError:
if not exactly one terminal event notification was received
assertUnsubscribedback to summary
public void assertUnsubscribed()

Asserts that this Subscriber is unsubscribed.

Exceptions
AssertionError:
if this Subscriber is not unsubscribed
assertValueback to summary
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:T

the item to check

Exceptions
AssertionError:
if the Observable does not emit only the single item specified by value
Since
1.1.0
assertValueCountback to summary
public void assertValueCount(int count)

Asserts that the given number of onNext events are received.

Parameters
count:int

the expected number of onNext events

Exceptions
AssertionError:
if there were more or fewer onNext events than specified by count
Since
1.1.0
assertValuesback to summary
public void assertValues(T... values)

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

Parameters
values:T[]

the items to check

Exceptions
AssertionError:
if the items emitted do not exactly match those specified by values
Since
1.1.0
assertValuesAndClearback to summary
public final void assertValuesAndClear(T expectedFirstValue, T... expectedRestValues)

Assert that the TestSubscriber contains the given first and optional rest values exactly and if so, clears the internal list of values.

TestSubscriber ts = new TestSubscriber();

ts.onNext(1);

ts.assertValuesAndClear(1);

ts.onNext(2);
ts.onNext(3);

ts.assertValuesAndClear(2, 3); // no mention of 1
Parameters
expectedFirstValue:T

the expected first value

expectedRestValues:T[]

the optional rest values

Since
1.3
awaitTerminalEventback to summary
public void awaitTerminalEvent()

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

Exceptions
RuntimeException:
if the Subscriber is interrupted before the Observable is able to complete
awaitTerminalEventback to summary
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:long

the duration of the timeout

unit:TimeUnit

the units in which timeout is expressed

Exceptions
RuntimeException:
if the Subscriber is interrupted before the Observable is able to complete
awaitTerminalEventAndUnsubscribeOnTimeoutback to summary
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:long

the duration of the timeout

unit:TimeUnit

the units in which timeout is expressed

awaitValueCountback to summary
public 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.

Parameters
expected:int

the expected number of onNext events

timeout:long

the time to wait for the events

unit:TimeUnit

the time unit of waiting

Returns:boolean

true if the expected number of onNext events happened

Exceptions
RuntimeException:
if the sleep is interrupted
Since
1.3
createback to summary
public static <T> TestSubscriber<T> create()

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

Parameters
<T>
the value type
Returns:TestSubscriber<T>

the created TestSubscriber instance

Since
1.1.0
createback to summary
public static <T> TestSubscriber<T> create(long initialRequest)

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

Parameters
<T>
the value type
initialRequest:long

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

Returns:TestSubscriber<T>

the created TestSubscriber instance

Since
1.1.0
createback to summary
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.

Parameters
<T>
the value type
delegate:Observer<T>

the observer to delegate events to

initialRequest:long

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

Returns:TestSubscriber<T>

the created TestSubscriber instance

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
createback to summary
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.

Parameters
<T>
the value type
delegate:Subscriber<T>

the subscriber to delegate events to

Returns:TestSubscriber<T>

the created TestSubscriber instance

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
createback to summary
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.

Parameters
<T>
the value type
delegate:Observer<T>

the observer to delegate events to

Returns:TestSubscriber<T>

the created TestSubscriber instance

Exceptions
NullPointerException:
if delegate is null
Since
1.1.0
getCompletionsback to summary
public final int getCompletions()

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

Returns:int

the number of times onCompleted was called on this TestSubscriber.

Since
1.3
getLastSeenThreadback to summary
public Thread getLastSeenThread()

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

Returns:Thread

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

getOnCompletedEventsback to summary
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:List<Notification<T>>

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

Annotations
@Deprecated
getOnErrorEventsback to summary
public List<Throwable> getOnErrorEvents()

Returns the Throwables this Subscriber was notified of via onError as a List.

Returns:List<Throwable>

a list of the Throwables that were passed to this Subscriber's onError method

getOnNextEventsback to summary
public List<T> getOnNextEvents()

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

Returns:List<T>

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

getValueCountback to summary
public final int getValueCount()

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

Returns:int

the committed number of onNext elements

onCompletedback to summary
public void onCompleted()

Implements rx.Observer.onCompleted.

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

The Observable will not call this method if it calls onError.

Annotations
@Override
onErrorback to summary
public void onError(Throwable e)

Implements rx.Observer.onError.

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

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

Parameters
e:Throwable

the exception encountered by the Observable

Annotations
@Override
onNextback to summary
public void onNext(T t)

Implements rx.Observer.onNext.

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.

Parameters
t:T

the item emitted by the Observable

Annotations
@Override
requestMoreback to summary
public void requestMore(long n)

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

Parameters
n:long

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