Mocking Layers: Module vs Network

## Two different things called "mocking the API" Both phrases mean "the server is not real", but they cut the application at completely different places. **Module seam.** You replace one of your own modules — the api client, a data-fetching hook's dependency, a repository object — with a fake object that returns canned values. The substitution happens inside the JavaScript module graph, before any network work exists. **Network seam.** You leave every module in place and intercept the outgoing HTTP request, answering it with a response you control. The substitution happens at the boundary the browser would actually cross. Everything else — fidelity, coupling, refactor cost — follows from where that line is drawn. ## Why the module seam produces false greens A fake does not add behaviour; it removes it. With the client module faked, the following never executes: the path and query string the app would build, the headers it would attach, the body it would serialize, the status codes it would branch on, the payload it would parse, and the field mapping it would apply. What the test asserts is that the UI works *given a value you wrote by hand*. That makes the test a statement about your beliefs, not about the system. Two very common production bugs slip straight through: - The app requests the wrong thing — a mistyped query parameter, a missing path segment, a lost auth header — and the fake answers correctly regardless, because it ignores or barely inspects its arguments. - The server's payload changes — a renamed field, a new nullable, a list that became paginated — and the fixture, frozen at the shape you once believed in, keeps every test green. The suite passes; the feature is broken; nobody learns anything until a user reports it. ## What the network seam restores Intercept at the network boundary and the same test suddenly exercises the real client: - the URL, method, headers and query string are genuinely built and can be asserted on, because the interceptor sees the actual request; - the request body is genuinely serialized; - the response is genuinely parsed and mapped by your code, so a fixture that does not match the app's expectations *fails the test* instead of bypassing the mismatch; - status handling and error mapping run, so "404 means empty state" is proved rather than assumed; - any interceptor, caching or retry layer in the client runs too. The imaginary part shrinks to exactly one thing: the server. That is the smallest honest fake for a frontend feature test, and it is why network-level interception has become the default recommendation for component and integration tests. ## The second benefit: coupling A module fake is written against the *shape of your implementation* — a module path and an exported function signature. Change the shape and the tests break even though nothing a user can see has changed: renaming the module, splitting one client into two, replacing one HTTP library with another, or moving from hand-written calls to a generated client. Hundreds of red tests for a pure refactor is a coupling signal, not a safety signal. A network-level fake is written against the *URL and payload*, which is a contract with a party outside your codebase and therefore far more stable. It keeps working across data-layer refactors, and it stops working precisely when the thing it describes — the API — actually changes. That is the behaviour you want from a test. ## What the network seam costs It is not free, and pretending otherwise is its own red flag: - **Setup.** Something must install the interception and tear it down between tests; leaked handlers across tests are a real flakiness source. - **Speed.** Slightly slower than returning a value from a fake function, and you now execute serialization and parsing on every test. - **Debuggability.** A failure can now come from the handler, the client, or the component, so the failure message is less pinpointing than a module fake's. - **Fidelity is still not truth.** You wrote the responses. The seam removes a class of bugs about *your* code; it does not tell you whether the server still returns what you claim. ## When a module seam is still the right choice Say this part out loud; an interviewer is listening for dogma. - The collaborator is **not HTTP**: a clock, a random source, a browser API, an analytics facade, a WebSocket wrapper, a payment SDK that opens its own iframe. - The dependency is a **third-party SDK whose transport you do not control or want to model** — faking its documented method is more honest than reverse-engineering the requests it makes. - The test is a **deliberately narrow unit test** of logic above the client, where you want the failure to be unambiguous and you accept the narrower claim. - You need to **force a state that is awkward to express as a response** — though most of those, including failures and delays, are expressible at the network seam and belong there. ## The answer an interviewer wants Name the seam, say what each one deletes, and connect it to the two failure modes: fidelity (false greens) and coupling (refactor breakage). Then place them: network seam by default for anything that goes over HTTP, module seam for non-HTTP collaborators and narrow unit tests, and a small number of tests against a real server to keep the fixtures honest.