Field matchers

Presence: the present() ladder

present() (3.5.0) matches any non-null value of any BSON type, completing a three-rung ladder: hasField(name) means the field exists, an explicit null included; hasFieldMatching(name, present()) means it exists and is non-null; a typed matcher such as bsonDate() then pins the shape. The gap between the first two rungs is where bugs hide: a field written as an explicit null passes hasField while carrying no value. The failure message distinguishes an absent field from an explicit null and names the rung you probably wanted.

That distinction belongs to hasFieldMatching alone. hasFieldValues, allFieldValues and extractingField flatten an absent field to null before any matcher runs, and they hand the matcher the whole extracted list, once, which is never null. A bare present() there would assert nothing, so both collection-level methods refuse it and point at everyItem(present()). Reach for allDocumentsSatisfy(d -> d.hasFieldMatching(field, present())) when absence and a stored null must be told apart.

Identity: ObjectIds and UUIDs

• validObjectIdHex(): an ObjectId, or a 24-character hex string that is a valid one. The string form is what a fixture-seeded id looks like when it was written as {"$oid": "…"} and read back through a JsonPath.
• validUuid(): a UUID, or a string in canonical 8-4-4-4-12 form. The check round-trips through UUID.fromString, so the lenient group lengths that method tolerates do not slip through.

Strings: instants, blanks, regexes

• validIsoInstant(): a string that parses as an ISO-8601 instant, with Z or an offset. For a value stored as a BSON date this fails by design. Use bsonDate() to check a stored BSON date's type, or the date-comparison matchers below to compare its value.
• nonBlankString(): a string with at least one non-whitespace character.
• matchesRegex(regex): the regex must match the whole value (Pattern.matches), because “the reference looks like ORD-\d{6}” almost always means the whole value. An invalid regex throws IllegalArgumentException at construction, not a mismatch.

Payloads: validJson and jsonPath

• validJson(): a string holding a well-formed JSON object or array, parsed by MongoDB's own parser, so Extended JSON and the shell's relaxed syntax count as valid. A bare scalar is not JSON for this purpose: the payloads worth asserting on are objects and arrays.
• jsonPath(path, matcher): the value's JsonPath resolves and satisfies the inner matcher. The value may be a JSON string, a nested Document, or a list; a Document is read in the same relaxed Extended JSON form the rest of the library speaks. A path that does not resolve is a mismatch, not an error.

BSON types: bsonDate and decimal128

• bsonDate(): a BSON date, i.e. a java.util.Date, which is what the driver materialises one as. A string that merely looks like a date fails.
• decimal128(matcher): a BSON decimal128 whose exact BigDecimal value satisfies the inner matcher.

Date comparisons with Java time

Since 3.5.2, pass a LocalDate, LocalDateTime, or Instant directly to a date matcher. They also accept Date, BsonDateTime, OffsetDateTime, and ZonedDateTimeas either the threshold or the actual value. No manual conversion is needed.

• dateAfter(value) and dateBefore(value) are strict.
• dateAtOrAfter(value) and dateAtOrBefore(value) include equality.
• dateEqualTo(value) compares at BSON millisecond precision.

A LocalDate means start of day. dateAfter(day) therefore accepts later times on that same day; it does not mean “a later calendar day”. Local dates and date-times use the JVM timezone captured when the matcher is created. Each matcher accepts a second ZoneId argument to use your persistence mapping's timezone, including ZoneOffset.UTC for native driver codecs. Instants and offset/zoned values already identify an instant.

Sub-millisecond differences do not make a stored BSON date strictly before or after the threshold. Missing fields, nulls, strings, numeric epochs, and BSON's separate internal timestamp type do not match. An unsupported or out-of-range threshold or a null timezone throws IllegalArgumentException when creating the matcher. Seed BSON dates with $date Extended JSON; a timestamp written as a plain JSON string stays a string.

Value equality across BSON types

Two matchers (3.4.0+) exist because Hamcrest equality is equals() and MongoDB's is not. hasField("total", 4999) passes against a stored NumberLong, because the library compares numbers by value across BSON types; hasFieldMatching("total", equalTo(4999)) fails against the same document, because Integer.equals(Long) is false. That gap is the trap: the two forms look interchangeable and are not.

• valueEqualTo(expected): the library's own comparison, as a matcher. Numbers by value across BSON types, Decimal128 against BigDecimal, lists element by element, everything else by equals. hasFieldMatching(f, valueEqualTo(v)) and hasField(f, v) return the same verdict for every value class.
• numberComparing(matcher): normalises any stored number (Integer, Long, Double, Decimal128, BigInteger) to a BigDecimal and hands that to the inner matcher. This is the general form of decimal128(...), and it is what makes a range work without knowing which numeric type the write happened to land on.

A non-numeric value under numberComparing is a mismatch, not an error, and so are the numeric edge cases that have no BigDecimal: NaN and ±Infinity, stored as a Double, Float, or Decimal128, never match and never throw. A test that finds a NaN in the store gets a failing assertion rather than an exception three frames down.

MongoDocumentMatchers

MongoDocumentMatchers (3.4.0+) is the document vocabulary as standalone Matcher<Document> factories, a name-for-name mirror of MongoDocumentAssert: hasField(f), hasField(f, value), hasFieldMatching(f, m), hasJsonPath(p), hasJsonPath(p, value), hasJsonPathMatching(p, m), hasId(value), hasIdMatching(m), doesNotHaveField(f), and matchesJson(json, ignoringPaths…). Every one delegates to the same resolver and comparison the assert methods use, so the verdicts are identical, including the cross-type numeric rule.

Being matchers, they go two places the assert methods cannot: into allOf/anyOf/not, and into any Hamcrest-native suite A bare assertThat(document, …) on a Document you already hold with no harness and no Bonsai entry point in sight. Inside the vocabulary they feed matchesDocument and the four …Satisfying collection methods.

Two rules decide the cases people trip over:

• An absent field is a mismatch, whatever the value matcher says. The matcher is never invoked on a missing value, and the mismatch text names the field as absent alongside the keys the document does have. “Absent or matching” therefore has to be spelled out: anyOf(not(hasField(f)), hasFieldMatching(f, m)).
• A null or non-Document actual never matches Standard Hamcrest semantics mean that a bare not(hasField("error")) passes on a null document. Guard it with both(notNullValue()).and(not(...)) when the actual may be null. The Bonsai-invoked paths null-check before the matcher runs, so this only bites on the standalone route.

Bonsai's own leaf matchers describe a mismatch as field, expected, and actual only. the document itself is appended once, by the method that invoked them. Hamcrest's anyOf and not print the item themselves, so expect the document to appear one extra time under those two; that is Hamcrest's rendering, not a leak.

How mismatches read

Every matcher describes a mismatch as the value's type and its rendering, because “was a String” and “was 665f1e…” answer different halves of “why did this fail?”. Through hasFieldMatching the document itself is appended too. A representative failure: a test expecting a string timestamp where the application stored a BSON date:

A null matcher passed to any composing method is an IllegalArgumentException naming the signature. This is a test-authoring mistake, reported as one rather than as a NullPointerException three frames down.