reactor.test

Interface StepVerifier

public interface StepVerifier

A StepVerifier provides a declarative way of creating a verifiable script for an async Publisher sequence, by expressing expectations about the events that will happen upon subscription. The verification must be triggered after the terminal expectations (completion, error, cancellation) have been declared, by calling one of the verify() methods.

• Create a StepVerifier around a Publisher using create(Publisher) or withVirtualTime(Supplier<Publisher>) (in which case you should lazily create the publisher inside the provided lambda).
• Set up individual value expectations using expectNext, expectNextMatches(Predicate), assertNext(Consumer), expectNextCount(long) or expectNextSequence(Iterable).
• Trigger subscription actions during the verification using either thenRequest(long) or thenCancel().
• Finalize the test scenario using a terminal expectation: expectComplete(), expectError(), expectError(Class), expectErrorMatches(Predicate), or thenCancel().
• Trigger the verification of the resulting StepVerifier on its Publisher using either verify() or verify(Duration). (note some of the terminal expectations above have a "verify" prefixed alternative that both declare the expectation and trigger the verification).
• If any expectations failed, an AssertionError will be thrown indicating the failures.

For example:

 StepVerifier.create(Flux.just("foo", "bar"))
   .expectNext("foo")
   .expectNext("bar")
   .expectComplete()
   .verify();
 

Author:

Arjen Poutsma, Stephane Maldini, Simon Baslé

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	StepVerifier.Assertions Exposes post-verification state assertions.
static interface	StepVerifier.ContextExpectations<T> Allow to set expectations about the Context propagated during the Subscription phase.
static interface	StepVerifier.FirstStep<T> Define a builder for explicitly expecting an initializing Subscription as first signal.
static interface	StepVerifier.LastStep Define a builder for terminal states.
static interface	StepVerifier.Step<T> Define a builder for expecting main sequence individual signals.

Field Summary

Fields

Modifier and Type	Field and Description
static java.time.Duration	DEFAULT_VERIFY_TIMEOUT Default verification timeout (see verify()) is "no timeout".

Method Summary

Modifier and Type	Method and Description
static <T> StepVerifier.FirstStep<T>	create(Publisher<? extends T> publisher) Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time.
static <T> StepVerifier.FirstStep<T>	create(Publisher<? extends T> publisher, long n) Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time.
static <T> StepVerifier.FirstStep<T>	create(Publisher<? extends T> publisher, StepVerifierOptions options) Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time.
StepVerifier	log() Activate debug logging of a description of the test scenario, as well as some details about certain verification steps.
static void	resetDefaultTimeout() Reset the verify() timeout to the "unlimited" default.
static void	setDefaultTimeout(java.time.Duration timeout) Set the verify() timeout for all StepVerifier created through the factory methods (create(Publisher), withVirtualTime(Supplier), etc.).
java.time.Duration	verify() Verify the signals received by this subscriber.
java.time.Duration	verify(java.time.Duration duration) Verify the signals received by this subscriber.
StepVerifier	verifyLater() Trigger the subscription and prepare for verifications but doesn't block.
StepVerifier.Assertions	verifyThenAssertThat() Verifies the signals received by this subscriber, then exposes various assertion methods on the final state.
StepVerifier.Assertions	verifyThenAssertThat(java.time.Duration duration) Verifies the signals received by this subscriber, then exposes various assertion methods on the final state.
static <T> StepVerifier.FirstStep<T>	withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier) Prepare a new StepVerifier in a controlled environment using VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait().
static <T> StepVerifier.FirstStep<T>	withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier, long n) Prepare a new StepVerifier in a controlled environment using VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait().
static <T> StepVerifier.FirstStep<T>	withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier, StepVerifierOptions options) Prepare a new StepVerifier in a controlled environment using a user-provided VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait().
static <T> StepVerifier.FirstStep<T>	withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier, java.util.function.Supplier<? extends VirtualTimeScheduler> vtsLookup, long n) Prepare a new StepVerifier in a controlled environment using a user-provided VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait().

Field Detail

DEFAULT_VERIFY_TIMEOUT

static final java.time.Duration DEFAULT_VERIFY_TIMEOUT

Default verification timeout (see verify()) is "no timeout".

See Also:

setDefaultTimeout(Duration), resetDefaultTimeout()

Method Detail

setDefaultTimeout

static void setDefaultTimeout(@Nullable
                              java.time.Duration timeout)

Set the verify() timeout for all StepVerifier created through the factory methods (create(Publisher), withVirtualTime(Supplier), etc.).

This affects ALL such verifiers created after this call, until a call to either this method or resetDefaultTimeout().

Parameters:

timeout - the timeout to use for verify() calls on all StepVerifier created through the factory methods after this call. null is interpreted as a call to resetDefaultTimeout().

resetDefaultTimeout

static void resetDefaultTimeout()

Reset the verify() timeout to the "unlimited" default.

This affects ALL such verifiers created after this call, until a call to setDefaultTimeout(Duration).

create

static <T> StepVerifier.FirstStep<T> create(Publisher<? extends T> publisher)

Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time. Each verify() will fully (re)play the scenario.

Parameters:

publisher - the publisher to subscribe to and verify

Returns:

a builder for expectation declaration and ultimately verification.

create

static <T> StepVerifier.FirstStep<T> create(Publisher<? extends T> publisher,
                                            long n)

Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time. Each verify() will fully (re)play the scenario. The verification will request a specified amount of values.

Parameters:

publisher - the publisher to subscribe to and verify

n - the amount of items to request

Returns:

a builder for expectation declaration and ultimately verification.

create

static <T> StepVerifier.FirstStep<T> create(Publisher<? extends T> publisher,
                                            StepVerifierOptions options)

Prepare a new StepVerifier in an uncontrolled environment: StepVerifier.Step.thenAwait() will block in real time. Each verify() will fully (re)play the scenario. The verification will request a specified amount of values according to the options passed.

Parameters:

publisher - the publisher to subscribe to

options - the options for the verification

Returns:

a builder for expectation declaration and ultimately verification.

withVirtualTime

static <T> StepVerifier.FirstStep<T> withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier)

Prepare a new StepVerifier in a controlled environment using VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait(). The scheduler is injected into all Schedulers factories, which means that any operator created within the lambda without a specific scheduler will use virtual time. Each verify() will fully (re)play the scenario. The verification will request an unbounded amount of values.

Note that virtual time, StepVerifier.Step.thenAwait(Duration) sources that are subscribed on a different Scheduler (eg. a source that is initialized outside of the lambda with a dedicated Scheduler) and delays introduced within the data path (eg. an interval in a flatMap) are not always compatible, as this can perform the clock move BEFORE the interval schedules itself, resulting in the interval never playing out.

Type Parameters:

T - the type of the subscriber

Parameters:

scenarioSupplier - a mandatory supplier of the Publisher to subscribe to and verify. In order for operators to use virtual time, they must be invoked from within the lambda.

Returns:

a builder for expectation declaration and ultimately verification.

withVirtualTime

static <T> StepVerifier.FirstStep<T> withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier,
                                                     long n)

Prepare a new StepVerifier in a controlled environment using VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait(). The scheduler is injected into all Schedulers factories, which means that any operator created within the lambda without a specific scheduler will use virtual time. Each verify() will fully (re)play the scenario. The verification will request a specified amount of values.

Note that virtual time, StepVerifier.Step.thenAwait(Duration) sources that are subscribed on a different Scheduler (eg. a source that is initialized outside of the lambda with a dedicated Scheduler) and delays introduced within the data path (eg. an interval in a flatMap) are not always compatible, as this can perform the clock move BEFORE the interval schedules itself, resulting in the interval never playing out.

Type Parameters:

T - the type of the subscriber

Parameters:

scenarioSupplier - a mandatory supplier of the Publisher to subscribe to and verify. In order for operators to use virtual time, they must be invoked from within the lambda.

n - the amount of items to request (must be >= 0)

Returns:

a builder for expectation declaration and ultimately verification.

withVirtualTime

static <T> StepVerifier.FirstStep<T> withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier,
                                                     java.util.function.Supplier<? extends VirtualTimeScheduler> vtsLookup,
                                                     long n)

Prepare a new StepVerifier in a controlled environment using a user-provided VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait(). The scheduler is injected into all Schedulers factories, which means that any operator created within the lambda without a specific scheduler will use virtual time. Each verify() will fully (re)play the scenario. The verification will request a specified amount of values.

Note that virtual time, StepVerifier.Step.thenAwait(Duration) sources that are subscribed on a different Scheduler (eg. a source that is initialized outside of the lambda with a dedicated Scheduler) and delays introduced within the data path (eg. an interval in a flatMap) are not always compatible, as this can perform the clock move BEFORE the interval schedules itself, resulting in the interval never playing out.

Type Parameters:

T - the type of the subscriber

Parameters:

scenarioSupplier - a mandatory supplier of the Publisher to subscribe to and verify. In order for operators to use virtual time, they must be invoked from within the lambda.

vtsLookup - the supplier of the VirtualTimeScheduler to inject and manipulate during verification.

n - the amount of items to request (must be >= 0)

Returns:

a builder for expectation declaration and ultimately verification.

withVirtualTime

static <T> StepVerifier.FirstStep<T> withVirtualTime(java.util.function.Supplier<? extends Publisher<? extends T>> scenarioSupplier,
                                                     StepVerifierOptions options)

Prepare a new StepVerifier in a controlled environment using a user-provided VirtualTimeScheduler to manipulate a virtual clock via StepVerifier.Step.thenAwait(). The scheduler is injected into all Schedulers factories, which means that any operator created within the lambda without a specific scheduler will use virtual time. Each verify() will fully (re)play the scenario. The verification will request a specified amount of values according to the provided options.

If no VirtualTimeScheduler Supplier is set in the options, this method will make a copy of said options and set up the default supplier (like the one in withVirtualTime(Supplier)).

Note that virtual time, StepVerifier.Step.thenAwait(Duration) sources that are subscribed on a different Scheduler (eg. a source that is initialized outside of the lambda with a dedicated Scheduler) and delays introduced within the data path (eg. an interval in a flatMap) are not always compatible, as this can perform the clock move BEFORE the interval schedules itself, resulting in the interval never playing out.

Type Parameters:

T - the type of the subscriber

Parameters:

scenarioSupplier - a mandatory supplier of the Publisher to subscribe to and verify. In order for operators to use virtual time, they must be invoked from within the lambda.

options - the verification options, including the supplier of the VirtualTimeScheduler to inject and manipulate during verification (see note above in case options doesn't define such a supplier)

Returns:

a builder for expectation declaration and ultimately verification.

log

StepVerifier log()

Activate debug logging of a description of the test scenario, as well as some details about certain verification steps.

Returns:

the verifier for final verify() call

verifyLater

StepVerifier verifyLater()

Trigger the subscription and prepare for verifications but doesn't block. Calling one of the verify() methods afterwards will block until the sequence is validated and throw if assertions fail.

Calling this method more than once in a row should be a NO-OP, returning the same instance as the first call.

Returns:

a StepVerifier that is in progress but on which one can chose to block later.

verify

java.time.Duration verify()
                   throws java.lang.AssertionError

Verify the signals received by this subscriber. Unless a default timeout has been set before construction of the StepVerifier via setDefaultTimeout(Duration), this method will block until the stream has been terminated (either through Subscriber.onComplete(), Subscriber.onError(Throwable) or Subscription.cancel()). Depending on the declared expectations and actions, notably in case of undersized manual requests, such a verification could also block indefinitely.

Returns:

the actual Duration the verification took.

Throws:

java.lang.AssertionError - in case of expectation failures

See Also:

verify(Duration), setDefaultTimeout(Duration)

verify

java.time.Duration verify(java.time.Duration duration)
                   throws java.lang.AssertionError

Verify the signals received by this subscriber. This method will block for up to the given duration or until the stream has been terminated (either through Subscriber.onComplete(), Subscriber.onError(Throwable) or Subscription.cancel()). Use Duration.ZERO for an unlimited wait for termination.

Parameters:

duration - the maximum duration to wait for the sequence to terminate, or Duration.ZERO for unlimited wait.

Returns:

the actual Duration the verification took.

Throws:

java.lang.AssertionError - in case of expectation failures, or when the verification times out

verifyThenAssertThat

StepVerifier.Assertions verifyThenAssertThat()

Verifies the signals received by this subscriber, then exposes various assertion methods on the final state.

Note that like verify(), this method will block until the stream has been terminated (either through Subscriber.onComplete(), Subscriber.onError(Throwable) or Subscription.cancel()). Depending on the declared expectations and actions, notably in case of undersized manual requests, such a verification could also block indefinitely. Use setDefaultTimeout(Duration) to globally add a timeout on verify()-derived methods.

Returns:

the actual Duration the verification took.

Throws:

java.lang.AssertionError - in case of expectation failures

verifyThenAssertThat

StepVerifier.Assertions verifyThenAssertThat(java.time.Duration duration)

Verifies the signals received by this subscriber, then exposes various assertion methods on the final state.

Note that like verify(), this method will block until the stream has been terminated (either through Subscriber.onComplete(), Subscriber.onError(Throwable) or Subscription.cancel()). Depending on the declared expectations and actions, notably in case of undersized manual requests, such a verification could also block indefinitely. As a consequence you can use the Duration duration parameter to set a timeout.

Parameters:

duration - the maximum duration to wait for the sequence to terminate, or Duration.ZERO for unlimited wait.

Returns:

StepVerifier.Assertions for chaining post-verification state assertions