or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

collection-matchers.mdfluent-assertions.mdindex.mdjsonpath-matchers.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.jayway.jsonpath/json-path-assert@2.9.x

To install, run

npx @tessl/cli install tessl/maven-com-jayway-jsonpath--json-path-assert@2.9.0

index.mddocs/

json-path-assert

A library with Hamcrest matchers for JsonPath that provides assertion capabilities for JSON documents using JsonPath expressions. This library bridges the gap between JsonPath query language and Hamcrest's expressive matcher framework, enabling developers to write readable and maintainable JSON assertions in Java tests.

Package Information

  • Package Name: json-path-assert
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>com.jayway.jsonpath</groupId>
    <artifactId>json-path-assert</artifactId>
    <version>2.9.0</version>
</dependency>

Core Imports

import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;

For JsonAsserter fluent interface:

import static com.jayway.jsonassert.JsonAssert.with;

Basic Usage

import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;
import static com.jayway.jsonassert.JsonAssert.with;
import static org.hamcrest.Matchers.*;
import static org.junit.Assert.assertThat;

String json = "{\"store\":{\"name\":\"Little Shop\",\"books\":[{\"title\":\"Book1\",\"price\":10.99},{\"title\":\"Book2\",\"price\":8.95}]}}";

// Basic path existence checks
assertThat(json, hasJsonPath("$.store.name"));
assertThat(json, hasNoJsonPath("$.nonexistent"));

// Path value validation
assertThat(json, hasJsonPath("$.store.name", equalTo("Little Shop")));
assertThat(json, hasJsonPath("$.store.books[*]", hasSize(2)));

// Fluent assertion interface
with(json)
    .assertThat("$.store.name", equalTo("Little Shop"))
    .and()
    .assertThat("$.store.books[*]", hasSize(2))
    .and()
    .assertNull("$.store.discount");

// Combined matchers for comprehensive validation
assertThat(json, isJson(allOf(
    withJsonPath("$.store.name", equalTo("Little Shop")),
    withJsonPath("$.store.books[*]", hasSize(2)),
    withoutJsonPath("$.expensive")
)));

Architecture

The library is built around several key components:

  • JsonPathMatchers: Static factory methods providing the main API for creating Hamcrest matchers
  • JsonAsserter Interface: Fluent assertion API for complex JSON validation scenarios
  • Type-Specific Matchers: Specialized matchers for String, File, and generic Object inputs
  • Path Evaluation Engine: Core logic for evaluating JsonPath expressions against JSON documents
  • Error Reporting: Detailed failure messages with path context and expected vs actual values

The library supports multiple JSON input formats (String, File, InputStream, Reader, parsed objects) and integrates seamlessly with existing test frameworks through Hamcrest's matcher system.

Capabilities

JsonPath Matchers

Core Hamcrest matchers for JsonPath-based assertions, providing the primary API for validating JSON documents using path expressions.

// Path existence validation
public static Matcher<? super Object> hasJsonPath(String jsonPath);
public static <T> Matcher<? super Object> hasJsonPath(String jsonPath, Matcher<T> resultMatcher);
public static Matcher<? super Object> hasNoJsonPath(String jsonPath);

// JSON validity checks
public static Matcher<Object> isJson();
public static Matcher<Object> isJson(Matcher<? super ReadContext> matcher);
public static Matcher<String> isJsonString(Matcher<? super ReadContext> matcher);
public static Matcher<File> isJsonFile(Matcher<? super ReadContext> matcher);

// ReadContext matchers for combining conditions
public static Matcher<? super ReadContext> withJsonPath(String jsonPath, Predicate... filters);
public static Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath);
public static <T> Matcher<? super ReadContext> withJsonPath(String jsonPath, Matcher<T> resultMatcher);
public static <T> Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath, Matcher<T> resultMatcher);
public static Matcher<? super ReadContext> withoutJsonPath(String jsonPath, Predicate... filters);
public static Matcher<? super ReadContext> withoutJsonPath(JsonPath jsonPath);

JsonPath Matchers

Fluent Assertion Interface

Object-oriented fluent API for creating readable assertion chains with detailed error reporting and method chaining support.

// Factory methods for creating JsonAsserter instances
public static JsonAsserter with(String json);
public static JsonAsserter with(Reader reader) throws IOException;
public static JsonAsserter with(InputStream is) throws IOException;

// Core assertion methods
public interface JsonAsserter {
    <T> JsonAsserter assertThat(String path, Matcher<T> matcher);
    <T> JsonAsserter assertThat(String path, Matcher<T> matcher, String message);
    <T> JsonAsserter assertEquals(String path, T expected);
    <T> JsonAsserter assertEquals(String path, T expected, String message);
    JsonAsserter assertNotDefined(String path);
    JsonAsserter assertNotDefined(String path, String message);
    JsonAsserter assertNull(String path);
    JsonAsserter assertNull(String path, String message);
    <T> JsonAsserter assertNotNull(String path);
    <T> JsonAsserter assertNotNull(String path, String message);
    JsonAsserter and();
}

Fluent Assertions

Collection and Map Matchers

Specialized Hamcrest matchers for validating collections and maps within JSON documents, extending standard Hamcrest capabilities.

public static CollectionMatcher collectionWithSize(Matcher<? super Integer> sizeMatcher);
public static Matcher<Map<String, ?>> mapContainingKey(Matcher<String> keyMatcher);
public static <V> Matcher<? super Map<?, V>> mapContainingValue(Matcher<? super V> valueMatcher);
public static Matcher<Collection<Object>> emptyCollection();

Collection Matchers

Types

// Core interfaces and classes
interface JsonAsserter {
    // Methods defined in capabilities above
}

abstract class CollectionMatcher<C extends Collection<?>> extends BaseMatcher<C> {
    protected abstract boolean matchesSafely(C collection);
}

// Implementation classes (internal use)
class IsJson<T> extends TypeSafeMatcher<T> { /* ... */ }
class WithJsonPath<T> extends TypeSafeMatcher<ReadContext> { /* ... */ }
class WithoutJsonPath extends TypeSafeDiagnosingMatcher<ReadContext> { /* ... */ }