### Text Context Conditions

- `isText`/`isNotText` - assert that the node is a text node, with optional specific text - note: this can also be achieved with `hasValue`, but adds
some extra checking that this is a text node
```java
assertJson("\"theText\"")
.isText();

assertJson("\"theText\"")
.isText("theText");

assertJson("{\"child\":{\"age\":123}}")
.at("/child/age").isNotText();

assertJson("{\"child\":{\"name\":"Bob"}}")
.at("/child/age").isNotText("Bert");
```
- `isEmptyText`/`isNotEmptyText` - both of these require the node to be text, and then assert that the text is `""` or not
```java
assertJson("\"\"")
.isEmptyText();

// FAILS! - wrong type
assertJson("0")
.isNotEmptyText();

// non empty
assertJson("\"0\"")
.isNotEmptyText();
```
- `matches(Pattern|String)` - assert that the **text** of this node matches a regular expression - some common patterns are available in the `Patterns` class
```java
assertJson(jsonString)
.at("/guid").matches(GUID_PATTERN);
```
- `textMatches`- allows a custom predicate to be passed in order to perform a custom check
```java
assertJson("\"a-b-c\"")
.textMatches("Has dashes", text -> text.contains("-"));
```
- `textContains`/`textDoesNotContain` - reuses the logic of the regular expression matcher to find substrings
- `textStartsWith`/`textDoesNotStartWith` - reuses the logic of the regular expression matcher to check the prefix of a text node's text

### Numeric Context Conditions
- `isGreaterThan`, `isGreaterThanOrEqualTo`, `isLessThan`, `isLessThanOrEqualTo` - these
require that the node is a number of a numeric type, and compares
```java
assertJson(jsonString)
.at("/count").isGreaterThan(9);
```
More specific typed versions - `isGreaterThanInt` or `isLessThanLong` also exist to avoid a test
passing through accidental type coercion or overflow.
- `isBetween` - asserts that a number falls in a range
```java
assertJson("{number:12}")
.at("/number").isBetween(2, 29);
```
- `isZero` - asserts that the number is zero
- `isNumber`, `isInteger`, `isLong`, `isDouble` - assert this is a numeric node
or of a specific numeric type

### Boolean Context Conditions
- `isTrue`/`isFalse` - requires the node to be boolean and have the correct value
- `isBoolean`/`isNotBoolean` - asserts the type of the node

### Object Context Conditions
- `isObject`/`isNotObject` - asserts the type of the node
- `containsKey`/`containsKeys`/`doesNotContainKey`/`doesNotContainKeys` - checks for the presence of a given set of keys in the object
- `containsKeysExactly` - requires the given keys to be present in the exact order provided
- `containsKeysExactlyInAnyOrder` - requires the given keys all to be present, regardless of order in the JSON

### Array Context Conditions
- `isArray`/`isNotArray` - asserts the type of the node
- `isArrayContaining`/`isArrayContainingExactlyInAnyOrder` - **potentially slow** assertions over the contents
of an array. Tries all permutations of matching the provided elements to the array elements, allowing for
duplicates. Uses loose `hasValue` style matching when values provided:
```java
assertJson("[1, 2, 3, 4]")
.isArrayContaining(1, 4);

assertJson("[1, 2, 3, 4]")
.isArrayContainingExactlyInAnyOrder(1, 2, 3, 4);
```
- `isArrayContainingExactly` - strictly proves that each element in the array
matches the elements provided:
```java
assertJson("[1, 2, 3, 4]")
.isArrayContainingExactly(1, 2, 3, 4);
```
This is more efficient at runtime as it has a simple job.

There are two main ways to assert the contents of an array. It can be done by
value as illustrated above, or it can be done by condition list.

To use the `isArrayContaining` suite of functions with a condition list,
we call `conditions()` within the `ConditionList` class to create a
fluent builder of a list of conditions. As the fluent builder for assertions
adds conditions to the assertion, so the fluent builder inside
`ConditionList` treats each additional condition as an element to search for
in the array:

```java
assertJson("[" +
"{\"name\":\"Model\",\"ok\":true}," +
"{\"name\":\"Model\",\"ok\":false}," +
"{\"name\":\"Assert\"}," +
"{\"age\":1234}" +
"]")
.isArrayContainingExactlyInAnyOrder(conditions()
.at("/name").isText("Assert")
.at("/name").hasValue("Model")
.at("/ok").isFalse()
.at("/age").isNumberEqualTo(1234));
```

In the above example, the conditions, between them, represent a unique
match in each element of the list, but a condition may match more than one
element (as `.at("/name".isText("Assert")` does). This is where the
permutational search of the ArrayCondition helps to find the best possible match.

Where a single condition cannot describe the required match for an element
then `satisfies`, which is part of every node, allows a `ConditionList`:

```java
assertJson("[" +
"{\"name\":\"Model\",\"ok\":true}," +
"{\"name\":\"Model\",\"ok\":false}," +
"{\"name\":\"Model\"}," +
"{\"age\":1234}" +
"]")
.isArrayContainingExactlyInAnyOrder(conditions()
// condition A
.at("/name").isText("Model")

// condition B
.satisfies(conditions()
.at("/name").hasValue("Model")
.at("/ok").isTrue())

// condition C
.satisfies(conditions()
.at("/ok").isFalse()
.at("/name").isText("Model"))

// condition D
.at("/age").isNumberEqualTo(1234));
```

Each of these composite conditions allows the whole DSL. They're
composed together using `Condition.and`.

> A Hamcrest matcher could also be used with `ConditionList`
> via `matches(Matcher)`

## Size Assertions (various types)

Object, String and Array can be said to be _sizeable_. For Object, the size is
the number of keys. For String, it's the number of characters. For Array it's the number
of elements.

We can assert this with `hasSize`:

```java
assertJson("\"some string\"")
.hasSize(11);

assertJson("[1, 2, 3]")
.hasSize(3);
```

The general purpose `Number` based numeric assertions can be used to assert size via the
`size()` function, which enters the `NumberComparison` context:

```java
// assert that the array has a size between 3 and 9
assertJson("[1, 2, 3]")
.size().isBetween(3, 9);
```

## Whole Tree Comparison

The tree comparison is intended to perform a semantic comparison of a JSON
tree with another.

It can be used in conjunction with the `at` part of the Node DSL:

```java
assertJson("{\"name\":\"ModelAssert\",\"versions\":[1.00, 1.01, 1.02]}")
.at("/versions")
.isEqualTo("[1.00, 1.01, 1.02]");
```

It can also be customised using `where`.

### Where Context

This is used to customise how whole tree comparison works.

The `where` function moves us from node context to customisation of `isEqualTo`:

```java
assertJson("{\"name\":\"ModelAssert\",\"versions\":[1.00, 1.01, 1.02]}")
.where()
.keysInAnyOrder()
.isEqualTo("{\"versions\":[1.00, 1.01, 1.02], \"name\":\"ModelAssert\"}");
```

In the where context, we can add general leniency overrides, or specify overrides
for particular paths.

- `keysInAnyOrder`/`keysInOrder` - controls whether objects observe order checks - when used just after `where` this applies to the whole tree, otherwise it applies to the path exression
- `objectContains` - the object ignored missing values in the _actual_
- `arrayInAnyOrder` - array elements can be in any order
- `arrayContains` - array elements can be in any order and the actual may have additional elements
- `path` - start customising the rule for a particular path in the tree:
```java
// turn off key order sensitivity for the `address` field
assertJson(...)
.where().path("address").keysInAnyOrder()
.isEqualTo(...);
```
The path is expressed as a series of values, which can be:
- `String` - conforming to a JSON Pointer, but no `/`
- Regular expression for matching a field - i.e. `Pattern`
- `PathWildCard` - either `ANY` or `ANY_SUBTREE` - allowing path matching of one or n levels of fields
- `at` - a synonym for `path` where the whole JSON Pointer style path is provided - this is a short-hand for paths where there are no wildcards

Within the path expression, we then add further conditions:

- Any conditions from Node context
- `keysInAnyOrder`/`keysInOrder` - specific matches for the current path
- `objectContains` - the object ignored missing values in the _actual_
- `arrayInAnyOrder` - array elements can be in any order
- `arrayContains` - array elements can be in any order and the actual may have additional elements
- `isIgnored` - the path is just ignored

The purpose of the `where` and `path` contexts is to allow for things
which cannot be predicted at the time of coding, or which do not matter
to the result.

A good example is GUIDs in the output. Let's say we have a process which
produces JSON with random GUIDs in it. We want to assert that there ARE GUIDs
but we can't predict them:

```java
assertJson("{\"a\":{\"guid\":\"fa82142d-13d2-49c4-9878-619c90a9f986\"}," +
"\"b\":{\"guid\":\"96734f31-33c3-4e50-a72b-49bf2d990e33\"}," +
"\"c\":{\"guid\":\"064c8c5a-c9c1-4ea0-bf36-1994104aa870\"}}")
.where()
.path(ANY_SUBTREE, "guid").matches(GUID_PATTERN)
.isEqualTo("{\"a\":{\"guid\":\"?\"}," +
"\"b\":{\"guid\":\"?\"}," +
"\"c\":{\"guid\":\"?\"}}");
```

Here, the `path(ANY_SUBTREE, "guid").matches(GUID_PATTERN)` phrase is
allowing anything _ending_ in `guid` to be matched using `matches(GUID_PATTERN)`
instead of matching it against the JSON inside `isEqualTo`.

This can be done more specifically using `at`:

```java
assertJson("{\"a\":{\"guid\":\"fa82142d-13d2-49c4-9878-619c90a9f986\"}," +
"\"b\":{\"guid\":\"96734f31-33c3-4e50-a72b-49bf2d990e33\"}," +
"\"c\":{\"guid\":\"064c8c5a-c9c1-4ea0-bf36-1994104aa870\"}}")
.where()
.at("/a/guid").matches(GUID_PATTERN)
.at("/b/guid").matches(GUID_PATTERN)
.at("/c/guid").matches(GUID_PATTERN)
.isEqualTo("{\"a\":{\"guid\":\"?\"}," +
"\"b\":{\"guid\":\"?\"}," +
"\"c\":{\"guid\":\"?\"}}");
```

> Note: the rules used with `where` are evaluated in reverse order
> so the most general should be provided first, and the most specific last.

#### Loose Array Matching

**Warning: performance implications** both `arrayInAnyOrder` and `arrayContains`
try every possible combination of array element in the expected against the
actual in order to work out if the expected elements are present. For
small arrays, this is not a problem, and the unit tests of this project
run very quickly, proving that.

However, an array can, itself, contain objects or other arrays. This can lead
to a large permutational explosion, which can take time.

The easiest way to relax array ordering rules is to use `where().arrayInAnyOrder()`
while setting up `isEqualTo`:

```java
assertJson("{\"name\":\"ModelAssert\",\"versions\":[1.00, 1.01, 1.02]}")
.where()
.arrayInAnyOrder()
.isEqualTo("{\"name\":\"ModelAssert\", \"versions\":[1.02, 1.01, 1.00]}");
```

If only a specific array may be in a random order, it may be better to specialise
this by path:

```java
assertJson("{\"name\":\"ModelAssert\",\"versions\":[1.00, 1.01, 1.02]}")
.where()
.path("versions").arrayInAnyOrder()
.isEqualTo("{\"name\":\"ModelAssert\", \"versions\":[1.02, 1.01, 1.00]}");
```

And, if the value in the expected doesn't contain all the values from the
array in the actual, then we can use `arrayContains` to both relax the order
and allow matching of the ones found:

```java
assertJson("{\"name\":\"ModelAssert\",\"versions\":[1.00, 1.01, 1.02]}")
.where()
.path("versions").arrayContains()
.isEqualTo("{\"name\":\"ModelAssert\", \"versions\":[1.02]}");
```

> Note: loose array comparison also honours the rules set in where
> for the child nodes of the array. **The paths described are routes within
> the actual tree, not the expected tree.**. So as every combination of
> match is tried, the path rules may perform different comparisons on the
> expected data, as it's checked against each actual.

#### Common `where` Configuration

The `configuredBy` function on the `WhereDsl` allows a common comparison configuration
to be implemented and plugged in:

```java
@Test
void matchesAnyGuidUsingCommonConfiguration() {
assertJson("{\"a\":{\"guid\":\"fa82142d-13d2-49c4-9878-619c90a9f986\"}," +
"\"b\":{\"guid\":\"96734f31-33c3-4e50-a72b-49bf2d990e33\"}," +
"\"c\":{\"guid\":\"064c8c5a-c9c1-4ea0-bf36-1994104aa870\"}}")
.where()
.configuredBy(ExamplesTest::ignoreGuids)
.isEqualTo("{\"a\":{\"guid\":\"?\"}," +
"\"b\":{\"guid\":\"?\"}," +
"\"c\":{\"guid\":\"?\"}}");
}

## Customisation

There's room for custom assertions throughout the DSL, and if necessary,
the `Satisfies` interface, allows a condition to be added fluently. Conditions
are based on the `Condition` class. The existing conditions can be used directly
if necessary, and can be composed using `Condition.and` or `Condition.or`
where needed. Similarly, there's a `not` method in the `Condition`
class `Not` to invert any condition as well as `invert` on `Condition` to invert
the current condition.

A custom condition can be fed to `satisfies`:

```java
// using `and` along with functions from the
// condition classes
assertJson("\"some string\"").satisfies(
textMatches(Pattern.compile("[a-z ]+"))
.and(new HasSize(12)));

// using or and inverting the condition - this will
// pass as it fails both the ORed conditions, but the
// whole statement is inverted
assertJson("\"some string!!!\"").satisfies(
textMatches(Pattern.compile("[a-z ]+"))
.or(new HasSize(12))
.inverted());
```

## Interoperability

The assertions can be used stand-alone with `assertJson` or can be built as Hamcrest matchers. The assertion
can also be converted to a `Mockito` `ArgumentMatcher`.

### Mockito Usage

Assuming Mockito 3, the `toArgumentMatcher` method converts the `Hamcrest` style syntax into Mockito's native
`ArgumentMatcher`. Older versions of `Mockito` used Hamcrest natively.

The json matcher can then be used to detect calls to a function either with `verify`/`then` or when setting
up responses to different inputs:

```java
// detecting calls based on the json values passed
someInterface.findValueFromJson("{\"name\":\"foo\"}");

then(someInterface)
.should()
.findValueFromJson(argThat(json()
.at("/name").hasValue("foo")
.toArgumentMatcher()));

// setting up responses based on the json
given(someInterface.findValueFromJson(argThat(json()
.at("/name").hasValue("foo")
.toArgumentMatcher())))
.willReturn("foo");

assertThat(someInterface.findValueFromJson("{\"name\":\"foo\"}")).isEqualTo("foo");
```

Note, this works with all the types of JSON input sources supported by the Hamcrest version of the library.
You need to choose the type of input via the `json`, `jsonFile` methods etc.

### Interoperability with Spring MVC Matchers

Rather than:

```java
// clause inside ResultMatcher
jsonPath("$.name", "ModelAssert")
```

We can construct the hamcrest matcher version of ModelAssert's JsonAssertion:

```java
content().string(
json()
.at("/name")
.hasValue("ModelAssert"))
```

While this syntax is of limited value in this simple case, the more powerful comparisons supported
by this library are equally possible after the `json()` statement starts creating a matcher.

### Custom Object Mappers

By default, Model Assert uses two `ObjectMapper` objects - one for loading JSON and one for loading YAML.
These can be overridden for the current thread (allowing concurrent testing) and it's advisable to do this
in the `@BeforeAll` of a text fixture:

```java
@BeforeAll
static void beforeAll() {
// support LocalDateTime
overrideObjectMapper(defaultObjectMapper()
.registerModule(new JavaTimeModule())
.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS));

// stop parsing `yes` to mean Boolean `true`
overrideYamlObjectMapper(new ObjectMapper(
new YAMLFactory()
.configure(PARSE_BOOLEAN_LIKE_WORDS_AS_STRINGS, true)));
}
```

and when replacing the object mapper in setup, it's a good idea to put it back in the tear down:

```java
@AfterAll
static void afterAll() {
clearObjectMapperOverride();
clearYamlObjectMapperOverride();
}
```

Any assertions used while the override is in place will use the alternative object mapper.

> Note: if using a common alternative object mapper, maybe consider building a small JUnit 5 test extension
> or [use a base class](./src/test/java/uk/org/webcompere/modelassert/json/OverrideObjectMapper.java) for your tests
> which contains the common set up

The functions `defaultObjectMapper` and `defaultYamlMapper` in `JsonProviders` can be used to create a basic `ObjectMapper`
to base a custom one on.

## API Stability

The classes in the root package `uk.org.webcompere.modelassert.json` are the jumping
on point for the API and they will be changed rarely.

Functions elsewhere will be accessed via the fluent API and may move between packages
in later versions, though this should be resolved without changing consuming code.

SemVer numbering will indicate possible breaking changes by increments to the minor version number. Patch
versions are unlikely to have any noticeable effect on the API.

## Contributing

If you experience any problems using this library, or have any ideas, then please
[raise an issue](https://github.com/webcompere/model-assert/issues/new/choose). Please
check for any [existing issues](https://github.com/webcompere/model-assert/issues) first.