Why is substituting at an interface your team owns stronger evidence than substituting at a vendor's own type?

### Two candidate seams for the same dependency When code depends on something a third party supplies, a test has two places it can cut. It can replace the **vendor's own type** — the client class the vendor ships, with its methods, builders and response objects — or it can replace **a narrow interface the team defined**, which one adapter class implements by calling the vendor. Both produce a test that runs fast and offline. They do not produce the same evidence, and the difference is the whole point of the question. ### Why the vendor seam produces weak evidence A stand-in for a vendor type is a **model of the vendor written from your team's understanding of it**. When the test then passes, what it has confirmed is that your code behaves correctly *against your beliefs about the vendor*. The vendor was never present, and nothing in the suite can tell you those beliefs are wrong. Four specific failure modes follow: - **Semantics you modelled incorrectly.** Retry behaviour, pagination, whether a missing record raises an error or returns an empty result, whether a returned collection is a live view, whether a client caches. Your stand-in returns whatever you assumed. Production returns what the vendor actually does. - **Surface size.** A vendor client typically exposes far more than your code uses, often behind builders and wrapper types. Replacing it means constructing a lot of vendor-shaped scaffolding in every test, which is expensive to write and expensive to change. - **Silent drift on upgrade.** When you take a new version of the vendor library, the behaviour it ships may change while your stand-in stays exactly as written. The suite goes green precisely because nothing about the real dependency was involved. - **Vendor vocabulary leaks into your tests.** Your test file now talks in the vendor's nouns, so swapping vendors means rewriting tests that had nothing to do with the vendor's identity. ### Why an owned interface produces stronger evidence An interface the team defines is narrow — usually a handful of methods stated in the domain's own words — and **you define its contract**, so a stand-in can honour that contract completely. There is no gap between what the interface promises and what the double does, because you wrote both. More importantly, this seam concentrates every uncertain assumption about the vendor into **one adapter**. That adapter is now the only code in the system whose correctness depends on the vendor's real behaviour, and it is small enough that you can afford to test it against a real or sandbox instance of the dependency. So the suite splits cleanly: a large body of fast tests that use the owned seam and prove your logic, plus a small body of slow tests that prove the one place where your beliefs about the vendor are encoded. The evidence adds up; with the vendor seam it does not, because no test ever meets the vendor at all. ### The worked case, and the defect the seam decided In the **tax-filing wizard**, the rules-snapshot dependency comes from a vendor library with a paged document query and — as it turned out — a client-side cache with its own eviction policy. The team defined `RulesSnapshotSource.forTaxYear(year) -> RuleSet`: one method, domain vocabulary, no vendor types in the signature. Unit tests substitute at that method. One adapter calls the vendor, and six adapter tests run against a real sandbox instance in roughly 28 seconds per commit. Those six tests are where a **stale-cache read** surfaced: the vendor client returned a snapshot from an earlier tax year after the rules were republished. No stand-in for the vendor type would have caught it, because nobody modelling that client had any reason to model its cache. That is the general shape — the defects that survive a doubled suite are exactly the ones about semantics you did not know to imitate. ### When the vendor seam is defensible The heuristic often quoted as "don't mock what you don't own" is a default, not a law, and a strong candidate names the exceptions: - The vendor **ships and maintains its own test double or fake**. Then the model of the vendor is the vendor's, kept in step with each release, and the objection largely disappears. - The type is a **pure data holder** with no behaviour worth modelling. - **Legacy code with no seam**, where introducing one is the larger project. Substituting at the vendor type is then a stepping stone you record as debt, not a destination. ### The trap to name An owned interface that mirrors the vendor's shape method-for-method buys nothing: the stand-in must model the same semantics, so you have the vendor seam plus an extra file. The test is whether the interface would survive replacing the vendor entirely. If its method names, parameters and return types are stated in your domain's terms and would not change, the seam is real. If they are the vendor's names with a different package, it is not.