In the previous lesson we tested the pure Escena Viva domain in fifty-two milliseconds. It was easy because Session, Event and policy.js depend on nothing: you give them data, they give you results. The real application, on the other hand, is full of dependencies that destroy determinism.

• src/services/currency-exchange.js calls an external API with fetch: if the provider is down, the test fails without our code having any bug at all, and if it works it takes 400 ms and burns quota.
• generateTicketCode builds codes of the form EV-<year>-<6 digits> using the current year: that test will pass until December 31 and fail on January 1.
• Access tokens expire after 15 minutes. Testing expiry as is would require a fifteen-minute test.
• The repositories open connections to Mongo. A unit test of a controller should not need a database.

The solution is test doubles: objects that stand in for the real dependencies during the test, just as a stunt double stands in for the actor in the dangerous scene. In Node the standard tool is Sinon.

1. A taxonomy of test doubles
2. sinon.spy: observing without changing
3. sinon.stub: replacing the behavior
4. Always restore: sandboxes and contamination
5. Fake clocks
6. Faking fetch to test currency-exchange.js
7. Faking the repository to test a controller
8. Dependency injection versus module patching
9. When NOT to use doubles

The terminology comes from Gerard Meszaros and shows up throughout the literature and in the API names themselves.

The practical distinction you will use most is stub versus spy: a spy lets you ask was this called, with which arguments and how many times? without altering anything; a stub also decides what it returns, and therefore controls the flow of the unit under test. The golden rule: stubs for the inputs (what the unit receives from the world) and spies for the outputs (what the unit does to the world).

Avoid Sinon's classic mock: its up-front expectations produce brittle tests that are hard to read. In practice, stub plus assertions at the end covers everything you need.

A spy wraps a function and lets it do its job, recording every call.

A word about failure messages: expect(spy.calledWith('purchase')).to.be.true fails with expected false to be true, which tells you nothing. Prefer comparing the arguments (expect(spy.firstCall.args[0]).to.equal('purchase'), which fails with expected 'refresh' to equal 'purchase') or use Sinon's own assertions, which print the recorded calls:

sinon.match allows partial assertions that are very useful when the argument has volatile fields: sinon.match.string, sinon.match.number, sinon.match.instanceOf(Event), sinon.match.has('appCode', 'INSUFFICIENT_CAPACITY').

A stub replaces the implementation completely. Its repertoire:

A stub is also a spy: it keeps calledOnce, firstCall.args and the whole repertoire above. That is why in practice you will almost always reach for stub.

sinon.fake is a more modern, minimalist API with the same idea (sinon.fake.returns(...), sinon.fake.resolves(...), sinon.fake.throws(...)). It is immutable — you cannot reprogram it after creating it — and that makes it more predictable; it works very well as an anonymous callback, while for replacing methods on existing objects stub is still the most convenient.

Here is the hardest bug to diagnose in the whole module. sinon.stub(object, 'method') modifies the real object in memory, and in Node require caches modules: the audit.js your test sees is exactly the same object every other test in the process sees. If you do not restore it, the stub is still there in the next file.

The symptoms are unmistakable and maddening: the test passes on its own but fails in the full suite, it fails only when it runs after one particular test, or you get TypeError: Attempted to wrap recordAction which is already wrapped.

The defense is sinon.restore() in afterEach, which undoes everything created with the default sandbox (sinon.stub, sinon.spy, sinon.useFakeTimers). When you want your own scope, sinon.createSandbox() gives you a box with its own sandbox.restore(). And so that nobody can forget it, we put it in a root hook loaded from .mocharc.json:

sinon.useFakeTimers() replaces Date, setTimeout, setInterval, setImmediate and process.hrtime with controlled versions. Time stops running on its own: it advances when you tell it to with clock.tick().

Two tests covering both sides of the expiry, running in under a millisecond. Without the fake clock, the second one would be literally impossible to write. It works because jsonwebtoken uses Date.now() internally and the fake clock affects the signing too; if a library used a time source Sinon does not intercept, you would have to inject the clock into it.

Really testing retry(operation, { attempts: 3, waitMs: 1000 }) would cost two seconds per test. With the fake clock, zero:

The key is tickAsync rather than tick: tick advances the timers synchronously, but between two retries there are pending promises that need the event loop to yield, and tickAsync allows that. A warning repeated on purpose: if you do not restore the clock, every later test in the process lives in frozen time, Mocha's timeouts behave in the strangest ways, and you will spend a whole afternoon understanding nothing. The root hook with sinon.restore() covers you here too.

This service is the perfect example of an external dependency: it calls a rate provider over HTTP, with AbortSignal.timeout, retries and an in-memory cache. We want to test its behaviors without touching the network.

To these we add the cache one (two consecutive lookups and expect(request.calledOnce).to.be.true). Four scenarios — two of them, the 500 and the timeout, impossible to reproduce on demand against the real provider — tested in milliseconds, with no network, no quota and no flakiness.

One hygiene detail that is easy to overlook: the clearCache() in the beforeEach. The service's cache is shared state inside the same process; without clearing it, the second test would be answered from the first test's cache, fetch would never be called and the failure would be baffling. Every module with in-memory state needs a reset function designed for testing, because Sinon cannot know about it.

An Express controller is a function with three arguments: we can test it without a database and without HTTP by handing it doubles.

The second test checks that the controller hands the error to next instead of answering itself. That is the contract that makes Module 6's errorHandler work, and it is exactly the kind of detail that breaks when somebody "simplifies" the controller.

You will have noticed the signature getEvent({ eventRepository })(req, res, next). It is no accident: it is a controller factory that receives its dependencies. Compare the two ways of writing the same thing.

In the router only one line changes: router.get('/:id', getEvent({ eventRepository })). This is a small, honest refactor: the production code behaves the same, the application still wires the real repository exactly once, and in exchange the controller becomes trivially testable. That is what "tests exert design pressure" means: code that is hard to test is usually too tightly coupled, and fixing it improves the code, not just the test.

With the rigid version there is another problem: sinon.stub on the exported object may have no effect at all, because the destructuring in the require already captured the reference. When you cannot refactor — third-party code, a legacy module — there is a last resort, proxyquire, which intercepts a module's require calls:

Its drawbacks justify keeping it as a last resort: it couples the test to require paths (move a file and it breaks even though the behavior did not change), it bypasses the module cache with odd effects if there is state, it hides the design problem instead of solving it, and it does not work with ESM, so it is a dead end if you ever migrate.

Doubles are so convenient that it is easy to overdo it, and a test with too many of them only checks your own assumptions. Look at this gem:

What does this test? That a stub returning 5000 returns 5000. If buyTickets computed the total wrong, it would pass. If it never checked capacity, it would pass. If it sold negative tickets, it would pass. It costs something to maintain and it can never turn red for a real bug.

And there is a worse problem: the double can lie about the real dependency. If your repository stub returns null when it does not find the event but the real repository throws CastError on a malformed id, your unit tests will all be green while the API returns 500 in production. The double encodes what you believe the dependency does.

The rule that sums it up: double the edge of the system, not its interior. And accept that unit tests with doubles, however many of them there are, do not prove the pieces fit together. The integration tests in the next lesson are the necessary counterweight; without them, doubles become a mirror in which your code admires itself.

• Forgetting sinon.restore(). Contamination across files, already wrapped, tests that fail only in the full suite. Put the root hook in test/helpers/setup.js and forget about it.
• Not restoring the fake clock. The whole process stays frozen in time: the most baffling failure there is.
• Using tick where tickAsync is needed. Retries with promises never advance and the test dies by timeout.
• Stubbing a destructured reference. const { recordAction } = require('./audit.js') captures the function; sinon.stub(audit, 'recordAction') changes the object's property, not your copy. Always call through the object.
• expect(spy.calledWith(x)).to.be.true. A useless failure message: use sinon.assert.calledWith or compare firstCall.args.
• Forgetting to clear in-memory state (the currency-exchange.js cache). Sinon knows nothing about it; you have to do it by hand.
• Faking your own domain. If you are doubling Session, stop: it is cheap, deterministic and real.
• Tip: when a stub needs more than three withArgs, consider a real fake; a small class with a Map inside is usually more readable.
• Tip: every time you write a stub, ask yourself "which real bug would this test catch?". If you cannot answer, it is not worth having.

generateTicketCode() produces codes of the form EV-<year>-<6 digits> with the current year and six random digits. Write deterministic tests that check: that the year in the code is the current year, freezing the clock at 2026-11-05; that the format matches the pattern exactly; and that two codes generated back to back are different.

The events controller also shows the price in pounds when the user asks for ?currency=GBP. Write two unit tests with doubles: one in which getExchangeRate resolves 0.86 and the response includes priceGbp, and another in which it resolves null and the response does not include priceGbp but is still a correct 200.

Explain why this test contributes nothing and rewrite it so that it detects a real bug:

Exercise 1

The third one is interesting: we do not freeze randomness, because what we want to check is precisely that there is variety. If you needed an exact code, you would have to stub Math.random or, better, inject the generator.

Exercise 2

The second one is the valuable test: it guarantees that an outage at the external provider does not break the catalog. That kind of guarantee can only be obtained with doubles.

Exercise 3

The test creates a stub that returns 4500 and checks that it returns 4500: it does not run a single line of production code, so it would pass even if applyDiscount were empty. The right thing is to use the real function, which is pure and deterministic:

The third assertion is the one that really matters: rounding money is where the phantom cents that unbalance the books come from.

We now know how to isolate a unit from everything that makes it unpredictable. We know the taxonomy of doubles and when to use each one, we have spy and stub with their full repertoire, we understand why sinon.restore() in afterEach is not optional and how to enforce it with a root hook, we know how to freeze and advance time to test expiries and retries without waiting, we have faked fetch to cover the 500 and the timeout we could never trigger against the real provider, and we have seen that code which receives its dependencies is tested with half the effort of code that goes looking for them itself.

And we have seen the limit. Every double is an assumption about how the real piece behaves. Our tests are green, but none of them has yet checked that the routes are mounted in the right order, that errorHandler really turns a StateConflict into a 409, that Module 7's transaction prevents overselling with ten simultaneous purchases, or that authenticate actually rejects a request with no token.

In the next lesson, Integration Testing, we start the whole application with supertest and interrogate it over HTTP the way a real client would. That is where Module 6's design pays off — createApplication() returns the application without calling listen, precisely for this — and where we finally deliver on the Module 8 promise: how a test gets hold of a valid token without a single password written into the code.