arnesto: Skill for Claude Code

Nullables: Testing Without Mocks

STARTER_CHARACTER = ⭕️

The Problem

External I/O is slow and flaky. Tests hitting real databases, APIs, or file systems run slow and fail randomly. We want tests that run in milliseconds and never fail due to network issues.

Mocking libraries solve speed but introduce a new problem: they couple tests to implementation by verifying specific method calls. Test code using mocking libraries is brittle—it breaks when code is refactored, even when behavior is unchanged.

The Solution

Nullables are production code with an "off switch" for infrastructure—not test doubles, but real code you can ship (dry-run modes, cache warming, offline operation). They enable narrow, sociable, state-based tests:

• Narrow: Each test focuses on one class/module, not broad end-to-end flows
• Sociable: Tests use real dependencies—only infrastructure I/O is neutralized. (Contrast with "solitary" tests that mock everything, isolating the class under test.)
• State-based: Assert on outputs and state, not on which methods were called

When to Use

Use Nullables for:

• Code that talks to external systems (HTTP, files, databases, clocks, random)
• Third-party libraries you don't control
• Non-deterministic operations

Don't use Nullables for:

• Pure logic — test directly, no wrapper needed
• Your own classes — make them Nullable directly, or null their dependencies

Greenfield: Add wrappers incrementally as tests demand—don't over-engineer upfront.

Existing codebase: See migration.md for incremental conversion strategies.

The Foundation: A-Frame Architecture

A-Frame is the architectural insight that makes Nullables work especially well. Traditional layered architecture stacks Logic on top of Infrastructure, making Logic depend on slow, brittle I/O. A-Frame makes them peers instead:

        Application (coordinates)
            ↓              ↓
Logic (pure, tested)    Infrastructure (Nullables)