# Unified driver-test runner schema and per-test lifecycle conformance > Source-anchored research for Unified driver-test runner schema and per-test lifecycle conformance. Run status: COMPLETED. Parent: [MongoDB Drivers](https://llms-explorer.com/tree/mongodb-drivers/) · 5 facets · 13 facts · page: https://llms-explorer.com/tree/unified-driver-test-runner-schema-and-per-test-lifecycle-conformance/ ## Structure and components - Outcome assertions MUST read each collection through the internal MongoClient with primary read preference, local read concern, and ascending _id sort. The collection must contain exactly the expected documents; document key order may vary, but the flexible Evaluating Matches rules do not apply. An empty expected document list requires an empty collection. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) ## How it works - For each test with initialData, setup MUST use an internal MongoClient and majority write concern, drop the target collection and its named encryption auxiliary collections, apply createOptions when present, and insert the documents. If neither documents nor createOptions are present, the runner MUST create the collection. The pinned Node.js runner implements this setup before creating entities. (medium confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) ## Problems, failure modes and limitations - At specification revision 775c4bce1bfe1c409b947eae1f3eab6975fccfe3, schema compatibility requires the same major version and a file version no greater than a runner-supported version. Incompatible files MUST raise an error and MUST NOT be processed; reporting a test failure is permitted. Supporting version 2 alone does not imply support for version 1. The pinned Node.js runner asserts schema-version support before evaluating skips. (medium confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - The runner MUST create an entity map for each test and MUST NOT share maps between tests. Entity names must be unique; storing a duplicate name or retrieving a missing entity or an entity of the wrong type MUST raise an error. createEntities populates setup objects, while saveResultAsEntity can add operation results during execution. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - Operations execute in their listed order. object=testRunner dispatches special operations; other object names resolve through the current entity map. Undefined entities, unsupported operations, unsupported arguments, and incorrectly typed session references MUST raise errors. Entity-operation results and errors are captured: ignoreResultAndError suppresses their assertions; expectError otherwise requires an error, and its absence requires success; expectResult uses the specification matching rules. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - Before event assertions, the runner MUST stop enabled listeners and disable configured fail points on the same servers, including the original mongos for targetedFailPoint. Event comparisons check the client-specific observed sequence after prescribed exclusions. ignoreExtraEvents defaults to false; true permits trailing observed events after the expected sequence has matched. An empty expected array explicitly asserts no observed events, excluding ignored events. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - An unexpected error or failed assertion MUST fail the test. The runner SHOULD continue cleanup while foregoing additional assertions. Before clearing the map it MUST permit external entity access; clearing MUST end ClientSessions and close ChangeStreams and FindCursors. If the test started a transaction, it MUST terminate open transactions. These lifecycle requirements describe the specification, not proof that every implementation satisfies them. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - The transaction-cleanup procedure recommends killing sessions at suite start and after failed tests using internal clients, on the primary or each mongos. It permits ignoring Interrupted(11601) and Unauthorized(13); for Atlas it recommends ignoring Unauthorized or omitting killAllSessions because users cannot kill other users’ sessions. This permission limits what cleanup can guarantee. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - The UTF runner has its own three-way test corpus: invalid files should fail schema validation, valid-fail files should pass schema validation and fail at runtime, and valid-pass files should execute successfully. The pinned Node.js suite runner also exposes expectRuntimeError handling, separating runtime-negative cases from ordinary passing cases. (medium confidence) — [source](https://arxiv.org/html/2608.18039v1) - The authors identify a schema-evolution limitation: a driver behind on the single increasing schema version can be blocked from adopting tests for another specification. They propose feature requirements as a more flexible alternative; this is a design lesson, not a claim that a feature-list scheme has replaced schemaVersion. (low confidence) — [source](https://arxiv.org/html/2608.18039v1) ## Comparisons and alternatives - An unmet runOnRequirements array causes a skip, unlike incompatible schema versions. At least one requirement object in each applicable array must match; when both file-level and test-level arrays exist, both arrays must be satisfied. test.skipReason also requires a skip. The pinned Node.js implementation checks suite and test requirements separately. (medium confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) ## Facts and statements - Schema validation and runtime conformance are separate checks. Each format-changing major or minor version SHALL have a JSON schema; older schemas MUST remain available. A minor-version schema MUST validate all earlier minor versions within its own major series. File parsing MUST accept both relaxed and canonical Extended JSON. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/specifications/775c4bce1bfe1c409b947eae1f3eab6975fccfe3/source/unified-test-format/unified-test-format.md) - Shared YAML conformance tests remain dependent on assertion quality. The engineering retrospective reports that the Node.js runner previously checked bulk-write results too weakly and missed inconsistencies. Independently of those historical bugs, the specification’s exact outcome comparison is an explicit runner obligation. (medium confidence) — [source](https://emptysqua.re/blog/polyglots-dilemma/)