Seams

A seam is a place where you can alter behaviour without editing in that place. That definition (from Feathers’ Working Effectively with Legacy Code) is precise and worth holding exactly. The point of a seam is not “good design” in the abstract — it is leverage: a spot where you, the tester, can substitute a different behaviour at runtime without touching the lines that do the work. Every seam has an enabling point — the place where you decide which behaviour is active (a constructor argument, a parameter, a build flag).

Hard-wired code has no seams. When a function literally contains new Date() or Database.query(...), there is no place to stand outside it and say “use this instead.” The whole game of getting legacy code under test is: find or create a seam, then exploit it.

The most common seam is the object seam: inject the collaborator instead of constructing it. Take a unit hard-wired to the clock:

// no seam — behaviour is welded to the real clock
function isTrialExpired(user: User): boolean {
  const now = new Date();              // ← can't be substituted from a test
  return now.getTime() > user.trialEndsAt.getTime();
}

You cannot test “expired” vs “active” deterministically: the answer depends on the wall clock. Introduce an object seam by passing the dependency in:

interface Clock { now(): Date }
const systemClock: Clock = { now: () => new Date() };

function isTrialExpired(user: User, clock: Clock = systemClock): boolean {
  return clock.now().getTime() > user.trialEndsAt.getTime();
}

The seam is the clock parameter; the enabling point is the call site (production passes nothing and gets systemClock; the test passes { now: () => new Date('2026-01-01') }). Note the default keeps every existing caller working untouched — the change is additive, not a rewrite. This is exactly dependency injection, but DI is just one kind of seam.

Seams come in kinds, and the cheapest one wins. Feathers classifies them by where the enabling point lives. Knowing the menu lets you pick the smallest cut:

• Object seam — swap a collaborator (the Clock/Repository above). Enabling point: constructor or parameter. Best default in TS.
• Parameter seam — pass the varying value itself rather than a whole object: isTrialExpired(user, now: Date). Even smaller than injecting a Clock when you only need one reading.
• Subclass-and-override seam — wrap the hard-wired call in a protected method, then override it in a test subclass. Useful when you can’t change the signature (it’s a framework hook, or too many callers).
• Link/language seam — substitute at module-resolution or build time (a test double for an imported module, e.g. mocking ./db in the test runner). The enabling point is outside the source entirely.

The senior move is to reach for the least invasive seam that unblocks the test, not the most architecturally pure one. A parameter seam you add in thirty seconds beats an interface hierarchy you spend a day on.

The same trick tames globals and direct I/O — the seam is wherever the unit reaches outside itself. A global config singleton and a direct db.query are the same problem as new Date(): the unit names a concrete, real-world thing instead of accepting an abstraction.

// no seam — reads a global and hits the real DB
async function chargeOverdue(): Promise<number> {
  const limit = GlobalConfig.get('overdueLimit');   // global
  const rows = await db.query('SELECT * FROM invoices WHERE overdue = true'); // real DB
  return rows.filter((r) => r.amount > limit).length;
}

// seams: config and repository are passed in
interface InvoiceRepo { listOverdue(): Promise<Invoice[]> }

async function chargeOverdue(repo: InvoiceRepo, limit: number): Promise<number> {
  const rows = await repo.listOverdue();
  return rows.filter((r) => r.amount > limit).length;
}

Now a test passes a repo returning three fixed invoices and a limit, and asserts on the count — no database, no global. The function’s logic (the filter and count) was always the interesting part; the seams just let you reach it. Notice we did not “design a persistence layer” — we extracted exactly the two dependencies the test needed, and stopped.