File: unbundled-database/testtestervalidation.py

Date: 2026-05-29

Time: 10:21

I'll work from what's available in the file content provided.

unbundled-database/testtestervalidation.py

Purpose

This is the tester-stage validation suite — a second layer of tests that sits above the primary test file (testunbundleddatabase.py). Its job is twofold:

1. Spec compliance: TestSpecExample runs the exact "Example Usage" scenario from the module's design spec end-to-end, serving as a living executable specification. If the spec example ever diverges from the implementation, this test breaks.

2. Edge-case coverage: TestEdgeCases captures behaviors from reviewer notes and spec constraints that the primary tests might not cover — persistence roundtrips, empty inputs, internal state leaks on rebuild, catch-up vs. rebuild equivalence.

This naming convention (testtestervalidation.py) appears throughout the repo — it's the pattern for a "tester" layer that validates the test suite's own contracts against the spec, distinct from the testertest*.py files that are generated test harnesses.

Key Components

TestSpecExample

A single test method, testfullspec_example, that exercises the entire UnbundledDatabase API in one linear flow:

This test is a contract test — it asserts exact counts, exact field values, and exact operation types (event.operation == "update"). Changing any behavior in the implementation will fail here before it fails anywhere else.

TestEdgeCases

Seven focused tests, each targeting a specific invariant:

| Test | What it guards |

|------|---------------|

| testrebuildaftercatchupmatcheslive | Catch-up via snapshot and rebuild via event replay produce identical derived state |

| testlsnsequentialnogaps | LSNs are 1-indexed and strictly sequential |

| testnesteddict_values | Nested dicts in records survive write/read without corruption |

| testemptysearchall | searchall([]) returns [], not an error |

| teststorageenginerebuildclearsoldstate | rebuild wipes phantom/stale state before replaying WAL |

| testaddderivedsystemnocatchup | catch_up=False means the system starts empty, only seeing future writes |

| testwalpersistence_roundtrip | WAL written to disk can fully reconstruct storage in a new UnbundledDatabase instance |

Patterns

Spec-as-test: TestSpecExample mirrors the spec's example usage verbatim. This is a deliberate choice — it prevents spec/implementation drift and serves as onboarding documentation for anyone reading the spec first.

State-equivalence assertion: testrebuildaftercatchupmatcheslive compares two independent derived systems via get_state(), asserting that two different code paths (snapshot-based catch-up vs. full event replay) produce identical output. This is a classic commutativity check for eventually-consistent systems.

Injection-then-rebuild: teststorageenginerebuildclearsoldstate manually injects db.storage._data["phantom"] to simulate corrupted or stale state, then asserts rebuild eliminates it. This pattern of polluting internal state to verify cleanup is common in storage-engine tests.

Filesystem isolation: testwalpersistence_roundtrip uses tempfile.TemporaryDirectory for disk-backed WAL tests, ensuring no cross-test filesystem contamination.

Dependencies

Imports from unbundled_database:

External: pytest, os, tempfile

Imported by: Nothing — this is a leaf test file. It's consumed by the test runner.

Note: os is imported but unused (likely a leftover from an earlier version of the persistence test).

Flow

The test suite runs linearly within each test, but the underlying data flow in the system under test is:


put/delete → WAL append → CDCStream event → flush → derived systems consume events

TestSpecExample.testfullspec_example walks through the full lifecycle:

1. Create database, register three derived systems

2. Insert 3 records, flush to propagate

3. Assert query/index/search results

4. Update a record, assert CDC event fields (operation, oldvalue, newvalue)

5. Flush, verify derived systems reflect the update

6. Delete a record, verify cascading effects

7. Add a new derived system with catch_up=True, verify it sees existing data

8. Rebuild an existing system, verify event count

9. Insert with unflushed lag, assert lag > 0, flush, assert lag == 0

10. Inspect pipeline state for record count and derived system count

11. Rebuild storage from WAL, verify final state

Invariants

Error Handling

This file contains no explicit error handling — it's a test suite that asserts happy-path invariants and edge-case behaviors. Failures surface as AssertionError via pytest. There are no pytest.raises blocks, meaning none of these tests verify error conditions (e.g., querying a nonexistent index, or double-deleting a key). That's a gap this file intentionally leaves to the primary test suite or the tester harness.

Topics to Explore

Beliefs