0
# json-path-assert
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: json-path-assert
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.jayway.jsonpath</groupId>
13
      <artifactId>json-path-assert</artifactId>
14
      <version>2.9.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;
22
```
23

24
For JsonAsserter fluent interface:
25

26
```java
27
import static com.jayway.jsonassert.JsonAssert.with;
28
```
29

30
## Basic Usage
31

32
```java
33
import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;
34
import static com.jayway.jsonassert.JsonAssert.with;
35
import static org.hamcrest.Matchers.*;
36
import static org.junit.Assert.assertThat;
37

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

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

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

48
// Fluent assertion interface
49
with(json)
50
    .assertThat("$.store.name", equalTo("Little Shop"))
51
    .and()
52
    .assertThat("$.store.books[*]", hasSize(2))
53
    .and()
54
    .assertNull("$.store.discount");
55

56
// Combined matchers for comprehensive validation
57
assertThat(json, isJson(allOf(
58
    withJsonPath("$.store.name", equalTo("Little Shop")),
59
    withJsonPath("$.store.books[*]", hasSize(2)),
60
    withoutJsonPath("$.expensive")
61
)));
62
```
63

64
## Architecture
65

66
The library is built around several key components:
67

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

74
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.
75

76
## Capabilities
77

78
### JsonPath Matchers
79

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

82
```java { .api }
83
// Path existence validation
84
public static Matcher<? super Object> hasJsonPath(String jsonPath);
85
public static <T> Matcher<? super Object> hasJsonPath(String jsonPath, Matcher<T> resultMatcher);
86
public static Matcher<? super Object> hasNoJsonPath(String jsonPath);
87

88
// JSON validity checks
89
public static Matcher<Object> isJson();
90
public static Matcher<Object> isJson(Matcher<? super ReadContext> matcher);
91
public static Matcher<String> isJsonString(Matcher<? super ReadContext> matcher);
92
public static Matcher<File> isJsonFile(Matcher<? super ReadContext> matcher);
93

94
// ReadContext matchers for combining conditions
95
public static Matcher<? super ReadContext> withJsonPath(String jsonPath, Predicate... filters);
96
public static Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath);
97
public static <T> Matcher<? super ReadContext> withJsonPath(String jsonPath, Matcher<T> resultMatcher);
98
public static <T> Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath, Matcher<T> resultMatcher);
99
public static Matcher<? super ReadContext> withoutJsonPath(String jsonPath, Predicate... filters);
100
public static Matcher<? super ReadContext> withoutJsonPath(JsonPath jsonPath);
101
```
102

103
[JsonPath Matchers](./jsonpath-matchers.md)
104

105
### Fluent Assertion Interface
106

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

109
```java { .api }
110
// Factory methods for creating JsonAsserter instances
111
public static JsonAsserter with(String json);
112
public static JsonAsserter with(Reader reader) throws IOException;
113
public static JsonAsserter with(InputStream is) throws IOException;
114

115
// Core assertion methods
116
public interface JsonAsserter {
117
    <T> JsonAsserter assertThat(String path, Matcher<T> matcher);
118
    <T> JsonAsserter assertThat(String path, Matcher<T> matcher, String message);
119
    <T> JsonAsserter assertEquals(String path, T expected);
120
    <T> JsonAsserter assertEquals(String path, T expected, String message);
121
    JsonAsserter assertNotDefined(String path);
122
    JsonAsserter assertNotDefined(String path, String message);
123
    JsonAsserter assertNull(String path);
124
    JsonAsserter assertNull(String path, String message);
125
    <T> JsonAsserter assertNotNull(String path);
126
    <T> JsonAsserter assertNotNull(String path, String message);
127
    JsonAsserter and();
128
}
129
```
130

131
[Fluent Assertions](./fluent-assertions.md)
132

133
### Collection and Map Matchers
134

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

137
```java { .api }
138
public static CollectionMatcher collectionWithSize(Matcher<? super Integer> sizeMatcher);
139
public static Matcher<Map<String, ?>> mapContainingKey(Matcher<String> keyMatcher);
140
public static <V> Matcher<? super Map<?, V>> mapContainingValue(Matcher<? super V> valueMatcher);
141
public static Matcher<Collection<Object>> emptyCollection();
142
```
143

144
[Collection Matchers](./collection-matchers.md)
145

146
## Types
147

148
```java { .api }
149
// Core interfaces and classes
150
interface JsonAsserter {
151
    // Methods defined in capabilities above
152
}
153

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

158
// Implementation classes (internal use)
159
class IsJson<T> extends TypeSafeMatcher<T> { /* ... */ }
160
class WithJsonPath<T> extends TypeSafeMatcher<ReadContext> { /* ... */ }
161
class WithoutJsonPath extends TypeSafeDiagnosingMatcher<ReadContext> { /* ... */ }
162
```