CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-jayway-jsonpath--json-path-assert

A library with Hamcrest matchers for JsonPath - provides assertion capabilities for JSON documents using JsonPath expressions

—

Pending
Overview
Eval results
Files

fluent-assertions.mddocs/

Fluent Assertion Interface

Object-oriented fluent API for creating readable assertion chains with detailed error reporting and method chaining support. This interface provides an alternative to the matcher-based approach, offering a more traditional assertion style for complex JSON validation scenarios.

Capabilities

JsonAsserter Factory Methods

Static factory methods for creating JsonAsserter instances from various JSON input sources.

/**
 * Creates a JsonAsserter from a JSON string
 * @param json JSON document as string
 * @return JsonAsserter instance for fluent assertions
 * @throws ParseException when the JSON cannot be parsed
 */
public static JsonAsserter with(String json);

/**
 * Creates a JsonAsserter from a Reader
 * @param reader Reader containing JSON document
 * @return JsonAsserter instance for fluent assertions
 * @throws IOException when reading fails
 * @throws ParseException when the JSON cannot be parsed
 */
public static JsonAsserter with(Reader reader) throws IOException;

/**
 * Creates a JsonAsserter from an InputStream
 * @param is InputStream containing JSON document
 * @return JsonAsserter instance for fluent assertions
 * @throws IOException when reading fails
 * @throws ParseException when the JSON cannot be parsed
 */
public static JsonAsserter with(InputStream is) throws IOException;

Usage Examples:

import static com.jayway.jsonassert.JsonAssert.with;
import java.io.*;

// From string
String jsonString = "{\"user\":{\"name\":\"Alice\",\"age\":30}}";
JsonAsserter asserter = with(jsonString);

// From file
FileReader reader = new FileReader("user.json");
JsonAsserter fileAsserter = with(reader);

// From input stream
InputStream stream = getClass().getResourceAsStream("/data.json");
JsonAsserter streamAsserter = with(stream);

Core Assertion Methods

Primary assertion methods for validating JSON path values using Hamcrest matchers or direct value comparison.

/**
 * Asserts that the value at the specified path matches the given Hamcrest matcher
 * @param path JsonPath expression as string
 * @param matcher Hamcrest matcher to validate the path value
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value doesn't match
 */
<T> JsonAsserter assertThat(String path, Matcher<T> matcher);

/**
 * Asserts that the value at the specified path matches the given matcher with custom error message
 * @param path JsonPath expression as string
 * @param matcher Hamcrest matcher to validate the path value
 * @param message Custom error message for assertion failures
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value doesn't match
 */
<T> JsonAsserter assertThat(String path, Matcher<T> matcher, String message);

/**
 * Asserts that the value at the specified path equals the expected value
 * @param path JsonPath expression as string
 * @param expected Expected value for comparison
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or values are not equal
 */
<T> JsonAsserter assertEquals(String path, T expected);

/**
 * Asserts that the value at the specified path equals the expected value with custom error message
 * @param path JsonPath expression as string
 * @param expected Expected value for comparison
 * @param message Custom error message for assertion failures
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or values are not equal
 */
<T> JsonAsserter assertEquals(String path, T expected, String message);

Usage Examples:

import static com.jayway.jsonassert.JsonAssert.with;
import static org.hamcrest.Matchers.*;

String json = "{\"user\":{\"name\":\"Alice\",\"age\":30,\"roles\":[\"admin\",\"user\"]}}";

// Using Hamcrest matchers
with(json)
    .assertThat("$.user.name", equalTo("Alice"))
    .assertThat("$.user.age", greaterThan(18))
    .assertThat("$.user.roles", hasSize(2))
    .assertThat("$.user.roles", hasItem("admin"));

// Direct value comparison
with(json)
    .assertEquals("$.user.name", "Alice")
    .assertEquals("$.user.age", 30);

// Custom error messages
with(json)
    .assertThat("$.user.age", greaterThan(21), "User must be over 21")
    .assertEquals("$.user.name", "Alice", "User name should be Alice");

Path Existence Assertions

Methods for asserting whether paths exist or are undefined within the JSON document.

/**
 * Asserts that the specified path does not exist in the JSON document
 * @param path JsonPath expression as string
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if the path exists
 */
JsonAsserter assertNotDefined(String path);

/**
 * Asserts that the specified path does not exist with custom error message
 * @param path JsonPath expression as string
 * @param message Custom error message for assertion failures
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if the path exists
 */
JsonAsserter assertNotDefined(String path, String message);

Usage Examples:

String json = "{\"user\":{\"name\":\"Alice\",\"age\":30}}";

with(json)
    .assertNotDefined("$.user.email")
    .assertNotDefined("$.admin", "Document should not contain admin section")
    .assertNotDefined("$.user.password");

Null Value Assertions

Specialized methods for asserting null and non-null values at specified paths.

/**
 * Asserts that the value at the specified path is null
 * @param path JsonPath expression as string
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value is not null
 */
JsonAsserter assertNull(String path);

/**
 * Asserts that the value at the specified path is null with custom error message
 * @param path JsonPath expression as string
 * @param message Custom error message for assertion failures
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value is not null
 */
JsonAsserter assertNull(String path, String message);

/**
 * Asserts that the value at the specified path is NOT null
 * @param path JsonPath expression as string
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value is null
 */
<T> JsonAsserter assertNotNull(String path);

/**
 * Asserts that the value at the specified path is NOT null with custom error message
 * @param path JsonPath expression as string
 * @param message Custom error message for assertion failures
 * @return this JsonAsserter for method chaining
 * @throws AssertionError if path doesn't exist or value is null
 */
<T> JsonAsserter assertNotNull(String path, String message);

Usage Examples:

String json = "{\"user\":{\"name\":\"Alice\",\"email\":null,\"age\":30}}";

with(json)
    .assertNull("$.user.email")
    .assertNull("$.user.email", "Email should not be set")
    .assertNotNull("$.user.name")
    .assertNotNull("$.user.age", "Age is required");

Method Chaining Support

Syntactic sugar method for creating readable assertion chains.

/**
 * Syntactic sugar to allow chaining assertions with a separating and() statement
 * @return this JsonAsserter for continued method chaining
 */
JsonAsserter and();

Usage Examples:

String json = "{\"user\":{\"firstName\":\"Alice\",\"lastName\":\"Smith\",\"age\":30,\"active\":true}}";

// Readable assertion chains
with(json)
    .assertThat("$.user.firstName", equalTo("Alice"))
    .and()
    .assertThat("$.user.lastName", equalTo("Smith"))
    .and()
    .assertThat("$.user.age", greaterThan(18))
    .and()
    .assertEquals("$.user.active", true);

// Complex validation chain
with(json)
    .assertNotNull("$.user.firstName", "First name is required")
    .and()
    .assertNotNull("$.user.lastName", "Last name is required")
    .and()
    .assertThat("$.user.age", allOf(greaterThan(0), lessThan(150)))
    .and()
    .assertNotDefined("$.user.password")
    .and()
    .assertNull("$.user.deletedAt");

Error Handling and Reporting

The fluent assertion interface provides detailed error messages that include:

  • Path Context: The JsonPath expression that failed
  • Expected vs Actual: Clear comparison of expected and actual values
  • Custom Messages: User-provided error descriptions
  • Exception Chain: Original parsing or path evaluation errors

Example Error Messages:

// Path not found error
"Error reading JSON path [$.user.missing]"

// Value mismatch error
"JSON path [$.user.age] doesn't match.\nExpected: <25>\nActual: <30>"

// Custom message error
"JSON Assert Error: User must be over 21\nExpected: <greater than 21>\nActual: <18>"

Integration with JsonPath Configuration

The fluent assertion interface respects the current JsonPath configuration for parsing and path evaluation:

import com.jayway.jsonpath.Configuration;
import com.jayway.jsonpath.Option;

// Configure strict parsing
Configuration.setDefaults(Configuration.defaultConfiguration()
    .addOptions(Option.SUPPRESS_EXCEPTIONS));

// Assertions will use the configured behavior
with(json)
    .assertThat("$.path", equalTo(expectedValue));

Performance Considerations

  • Document Parsing: JSON is parsed once when creating the JsonAsserter instance
  • Path Evaluation: Each assertion method evaluates its path independently
  • Error Handling: Detailed error reporting may impact performance in high-volume scenarios
  • Memory Usage: The parsed JSON document is held in memory for the lifetime of the JsonAsserter

Install with Tessl CLI

npx tessl i tessl/maven-com-jayway-jsonpath--json-path-assert

docs

collection-matchers.md

fluent-assertions.md

index.md

jsonpath-matchers.md

tile.json