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

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 permanent design improvements. Steps 4-5 are temporary scaffolding.

Quick Example

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

// BEFORE -- no seam, can't test without hitting real API
const processOrder = (order: Order): OrderResult => {
  const tax = fetchTaxRate(order.region);
  return { ...order, total: order.subtotal * (1 + tax) };
};

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

const processOrder = (
  order: Order,
  resolveTax: TaxResolver = fetchTaxRate,
): OrderResult => {
  const tax = resolveTax(order.region);
  return { ...order, total: order.subtotal * (1 + tax) };
};

// Test -- swap in a fake at the enabling point (the argument list)
const result = processOrder(testOrder, () => 0.08);

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