bonsai

Assertions

Change tracking assertions

documentWithId: prove what a seeded document changed from, not only what it looks like now.

The post-seed baseline

Both harnesses snapshot each seeded collection once per test method, after seeding and before the test body. documentWithId (3.5.0+) compares the current document with that baseline, so a test proves a transition rather than only an end state.

The baseline belongs to one method. A mutation in one test cannot leak into the next test's from() assertion.

Asserting a transition

Java
assertThatCollection("workflowStates").documentWithId(workspaceId)
    .changedField("currentStage").from("WORKSPACE_PARTICIPANT_ADDED").to("WORKSPACE_PREPARED")
    .changedField("stageProgress[1].status").from("PENDING").to("COMPLETED")
    .unchangedField("createdAt")
    .createdField("completedAt");

from() asserts the baseline value and to() asserts the current value. Either leg alone still requires a real change. A from value equal toto is refused because it asserts nothing. Paths accept dots and[index] hops, and equality is BSON-aware.

A field absent from the baseline belongs in createdField(...);removedField(...) is the inverse. unchangedField(...) keeps an important value pinned while the surrounding document changes.

Failure shape

Every failure identifies the broken leg and aligns baseline, expected, and actual values, so the difference reads without reconstructing the original fixture.

text
Expected changed field <currentStage> to have current value <WORKSPACE_PREPARED>, but it was <PENDING>.
  field         | baseline                     | expected                     | actual
  --------------+------------------------------+------------------------------+------------------------------
  currentStage  | WORKSPACE_PARTICIPANT_ADDED  | WORKSPACE_PREPARED           | PENDING

Named boundaries

The baseline is a snapshot keyed by _id. A document created during the test under a new _id is refused by name: it has no baseline, so there is no transition to prove. A delete followed by a reinsert under the same _id is indistinguishable from an in-place update and is compared normally. If a test needs to prove the document was never replaced, assert that separately; the library tracks no incarnation identity in this release.