Nullables Testing Pattern

Nullables: Testing Without Mocks

STARTER_CHARACTER = ⭕️

Nullables are production code with an off switch: classes with external I/O anywhere in their dependencies offer create() (real) and createNull() (I/O disabled, everything else runs normally). Tests are narrow (focused on one class), sociable (dependencies run for real), and state-based (assert outputs and state, never method calls). Don't use mocking libraries or DI frameworks — Nullables make them unnecessary.

The cut

Stub at the lowest point — the third-party edge — never your own code:

OrderService  →  PaymentClient  →  HttpClient  →  third-party lib
  app code       high-level        low-level       ✂ stubbed when nulled
                 wrapper           wrapper

• PaymentClient is a high-level wrapper: it abstracts one service and speaks domain language.
• HttpClient is a low-level wrapper: it abstracts one technology and is generic and highly reusable.
• The low-level wrapper holds the fork: create() wires the real library (node http, RestTemplate); createNull() wires an embedded stub — your code, returning canned data, doing no I/O.
• Everything left of the cut is your code and runs for real in tests.

With mocks, you only mock code you own; with Nullables, you only stub code you don't own. Only the bottom layer has a stub — one per technology. Everything above runs real in tests, so a bug anywhere in your code turns tests red. Mocking your own classes breaks that chain: mocked code never runs, and its bugs hide behind green tests.

An invented internal seam is the same break in disguise: cutting at rows() → List<Row> instead of the driver puts your mapping loop below the seam, where nulled tests never run it. The test: any parsing, mapping, or normalization you wrote must sit above the cut. When the third-party API is a chain of objects, mirror it — one stub class can play the whole chain (see the low-level wrapper files).

Two channels, plus events

Every class that talks to infrastructure anywhere in its dependencies offers the same two factory methods:

Clock.create()                            // production: the real system clock
Clock.createNull({ now: "2024-01-01" })   // test: frozen time, no external state

Tests interact with a nulled instance through three moves:

• Reads — configure what the world answers, as createNull(...) parameters in the caller's domain terms: PaymentClient.createNull({ approved: false }), DieRoller.createNull([3, 5, 1]). A single value repeats forever; a list is consumed in order, then fails fast. An error is just another configured response: createNull([{ error: "boom" }]).

• Writes — observe what the code sent, as domain data (track the data, not the rendered string):

  const emails = emailer.trackOutput();
  await service.register("a@b.com");
  assert.deepEqual(emails.data, [{ to: "a@b.com", subject: "Welcome" }]);

  The same tracker can prove a negative — a test where registration is refused asserts emails.data is []: no email went out.

• Pushed events — fire a simulated incoming event through the same handler path a real event takes: network.simulateMessage("client-1", "Hello").

These ride on two tiny utilities, OutputListener/OutputTracker and ConfigurableResponses. When the codebase lacks them, add them — example implementations in utilities.md.

Procedure

Start from the code you need to test. For a whole system, pick one class and repeat; conversion order across many classes is in migration.md.

1. List the dependencies of the class under test. Classify each one you need to control:
   • Pure logic, nothing external below → test directly, nothing to null.
   • Value object or config → createTestInstance() with safe overridable defaults. If it holds an infrastructure object, default it to the nulled version.
   • Already has createNull() → go to step 4.
   • Touches infrastructure below but has no createNull() → step 2.
2. Follow that dependency's chain down until you reach code you don't own — a third-party library doing I/O. That is the edge.
   • The codebase already has a wrapper for this technology (search createNull, Stubbed, infrastructure/) → reuse it, go to step 3.
   • No wrapper → build one: building-low-level-wrappers-static.md when the seam is an interface you declare, building-low-level-wrappers-dynamic.md when any object with the right methods will do.
3. Walk back up the chain, giving each class create() and createNull() that compose its nulled dependencies — follow building-high-level-wrappers.md; its recipe carries the decomposition and tracker moves that keep layers honest, and this is where abstractions leak if you rush. Done when every class between the edge and the class under test has both factories, configuration in its own language decomposed downward, and its write channel tracked.
4. Write the tests following consuming-nullables.md — the fixture shape, error configs, and time travel live there. Done when every read, write, and error path of the class is asserted — both directions per dependency: the exact outgoing request (via that dependency's tracker) and the returned answer being used.

Converting a mock-based suite → migration.md. Improving existing nullables → walk their layers and check each against The cut and the rules below, plus: no leftover throwaway stubs. Structuring a new app around this (optional) → architecture.md.