io.vertx.junit5

## Class VertxTestContext

- java.lang.Object
- - io.vertx.junit5.VertxTestContext

-     public final class VertxTestContext
      extends Object

  A test context to wait on the outcomes of asynchronous operations.
  Author:
    Julien Ponge

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `VertxTestContext.ExecutionBlock` Interface for an executable block of assertion code.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VertxTestContext()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> Future<T>` | `assertComplete(Future<T> fut)` This method allows you to check if a future is completed.
    `<T> Future<T>` | `assertFailure(Future<T> fut)` This method allows you to check if a future is failed.
    `boolean` | `awaitCompletion(long timeout, TimeUnit unit)` Wait for the completion of the test context.
    `Throwable` | `causeOfFailure()` Give the cause of failure.
    `Checkpoint` | `checkpoint()` Create a strict checkpoint.
    `Checkpoint` | `checkpoint(int requiredNumberOfPasses)` Create a strict checkpoint.
    `boolean` | `completed()` Check if the context has completed.
    `void` | `completeNow()` Complete the test context immediately, making the corresponding test pass.
    `<T> Handler<AsyncResult<T>>` | `completing()` Deprecated. Use `succeedingThenComplete()` instead.
    `boolean` | `failed()` Check if the context has been marked has failed or not.
    `<T> Handler<AsyncResult<T>>` | `failing()` Deprecated. Use `failingThenComplete()` or `failing(Handler)`, for example `failing(e -> checkpoint.flag())`, `failing(e -> { more testing code })`, or `failing(e -> {})`.
    `<T> Handler<AsyncResult<T>>` | `failing(Handler<Throwable> nextHandler)` Create an asynchronous result handler that expects a failure, and passes the exception to another handler.
    `<T> Handler<AsyncResult<T>>` | `failingThenComplete()` Create an asynchronous result handler that expects a failure to then complete the test context.
    `void` | `failNow(String message)` Calls `failNow(Throwable)` with the `message`.
    `void` | `failNow(Throwable t)` Make the test context fail immediately, making the corresponding test fail.
    `Checkpoint` | `laxCheckpoint()` Create a lax checkpoint.
    `Checkpoint` | `laxCheckpoint(int requiredNumberOfPasses)` Create a lax checkpoint.
    `<T> Handler<AsyncResult<T>>` | `succeeding()` Deprecated. Use `succeedingThenComplete()` or `succeeding(Handler)`, for example `succeeding(value -> checkpoint.flag())`, `succeeding(value -> { more testing code })`, or `succeeding(value -> {})`.
    `<T> Handler<AsyncResult<T>>` | `succeeding(Handler<T> nextHandler)` Create an asynchronous result handler that expects a success, and passes the value to another handler.
    `<T> Handler<AsyncResult<T>>` | `succeedingThenComplete()` Create an asynchronous result handler that expects a success to then complete the test context.
    `Set<StackTraceElement>` | `unsatisfiedCheckpointCallSites()` Gives the call sites of all unsatisfied checkpoints.
    `VertxTestContext` | `verify(VertxTestContext.ExecutionBlock block)` Allow verifications and assertions to be made.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### VertxTestContext

          public VertxTestContext()

  - ### Method Detail

    - #### failed

          public boolean failed()

      Check if the context has been marked has failed or not.
      Returns:
        `true` if the context has failed, `false` otherwise.

    - #### causeOfFailure

          public Throwable causeOfFailure()

      Give the cause of failure.
      Returns:
        the cause of failure, or `null` if the test context hasn't failed.

    - #### completed

          public boolean completed()

      Check if the context has completed.
      Returns:
        `true` if the context has completed, `false` otherwise.

    - #### unsatisfiedCheckpointCallSites

          public Set<StackTraceElement> unsatisfiedCheckpointCallSites()

      Gives the call sites of all unsatisfied checkpoints.
      Returns:
        a set of `StackTraceElement` references pointing to the unsatisfied checkpoint call sites.

    - #### completeNow

          public void completeNow()

      Complete the test context immediately, making the corresponding test pass.

    - #### failNow

          public void failNow(Throwable t)

      Make the test context fail immediately, making the corresponding test fail.
      Parameters:
        `t` - the cause of failure.

    - #### failNow

          public void failNow(String message)

      Calls `failNow(Throwable)` with the `message`.
      Parameters:
        `message` - the cause of failure

    - #### laxCheckpoint

          public Checkpoint laxCheckpoint()

      Create a lax checkpoint.
      Returns:
        a checkpoint that requires 1 pass; more passes are allowed and ignored.

    - #### laxCheckpoint

          public Checkpoint laxCheckpoint(int requiredNumberOfPasses)

      Create a lax checkpoint.
      Parameters:
        `requiredNumberOfPasses` - the required number of passes to validate the checkpoint.
      Returns:
        a checkpoint that requires several passes; more passes than the required number are allowed and ignored.

    - #### checkpoint

          public Checkpoint checkpoint()

      Create a strict checkpoint.
      Returns:
        a checkpoint that requires 1 pass, and makes the context fail if it is called more than once.

    - #### checkpoint

          public Checkpoint checkpoint(int requiredNumberOfPasses)

      Create a strict checkpoint.
      Parameters:
        `requiredNumberOfPasses` - the required number of passes to validate the checkpoint.
      Returns:
        a checkpoint that requires several passes, but no more, or it fails the context.

    - #### succeeding

          @Deprecated
          public <T> Handler<AsyncResult<T>> succeeding()

      Deprecated. Use `succeedingThenComplete()` or `succeeding(Handler)`, for example `succeeding(value -> checkpoint.flag())`, `succeeding(value -> { more testing code })`, or `succeeding(value -> {})`.
      Create an asynchronous result handler that expects a success.
      Type Parameters:
        `T` - the asynchronous result type.
      Returns:
        the handler.

    - #### succeeding

          public <T> Handler<AsyncResult<T>> succeeding(Handler<T> nextHandler)

      Create an asynchronous result handler that expects a success, and passes the value to another handler.
      Type Parameters:
        `T` - the asynchronous result type.
      Parameters:
        `nextHandler` - the value handler to call on success that is expected not to throw a `Throwable`.
      Returns:
        the handler.

    - #### failing

          @Deprecated
          public <T> Handler<AsyncResult<T>> failing()

      Deprecated. Use `failingThenComplete()` or `failing(Handler)`, for example `failing(e -> checkpoint.flag())`, `failing(e -> { more testing code })`, or `failing(e -> {})`.
      Create an asynchronous result handler that expects a failure.
      Type Parameters:
        `T` - the asynchronous result type.
      Returns:
        the handler.

    - #### failing

          public <T> Handler<AsyncResult<T>> failing(Handler<Throwable> nextHandler)

      Create an asynchronous result handler that expects a failure, and passes the exception to another handler.
      Type Parameters:
        `T` - the asynchronous result type.
      Parameters:
        `nextHandler` - the exception handler to call on failure that is expected not to throw a `Throwable`.
      Returns:
        the handler.

    - #### succeedingThenComplete

          public <T> Handler<AsyncResult<T>> succeedingThenComplete()

      Create an asynchronous result handler that expects a success to then complete the test context.
      Type Parameters:
        `T` - the asynchronous result type.
      Returns:
        the handler.

    - #### completing

          @Deprecated
          public <T> Handler<AsyncResult<T>> completing()

      Deprecated. Use `succeedingThenComplete()` instead.
      Create an asynchronous result handler that expects a success to then complete the test context.
      Type Parameters:
        `T` - the asynchronous result type.
      Returns:
        the handler.
      See Also:
        `failingThenComplete()`

    - #### failingThenComplete

          public <T> Handler<AsyncResult<T>> failingThenComplete()

      Create an asynchronous result handler that expects a failure to then complete the test context.
      Type Parameters:
        `T` - the asynchronous result type.
      Returns:
        the handler.

    - #### assertComplete

          public <T> Future<T> assertComplete(Future<T> fut)

      This method allows you to check if a future is completed. It internally creates a checkpoint. You can use it in a chain of `Future`.
      Parameters:
        `fut` - The future to assert success
      Returns:
        a future with completion result

    - #### assertFailure

          public <T> Future<T> assertFailure(Future<T> fut)

      This method allows you to check if a future is failed. It internally creates a checkpoint. You can use it in a chain of `Future`.
      Parameters:
        `fut` - The future to assert failure
      Returns:
        a future with failure result

    - #### verify

          public VertxTestContext verify(VertxTestContext.ExecutionBlock block)

      Allow verifications and assertions to be made.

      This method allows any assertion API to be used. The semantic is that the verification is successful when no exception is being thrown upon calling `block`, otherwise the context fails with that exception.

      Parameters:
        `block` - a block of code to execute.
      Returns:
        this context.

    - #### awaitCompletion

          public boolean awaitCompletion(long timeout,
                                         TimeUnit unit)
                                  throws InterruptedException

      Wait for the completion of the test context.

      This method is automatically called by the `VertxExtension` when using parameter injection of `VertxTestContext`. You should only call it when you instantiate this class manually.

      Parameters:
        `timeout` - the timeout.
        `unit` - the timeout unit.
      Returns:
        `true` if the completion or failure happens before the timeout has been reached, `false` otherwise.
      Throws:
        `InterruptedException` - when the thread has been interrupted.

Copyright © 2024 Eclipse. All rights reserved.