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

collection-matchers.mddocs/

Collection and Map Matchers

Specialized Hamcrest matchers for validating collections and maps within JSON documents, extending standard Hamcrest capabilities with JSON-specific functionality. These matchers are designed to work seamlessly with JsonPath results and provide enhanced collection validation.

Capabilities

Collection Size Validation

Validates collection size using flexible Hamcrest matchers for precise size constraints.

/**
 * Creates a matcher for collections that validates size using the provided size matcher
 * @param sizeMatcher Hamcrest matcher to validate the collection size
 * @return CollectionMatcher that succeeds when size matches the provided matcher
 */
public static CollectionMatcher collectionWithSize(Matcher<? super Integer> sizeMatcher);

Usage Examples:

import static com.jayway.jsonassert.JsonAssert.*;
import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;
import static org.hamcrest.Matchers.*;

String json = "{\"users\":[{\"name\":\"Alice\"},{\"name\":\"Bob\"},{\"name\":\"Charlie\"}],\"tags\":[]}";

// Exact size validation
assertThat(json, hasJsonPath("$.users", collectionWithSize(equalTo(3))));

// Range-based size validation
assertThat(json, hasJsonPath("$.users", collectionWithSize(greaterThan(2))));
assertThat(json, hasJsonPath("$.users", collectionWithSize(lessThanOrEqualTo(5))));

// Combined size constraints
assertThat(json, hasJsonPath("$.users", collectionWithSize(
    allOf(greaterThan(1), lessThan(10)))));

// Empty collection validation
assertThat(json, hasJsonPath("$.tags", collectionWithSize(equalTo(0))));

// Using with fluent assertions
with(json)
    .assertThat("$.users", collectionWithSize(equalTo(3)))
    .and()
    .assertThat("$.tags", collectionWithSize(equalTo(0)));

Map Key Validation

Validates that maps contain specific keys using flexible key matching criteria.

/**
 * Creates a matcher for maps that validates the presence of keys matching the provided key matcher
 * @param keyMatcher Hamcrest matcher to validate map keys
 * @return Matcher for Map<String, ?> that succeeds when a matching key is found
 */
public static Matcher<Map<String, ?>> mapContainingKey(Matcher<String> keyMatcher);

Usage Examples:

String json = "{\"user\":{\"firstName\":\"Alice\",\"lastName\":\"Smith\",\"email\":\"alice@example.com\"}}";

// Exact key matching
assertThat(json, hasJsonPath("$.user", mapContainingKey(equalTo("firstName"))));

// Pattern-based key matching
assertThat(json, hasJsonPath("$.user", mapContainingKey(startsWith("first"))));
assertThat(json, hasJsonPath("$.user", mapContainingKey(endsWith("Name"))));
assertThat(json, hasJsonPath("$.user", mapContainingKey(containsString("email"))));

// Case-insensitive key matching
assertThat(json, hasJsonPath("$.user", mapContainingKey(equalToIgnoringCase("FIRSTNAME"))));

// Combined key validation
assertThat(json, hasJsonPath("$.user", allOf(
    mapContainingKey(equalTo("firstName")),
    mapContainingKey(equalTo("lastName")),
    mapContainingKey(equalTo("email"))
)));

// Using with fluent assertions
with(json)
    .assertThat("$.user", mapContainingKey(equalTo("firstName")))
    .and()
    .assertThat("$.user", mapContainingKey(endsWith("Name")));

Map Value Validation

Validates that maps contain specific values using flexible value matching criteria.

/**
 * Creates a matcher for maps that validates the presence of values matching the provided value matcher
 * @param valueMatcher Hamcrest matcher to validate map values
 * @return Matcher for Map<?, V> that succeeds when a matching value is found
 */
public static <V> Matcher<? super Map<?, V>> mapContainingValue(Matcher<? super V> valueMatcher);

Usage Examples:

String json = "{\"config\":{\"timeout\":30,\"retries\":3,\"enabled\":true,\"url\":\"https://api.example.com\"}}";

// Exact value matching
assertThat(json, hasJsonPath("$.config", mapContainingValue(equalTo(30))));
assertThat(json, hasJsonPath("$.config", mapContainingValue(equalTo(true))));

// Type-specific value matching
assertThat(json, hasJsonPath("$.config", mapContainingValue(instanceOf(String.class))));
assertThat(json, hasJsonPath("$.config", mapContainingValue(instanceOf(Integer.class))));
assertThat(json, hasJsonPath("$.config", mapContainingValue(instanceOf(Boolean.class))));

// String value pattern matching
assertThat(json, hasJsonPath("$.config", mapContainingValue(startsWith("https://"))));
assertThat(json, hasJsonPath("$.config", mapContainingValue(containsString("api"))));

// Numeric value range matching
assertThat(json, hasJsonPath("$.config", mapContainingValue(greaterThan(0))));
assertThat(json, hasJsonPath("$.config", mapContainingValue(lessThanOrEqualTo(100))));

// Combined value validation
assertThat(json, hasJsonPath("$.config", allOf(
    mapContainingValue(equalTo(30)),
    mapContainingValue(equalTo(true)),
    mapContainingValue(startsWith("https://"))
)));

// Using with fluent assertions
with(json)
    .assertThat("$.config", mapContainingValue(equalTo(30)))
    .and()
    .assertThat("$.config", mapContainingValue(instanceOf(String.class)));

Empty Collection Validation

Validates that collections are empty with type-safe handling.

/**
 * Creates a matcher that validates collections are empty
 * @return Matcher for Collection<Object> that succeeds for empty collections
 */
public static Matcher<Collection<Object>> emptyCollection();

Usage Examples:

String json = "{\"activeUsers\":[],\"completedTasks\":[],\"pendingItems\":[{\"id\":1}]}";

// Empty collection validation
assertThat(json, hasJsonPath("$.activeUsers", emptyCollection()));
assertThat(json, hasJsonPath("$.completedTasks", emptyCollection()));

// Non-empty collection validation (negated)
assertThat(json, hasJsonPath("$.pendingItems", not(emptyCollection())));

// Combined with size validation
assertThat(json, hasJsonPath("$.activeUsers", allOf(
    emptyCollection(),
    collectionWithSize(equalTo(0))
)));

// Using with fluent assertions
with(json)
    .assertThat("$.activeUsers", emptyCollection())
    .and()
    .assertThat("$.completedTasks", emptyCollection())
    .and()
    .assertThat("$.pendingItems", not(emptyCollection()));

Advanced Usage Patterns

Nested Collection Validation

Combining collection matchers with JsonPath expressions for deep validation:

String json = "{\"departments\":[{\"name\":\"Engineering\",\"employees\":[{\"name\":\"Alice\"},{\"name\":\"Bob\"}]},{\"name\":\"Marketing\",\"employees\":[]}]}";

// Validate nested collection sizes
assertThat(json, hasJsonPath("$.departments", collectionWithSize(equalTo(2))));
assertThat(json, hasJsonPath("$.departments[0].employees", collectionWithSize(equalTo(2))));
assertThat(json, hasJsonPath("$.departments[1].employees", emptyCollection()));

// Validate all employee collections
assertThat(json, hasJsonPath("$.departments[*].employees", everyItem(
    instanceOf(Collection.class))));

// Complex nested validation
with(json)
    .assertThat("$.departments", collectionWithSize(greaterThan(1)))
    .and()
    .assertThat("$.departments[0]", mapContainingKey(equalTo("employees")))
    .and()
    .assertThat("$.departments[0].employees", collectionWithSize(greaterThan(0)));

Map Structure Validation

Comprehensive map validation combining key and value matchers:

String json = "{\"apiResponse\":{\"status\":\"success\",\"code\":200,\"data\":{\"count\":5,\"items\":[]}}}";

// Comprehensive map validation
assertThat(json, hasJsonPath("$.apiResponse", allOf(
    mapContainingKey(equalTo("status")),
    mapContainingKey(equalTo("code")),
    mapContainingKey(equalTo("data")),
    mapContainingValue(equalTo("success")),
    mapContainingValue(equalTo(200))
)));

// Nested map validation
assertThat(json, hasJsonPath("$.apiResponse.data", allOf(
    mapContainingKey(equalTo("count")),
    mapContainingKey(equalTo("items")),
    mapContainingValue(instanceOf(Integer.class)),
    mapContainingValue(instanceOf(Collection.class))
)));

// Value type and content validation
with(json)
    .assertThat("$.apiResponse", mapContainingValue(equalTo("success")))
    .and()
    .assertThat("$.apiResponse.data", mapContainingValue(greaterThan(0)))
    .and()
    .assertThat("$.apiResponse.data.items", emptyCollection());

Integration with JsonPath Results

These matchers are specifically designed to work with JsonPath evaluation results:

import com.jayway.jsonpath.JsonPath;

String json = "{\"data\":{\"users\":[{\"active\":true},{\"active\":false}],\"metadata\":{\"total\":2,\"page\":1}}}";

// Direct JsonPath evaluation with matchers
List<Object> users = JsonPath.read(json, "$.data.users");
assertThat(users, collectionWithSize(equalTo(2)));

Map<String, Object> metadata = JsonPath.read(json, "$.data.metadata");
assertThat(metadata, mapContainingKey(equalTo("total")));
assertThat(metadata, mapContainingValue(equalTo(2)));

// Combined with JsonPath matchers
assertThat(json, isJson(allOf(
    withJsonPath("$.data.users", collectionWithSize(greaterThan(1))),
    withJsonPath("$.data.metadata", mapContainingKey(equalTo("total"))),
    withJsonPath("$.data.metadata", mapContainingValue(greaterThan(0)))
)));

Type Safety and Generic Support

The collection matchers provide type-safe operation while maintaining flexibility:

// Type-safe value matching
Matcher<Map<String, String>> stringMapMatcher = mapContainingValue(startsWith("prefix"));
Matcher<Map<String, Integer>> intMapMatcher = mapContainingValue(greaterThan(0));

// Generic collection matching
Matcher<Collection<String>> stringCollectionMatcher = collectionWithSize(greaterThan(0));

// Usage maintains type safety
String json = "{\"stringMap\":{\"key\":\"prefixValue\"},\"intMap\":{\"count\":5}}";
assertThat(json, hasJsonPath("$.stringMap", stringMapMatcher));
assertThat(json, hasJsonPath("$.intMap", intMapMatcher));

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