{title:'Fluent Assertions', created:'9.0.0'}

The {@link oaj.assertions} package in Juneau is a powerful API for performing fluent style assertions. It is used throughout the REST client and server APIs for performing inline assertions on REST requests and responses.

##### Example:

| // Create a basic REST client with JSON support and download a bean. | MyBean bean = RestClient.create() | .simpleJson() | .build() | .get(URI) | .run() | .assertStatus().asCode().is(200) | .assertHeader("Content-Type").isMatches("application/json*") | .getContent().assertValue().asString().isContains("OK") | .getContent().as(MyBean.class);

- The REST API is described later in the documentation.

The assertions API is designed to be used in both code (as it's done in the REST APIs) or for standalone use in unit tests.

The {@link oaj.assertions.Assertions} class provides various static methods for invoking assertions on a variety of object types for simplified unit testing.

- {@link oaj.assertions.Assertions}
  - {@link oaj.assertions.Assertions#assertAny(Object) assertAny(T)}
  - {@link oaj.assertions.Assertions#assertArray(Object[]) assertArray(E[])}
  - {@link oaj.assertions.Assertions#assertBean(Object) assertBean(V)}
  - {@link oaj.assertions.Assertions#assertBeanList(List) assertBeanList(List)}
  - {@link oaj.assertions.Assertions#assertBoolean(Boolean) assertBoolean(Boolean)}
  - {@link oaj.assertions.Assertions#assertBooleanArray(boolean[]) assertBooleanArray(boolean[])}
  - {@link oaj.assertions.Assertions#assertByteArray(byte[]) assertByteArray(byte[])}
  - {@link oaj.assertions.Assertions#assertBytes(byte[]) assertBytes(byte[])}
  - {@link oaj.assertions.Assertions#assertBytes(InputStream) assertBytes(InputStream)}
  - {@link oaj.assertions.Assertions#assertCharArray(char[]) assertCharArray(char[])}
  - {@link oaj.assertions.Assertions#assertCollection(Collection) assertCollection(Collection)}
  - {@link oaj.assertions.Assertions#assertComparable(Comparable) assertComparable(T)}
  - {@link oaj.assertions.Assertions#assertDate(Date) assertDate(Date)}
  - {@link oaj.assertions.Assertions#assertDoubleArray(double[]) assertDoubleArray(double[])}
  - {@link oaj.assertions.Assertions#assertFloatArray(float[]) assertFloatArray(float[])}
  - {@link oaj.assertions.Assertions#assertIntArray(int[]) assertIntArray(int[])}
  - {@link oaj.assertions.Assertions#assertInteger(Integer) assertInteger(Integer)}
  - {@link oaj.assertions.Assertions#assertList(List) assertList(List)}
  - {@link oaj.assertions.Assertions#assertLong(Long) assertLong(Long)}
  - {@link oaj.assertions.Assertions#assertLongArray(long[]) assertLongArray(long[])}
  - {@link oaj.assertions.Assertions#assertMap(Map) assertMap(Map)}
  - {@link oaj.assertions.Assertions#assertObject(Object) assertObject(T)}
  - {@link oaj.assertions.Assertions#assertOptional(Optional) assertOptional(Optional)}
  - {@link oaj.assertions.Assertions#assertReader(Reader) assertReader(Reader)}
  - {@link oaj.assertions.Assertions#assertShortArray(short[]) assertShortArray(short[])}
  - {@link oaj.assertions.Assertions#assertString(Object) assertString(Object)}
  - {@link oaj.assertions.Assertions#assertStringList(List) assertStringList(List)}
  - {@link oaj.assertions.Assertions#assertThrowable(Throwable) assertThrowable(V)}
  - {@link oaj.assertions.Assertions#assertThrown(Snippet) assertThrown(Snippet)}
  - {@link oaj.assertions.Assertions#assertVersion(Version) assertVersion(Version)}
  - {@link oaj.assertions.Assertions#assertZonedDateTime(ZonedDateTime) assertZonedDateTime(ZonedDateTime)}

##### Examples:

| import static org.apache.juneau.assertions.Assertions.*; | import static org.apache.juneau.assertions.AssertionPredicates.*; | | // Check the contents of a string. | assertString("foo, bar") | .asSplit(",") | .asTrimmed() | .isHas("foo", "bar"); | | // Extract a subset of properties from a list of beans and compare using Simplified JSON. | List<MyBean> myListOfBeans = ...; | assertBeanList(myListOfBeans) | .asPropertyMap("a,b") | .asJson().is("[{a:1,b:'foo'}]"); | | // Perform an arbitrary Predicate check against a bean. | MyBean myBeans = ...; | assertBean(myBeans) | .is(x -> isValidCheck(x)) | | // Check that a list of strings has less than 10 entries and the first | // 3 entries are [foo, bar*, null] using assertion predicates. | List<String> myListOfStrings = ...; | assertStringList(myListOfStrings) | .asSize().isLt(10) | .asFirst(3) | .isEach(eq("foo"),match("bar*"),isNull()) | | // Check that an exception is thrown and is the specified type and has the specified message. | assertThrown(()->myBean.runBadMethod()) | .exists() | .isExactType(RuntimeException.class) | .asMessage().is("foo");

Assertions have 3 categories of methods:

- Testing methods.
- Transform methods.
- Configuration methods.

Testing methods perform an assertion on the specified value and throws a {@link java.lang.AssertionError} if the test fails. Otherwise, the method returns the original assertion object to allow you to chain the command. Testing methods start with is.

##### Example:

| // Test a string. | assertString(myString) | .isNotNull() // Perform test and returns original FluentStringAssertion. | .isNotEmpty(); // Perform test and returns original FluentStringAssertion.

Transform methods allow you to convert assertions of one type to another type or to convert the tested value to some other form wrapped in another assertion. Transform methods start with as.

##### Example:

| // Customize the behavior of an assertion. | assertString(myString) | .asString() // Converts to a FluentIntegerAssertion. | .isLt(100) // Runs test and returns original FluentStringAssertion. | .asUc() // Converts string to uppercase and returns a new FluentStringAssertion. | .isContains("FOO"); // Runs test and returns original FluentStringAssertion.

Configuration methods allow you to tailor the behavior of assertions when they fail. They always return the same assertion object. Transformed assertions inherit the configurations of the created-by assertions. Configuration methods start with set.

##### Example:

| // Customize the behavior of an assertion. | assertString(myString) | .setMsg("My string was null. Value was {VALUE}.") // Custom error message when error occurs. | .setOut(myPrintWriter) // Print error message to a separate writer. | .setThrowable(MyAssertionThrowable.class) // Throw a customized assertion exception. | .isNotNull();

The following shows the class hierarchy for the {@link oaj.assertions.IntegerAssertion IntegerAssertion} class showing the general design pattern for assertion classes:

- {@link oaj.assertions.Assertion Assertion} - Base class for all assertion objects containing common configuration methods.
  - {@link oaj.assertions.FluentAssertion FluentAssertion<R>} - Parent class for all fluent assertions.
    - {@link oaj.assertions.FluentObjectAssertion FluentObjectAssertion<T,R>} - Tests and transforms for general POJOs.
      - {@link oaj.assertions.FluentComparableAssertion FluentComparableAssertion<T extends Comparable,R>} - Tests and transforms for Comparables.
        - {@link oaj.assertions.FluentIntegerAssertion FluentIntegerAssertion<R>} - Tests and transforms for Integers.
          - {@link oaj.assertions.IntegerAssertion IntegerAssertion} - Assertion that returns itself.

In the design, the "Fluent" classes (e.g. {@link oaj.assertions.FluentIntegerAssertion}) allow you to specify the object that gets returned when the test method is executed. When used in the RestClient class for example, the return object is the {@link oajrc.RestResponse} object so that you can perform multiple fluent operations against that object. The "Normal" classes (e.g. {@link oaj.assertions.IntegerAssertion}) are simply subclasses of the fluent equivalent which return the assertion itself, meaning the test method returns the original {@link oaj.assertions.IntegerAssertion} so that multiple tests can be performed per assertion.

For more information about the capabilities of the Assertions API, refer to the methods on the {@link oaj.assertions.Assertions} methods above.