Finding Seams

Finding Seams

For writing tests that document existing behavior once you have seams, load the characterisation-tests skill. For test-driving new behavior, load the tdd skill. For general test patterns, load the testing skill. For refactoring after tests are in place, load the refactoring skill. Use codebase-design when deciding a module's lasting responsibility and caller-facing contract; this skill introduces the minimum enabling point needed to place existing behavior under test.

Deep-dive resources are in the resources/ directory. Load them on demand:

Core Concept

A seam is a place where you can alter behavior in your program without editing in that place.

Every seam has an enabling point -- the place where you choose which behavior to activate. The source code at the seam stays identical in production and test; only the enabling point differs.

A seam is not automatically a public module interface, port, or permanent abstraction. Introduce the narrowest safe substitution point first; once behavior is characterized, let codebase-design decide whether that point belongs in the durable contract or should remain private scaffolding.

-- Michael Feathers, Working Effectively with Legacy Code (2004)

Connection to hexagonal architecture: Ports are designed-in seams. A port defines a contract (the seam), and the composition root chooses which adapter to wire in (the enabling point). If your code already uses hex arch, you have seams everywhere -- this skill is for code that lacks them. See the hexagonal-architecture skill.

When to Use

• Cannot call a function in a test harness because it reaches for external systems directly
• A function hard-codes a dependency instead of accepting it as a parameter
• Global or static dependencies make isolation impossible
• Singleton access patterns couple code to shared mutable state
• React components fetch data internally instead of receiving it via props/context

Quick Reference: Seam Types for TypeScript/JS

Putting Existing Code Under Test

Work through this before writing a single test:

1. List every hidden dependency the function reaches for -- collaborators it constructs, Date.now() / new Date(), process.env, singletons. All of them, not just the one that annoys you most.
2. Move each one to the argument list with a production default that reproduces today's behaviour exactly -- the new and the env read now live in the default, so production is unchanged. When you are done the function under test constructs nothing and reads no global.
3. Write the test by passing fakes in as arguments. A fake is a stand-in you hand-write in the test and fully control: a literal like () => 1_700_000_000_000, or a small object implementing only the methods the seam's narrow type names. Never pass the real collaborator through the seam -- not the production client, driver or service object, however cheap, local or in-memory its implementation happens to be, and whatever its own comments claim. A test built on the real collaborator still breaks when that collaborator's shape changes, which is the coupling the seam exists to cut. If the test needs vi.mock(), vi.stubEnv() or fake timers to run, a dependency is still hidden: go back to step 2 instead of reaching for them.
4. Remove any module mock of that dependency the existing tests carry -- the seam replaces it, and leaving both means the old test still cannot see what the mock hides.

When you hand the work back, name the seam type you introduced and where its enabling point is (file and line of the parameter default, the ?? fallback, or the factory call), and confirm the existing call sites are unchanged.

How to Find Seams

Look for these in the code you need to test:

1. Function parameters -- any parameter that could accept a different implementation
2. Default parameter values -- (resolve = fetchFromApi) is already a seam
3. Module imports -- anything imported can potentially be mocked (but prefer parameter injection)
4. Configuration -- env vars, config files, feature flags
5. React props and context -- components receive dependencies as props; context providers can be swapped in tests
6. Hard-coded new or direct calls -- every direct dependency is a place where a seam could exist but doesn't yet

The Progression

Ordered from preferred to last-resort. Start with the most explicit option that works:

1. Function parameter injection -- pass dependencies as arguments with production defaults (explicit, type-safe, no framework needed)
2. Higher-order functions -- return a configured function from a factory (FP composition)
3. Configuration injection -- pass config/env as parameter instead of reading globally
4. Module mocking -- vi.mock() to replace imports (scaffolding only -- migrate away as you gain coverage)
5. Subclass and override -- for legacy class-based code only (see resources/oop-patterns.md)

Steps 1-3 are candidates for a durable design only when the lasting contract earns them. Otherwise keep them private or remove them after characterisation. Steps 4-5 are normally temporary scaffolding.

Quick Example

Before you can characterise scheduleDelivery, you need a seam for its hidden dependency:

typescriptCopy code
// BEFORE -- no seam, can't test without hitting real API
const scheduleDelivery = (delivery: Delivery): DeliveryPlan => {
  const transitDays = fetchTransitDays(delivery.region);
  return { ...delivery, totalDays: delivery.preparationDays + transitDays };
};

// AFTER -- function parameter seam with production default
type TransitDaysResolver = (region: string) => number;

const scheduleDelivery = (
  delivery: Delivery,
  resolveTransitDays: TransitDaysResolver = fetchTransitDays,
): DeliveryPlan => {
  const transitDays = resolveTransitDays(delivery.region);
  return { ...delivery, totalDays: delivery.preparationDays + transitDays };
};

// Test -- swap in a fake at the enabling point (the argument list)
const result = scheduleDelivery(testDelivery, () => 2);

Production code is unchanged at every call site (the default kicks in). Tests pass a fake. The seam is the parameter; the enabling point is the argument list.

Code Smell → Technique

Common Mistakes