It Passed in the Monorepo. It Broke After npm install.

An observability adapter — a small library that wraps your model client or database client and records what went through it — can pass every test its maintainer wrote and still record nothing when you install it. The imports resolve. The tool runs. No exception fires. Your trace dashboard is just empty.
That is not hypothetical. A public evaluation of an earlier release of AgentInspect, a tracing tool for MCP clients, hit exactly this class of problem: capture and runtime-identity issues that only appeared once the package was consumed from the registry instead of the source tree it was built in. The maintainer responded by rebuilding the test around that boundary — pinned versions, a real SDK client, both module systems, a container with the network switched off — and then writing down, in the same document, what the result does not prove.
Most teams skip that last part, and most teams skip the test. They test the workshop and ship the product.
Your repo and your users' node_modules are different programs
A monorepo is a workshop. It hoists dependencies, symlinks internal packages, and resolves your imports through a graph you control. An installed application is a different graph built by someone else's lockfile, and it fails in three specific ways your repo can't show you.
One module becomes two copies
Any library that keeps state needs to be a single instance at runtime — an async context store, a metrics registry, a connection pool, a feature-flag client. In your workspace, the package is usually one copy: everything points at the same symlinked folder, so your adapter and your app share the same live state.
After install, that is a coincidence, not a guarantee. Two packages can declare overlapping version ranges and still end up with separate copies of the shared module, depending on the tree your user's resolver builds. A bundler can prebundle a third. The result is quiet and awful: your app opens a trace context in copy A, your adapter reads copy B, sees no active run, and records nothing. No error, no warning, no log line. Just silence where data should be.
You test against versions your users never get
Your lockfile pins one exact version of a peer dependency. Your users install whatever their resolver picks inside the range you declared. You tested a point; you promised an interval.
Your own tests import the wrong door
Internal tests often import from a source path. Consumers import the entry point declared in your package manifest — which may map a different file per module system, per runtime, per browser condition. Those are not the same file, and increasingly they are not the same code.
Package topology changes runtime behavior. Listing installed versions tells you what is on disk; it does not tell you whether two imports share one live context.
Three boundaries, three tests
1. Resolution: which copy am I talking to?
In a fixture app that installs your published package, write a marker into the shared state and then assert your library can read it back. If the read comes back empty, you have two copies, and the fix is structural — a singleton registry accessed through a well-known key, or a narrower dependency range — not a code patch.
2. Surface: is it still the same object after wrapping?
Wrappers are where object behavior dies. Spreading an instance into a plain object ({...client}) drops prototype methods and getters. Calling a forwarded method with the wrong receiver breaks anything relying on this — including private fields, which throw rather than return garbage. So the fixture should assert the wrapped object is still an instance of the original class, and then actually call a few methods through the wrapper: a ping, a list, a real operation. Return values, not just absence of exceptions.
3. Environment: which module system, runtime, and network?
ESM import and CommonJS require are two separate consumers hitting two separate entry points. Node versions differ. So do operating systems, which matters the moment a native module or a path separator is involved. And the network is the environment nobody declares — which is exactly why you should take it away.
Assert against a counter you don't own
Here is the assertion pattern that catches the invisible failures. Build a fixture where a real client talks to a real server over an in-memory transport — no mocks, no network. Give the server one synthetic tool and a counter that increments every time that tool's handler runs. Then:
- Assert the wrapped client is still an instance of the real client class.
- Call a method through the wrapper and inside a traced run, list tools and call the tool.
- Assert the server's own counter equals one. This is ground truth from the other side of the boundary.
- Assert your library captured two steps, and that they are labelled list and call.
Two numbers from two independent sources. If you only check your captured spans, "one span recorded" passes happily while a second real call vanishes — the trace is incomplete and looks fine. If you only check the counter, you know the operation ran but not that your library described it correctly.
The rule generalizes to anything you wrap:
- Email wrapper: the fake SMTP server received one message and your audit table has one row.
- Cache wrapper: the backing store's get count went up and your hit/miss metric moved.
- Queue wrapper: the consumer's handler fired once and the span closed.
Your library cannot be the only witness to its own behavior. Somewhere in every boundary test there has to be a measurement taken from the far side.
Run both module systems, or you tested half your users
Two consumer files, one using import, one using require, both installing the same pinned version through a committed lockfile, both hitting public entry points. In the AgentInspect rebuild, both passed with the same shape: one actual tool execution on the server, two captured steps in the trace. That held on Linux with Node 24.22.1, and again on macOS arm64 with Node 22.22.3.
Two environments passing is a bounded claim. It is not universal compatibility, and the honest write-up says so. The temptation is to paint the whole platform column green off one smoke test; that is a marketing slide, not a test result.
Take the network away
The cleanest way to prove your fixture has no hidden dependencies is to run it where there is nothing to reach. A small container — Node base image, npm ci with install scripts disabled, run the tests — launched with Docker's --network none driver leaves only loopback. In-memory transport means no credentials are needed, so any accidental outbound request is a bug the run reports instead of a request somebody's endpoint quietly receives.
Two disciplines worth copying. First, the maintainer ran the Node tests but only reviewed the Docker commands, and said so in the article rather than implying a container result. That sentence — "reviewed but not executed" — is part of the finding, not a disclaimer to bury. Second, pin an immutable image digest for CI: a major version tag can move under you, and a test that silently changes its own environment is worse than no test.
Write the support matrix, including the empty cells
A release claim is a grid: module system, operating system, Node version, SDK version, transport. Fill in the cells you actually ran. Then leave the rest visibly untested instead of inferring them.
In the rebuilt fixture, several rows stayed honestly empty: native Windows, HTTP and stdio transports, OAuth flows, reconnect behavior, and the long tail of SDK methods. None of those are covered by a passing in-memory smoke test, and stating that is cheaper than discovering it in a bug report from a Windows user behind a proxy.
What this costs, and what it doesn't buy
Realistically an afternoon: one fixture app, one committed lockfile, roughly nine assertions, one Dockerfile. It earns its keep the first time it catches duplicated runtime state or a wrapper that dropped a prototype.
The trade-offs are real. It is another suite that can rot, and it is slower than your unit tests, so it belongs in the release path rather than the inner loop. Pin exact versions, update the fixture deliberately, and treat a failure as a release blocker — not a flake to retry. And it does not replace a native OS matrix, unit tests, or load testing. It covers a specific and under-served gap: the distance between the code you own and the artifact your users actually load.
The bug you ship is the one that only exists after install. Test where your users stand.
Key Takeaways
- Your workspace is not your product. Hoisting, symlinks, and dev-time resolution hide duplicated modules and wrong entry points that appear only after install.
- Test three boundaries: resolution (one copy or two), surface (prototypes, getters, receivers survive wrapping), and environment (module system, runtime, network).
- Every boundary test needs a measurement from the other side. Assert the server's own call counter alongside your captured spans, or an incomplete trace will look perfectly healthy.
- Run ESM and CommonJS consumers separately. They are different entry points; passing one proves nothing about the other.
- Remove the network to prove you don't need it. An in-memory transport plus a no-network container turns hidden dependencies into loud failures.
- Publish the empty cells. A support matrix with visible untested rows is a stronger claim than a green column built from one smoke test.