bookforge-ai Seam Type Selector
When to Use
Use this skill when a developer needs to substitute or intercept behavior in legacy code for testing, but cannot freely edit the code under test. Specifically:
- The code has a hard-coded dependency (global function, library call, concrete class instantiation) that prevents running it in a test harness.
- The developer asks: "How do I fake this?", "How do I test around this global?", "How do I intercept this call without a DI framework?", or "What's the right way to introduce a test double here?"
- The developer is choosing between approaches (subclass override vs. classpath swap vs. macro replacement) and needs a principled recommendation.
Do not use for greenfield code where a dependency injection framework is already in place — the framework already manages enabling points.
Context and Input Gathering
Before recommending a seam type, gather:
- Language — Is this C or C++ (preprocessor available)? A compiled OO language like Java or C# (link and object seams)? A dynamic OO language like Python or Ruby (object seams, plus text redefinition)?
- Dependency type — What exactly needs to be substituted? Options: global function, static method, constructor call, third-party library, concrete class member.
- Pervasiveness — Is this dependency called in one or two places, or scattered across dozens of files and hundreds of call sites?
- Risk tolerance — Is modifying production class structure (adding a virtual method, adding a constructor parameter) acceptable? Some teams forbid structural changes to classes under test without prior test coverage.
Process
Step 1: Confirm a seam exists
A seam (Feathers' formal definition) is "a place where you can alter behavior in your program without editing in that place." Verify the target call site qualifies:
- You want to substitute the behavior that runs at call site X.
- You can make the substitution without modifying the source text at X itself.
- There is an enabling point — a separate place where you decide which behavior to use.
If no enabling point can be identified, there is no seam. You will need to introduce one first (see dependency-breaking-technique-executor).
Step 2: Classify the dependency
| Classification | Characteristic | Examples |
|---|---|---|
| Localized | 1–5 call sites, within one class or module | One new DatabaseConnection() in a constructor |
| Pervasive | Many call sites, spread across files | 50+ calls to getenv() throughout a C codebase; all files import a logging singleton |
Pervasiveness is the primary override condition. If a dependency is pervasive, the cost of introducing object seams at every site may exceed the cost of a single link- or preprocessor-level substitution.
Step 3: Assess language capabilities
| Language | Preprocessor Seam | Link Seam | Object Seam |
|---|---|---|---|
| C | Yes (#define, #ifdef) |
Yes (object file swap) | No (procedural) |
| C++ | Yes | Yes | Yes |
| Java, Kotlin | No | Yes (classpath) | Yes |
| C# | No | Yes (assembly) | Yes |
| Python, Ruby | No | Limited | Yes (duck typing) |
| Go | No | Limited | Yes (interfaces) |
| TypeScript/JS | No | Limited (module mock) | Yes |
Step 4: Apply the selection rule
Feathers states: "In general, object seams are the best choice in object-oriented languages. Preprocessing seams and link seams can be useful at times but they are not as explicit as object seams. Tests that depend on them can be hard to maintain. Reserve preprocessing seams and link seams for cases where dependencies are pervasive and there are no better alternatives."
Decision hierarchy:
1. Is the language OO and the dependency localized?
→ Use Object Seam
2. Is the language OO but the dependency is pervasive (many call sites)?
→ Prefer Link Seam (keeps source changes minimal)
→ Fall back to Preprocessor Seam only in C/C++
3. Is the language procedural C/C++ and the dependency is pervasive?
→ Link Seam first; Preprocessor Seam if link is not feasible
4. Is the language procedural C/C++ and the dependency is localized?
→ Preprocessor Seam (only option available)
Step 5: Identify the enabling point
Every seam has an enabling point — name it explicitly. Future readers (and the developer implementing the seam) must know where to flip the switch.
| Seam Type | Where the Enabling Point Lives |
|---|---|
| Object Seam | Where the object is constructed or injected — a constructor, factory method, parameter, or setter |
| Link Seam | The build configuration — classpath entry, Makefile rule, linker flag, or IDE project setting |
| Preprocessor Seam | A preprocessor define — #define TESTING, a -DTESTING compiler flag, or an #include of a test-override header |
Step 6: Produce the recommendation artifact
Output a seam-recommendation.md (template in Outputs section) with: seam type, enabling point location, rationale, language note, and a list of compatible Part III techniques the developer can apply next.
Inputs
| Input | Required | Description |
|---|---|---|
| Source file(s) | Required | The file(s) containing the dependency to break |
| Language | Required | Programming language of the codebase |
| Dependency description | Required | What call/class/library needs to be substituted |
| Pervasiveness assessment | Recommended | Number of call sites; single file vs. codebase-wide |
| Risk constraints | Optional | Whether structural changes to production classes are allowed |
Outputs
seam-recommendation.md
## Seam Recommendation: [dependency name]
**Chosen Seam Type:** [Object / Link / Preprocessor]
**Enabling Point:**
[Exact location — e.g., "The constructor of OrderProcessor (line 42 of OrderProcessor.java)"
or "The classpath entry resolving com.example.PaymentGateway"
or "The TESTING preprocessor define passed via -DTESTING in the Makefile"]
**Rationale:**
[1–3 sentences: why this seam type for this language, dependency type, and pervasiveness level]
**Language Applicability:**
[Confirm the seam is available in the target language; note if a fallback was chosen]
**Compatible Part III Techniques:**
- [Technique name] — [one-line explanation of how it exploits this seam]
- [Technique name] — ...
**Next step:** See `dependency-breaking-technique-executor` to apply the selected technique.
Key Principles
Prefer object seams for maintainability. Object seams are explicit — the substitution is visible in the source code at the enabling point. Link and preprocessor seams substitute behavior invisibly; future readers see nothing unusual at the call site.
Every seam has an enabling point — name it explicitly. A seam without a named enabling point is incomplete. The enabling point is where the developer acts; without naming it, the recommendation cannot be implemented.
Pervasive dependencies may justify link or preprocessor seams. When a global function is called in 80 places across 20 files, introducing a virtual dispatch at each site is high-risk surgery. A single build-level substitution is safer than 80 structural edits.
Seams make the substitution point visible to future readers. The goal is not just to make tests pass today — it is to leave the codebase in a state where the next engineer can understand which behavior is being substituted and why.
Examples
Example A: Java class with a hard-coded dependency (Object Seam)
Situation: A UserService class has a constructor that directly instantiates UserRepository, which opens a database connection. No DI framework. Need to test UserService.findActiveUsers() without a real database.
Classification: Localized (one constructor site). Language: Java (OO).
Recommendation: Object Seam.
Enabling point: The UserService constructor. Introduce a second constructor that accepts a UserRepository parameter (Parameterize Constructor technique). Tests pass in a fake implementation; production code calls the original constructor.
Compatible techniques: Parameterize Constructor, Extract Interface (extract IUserRepository), Subclass and Override Method.
Example B: C++ with pervasive global calls (Link Seam)
Situation: A legacy C++ codebase has 60+ calls to log_event() (a global that writes to a syslog daemon) scattered across 15 files. Running tests triggers syslog writes and slows everything down.
Classification: Pervasive. Language: C++ (compiled, OO).
Recommendation: Link Seam.
Enabling point: The Makefile's link step. Create a test_log_event.o object file with a stub log_event() that records calls in memory. Swap it in via the Makefile for test builds. Source files are untouched.
Compatible techniques: Link-level substitution (Ch 19 procedural pattern), Encapsulate Global References (if later migration to OO is planned).
Example C: Legacy C with pervasive global calls (Preprocessor Seam)
Situation: A C codebase calls db_update(account_no, record) in 40 places across 8 files. There is no OO structure and no link-time substitution capability in the build environment.
Classification: Pervasive. Language: C (procedural — no object seam available).
Recommendation: Preprocessor Seam.
Enabling point: A #define TESTING flag passed to the C compiler (e.g., gcc -DTESTING). A localdefs.h header, included in each source file, defines a macro replacement for db_update under #ifdef TESTING that captures arguments without hitting the database.
Compatible techniques: Text Redefinition (C/C++ specific), C macro preprocessor pattern (Ch 19).
References
See references/seam-type-comparison.md for a full comparison matrix of all three seam types across language families, enabling point locations, and compatible Chapter 25 techniques.
License
CC-BY-SA-4.0 — derived from Working Effectively with Legacy Code by Michael C. Feathers (2004).
Related BookForge Skills
dependency-breaking-technique-executor— Takes a seam recommendation and applies a specific Chapter 25 technique step-by-step. This skill feeds directly into it.legacy-code-change-algorithm— The outer 6-step procedure. Seam identification is Step 3 of that algorithm; use this skill to complete it.library-seam-wrapper— Applies the link seam pattern specifically to third-party library dependencies, wrapping them in an interface.