{title:'Overview', 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() | .json5() | .build() | .get(URI) | .run() | .assertStatus().asCode().is(200) | .assertHeader("Content-Type").isMatches("application/json*") | .getContent().assertValue().asString().isContains("OK") | .getContent().as(MyBean.class);

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.

Assertions have 3 categories of methods:

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");

Testing methods (isX 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.

Example:

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

Transform methods (asX 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.

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 (setX 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:

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.