For four modules we have lived with an npm test that fails on purpose. That ends today. We install Mocha and Chai, configure the runner, fix the test script in package.json and write the unit suite for the Escena Viva domain: Session, Event, SalesManager and — the promise outstanding since Module 8 — the entire matrix in src/authorization/policy.js, walked cell by cell.

1. Installing the stack and fixing the test script
2. Anatomy of a test file
3. The hooks and their exact execution order
4. Focusing and skipping tests
5. Chai: styles and assertion catalog
6. Assertions about errors
7. Asynchronous tests and timeouts
8. The Escena Viva unit suite
9. Test data factories

The version matters: Chai 5 ships ESM only and cannot be loaded with require(). Since Escena Viva is CommonJS, we pin version 4; if you see "chai": "^5..." you will get ERR_REQUIRE_ESM on the very first run.

The runner options live in .mocharc.json at the project root, so that they are visible to the team and to the continuous integration server:

That last one deserves a comment. If Mocha finishes but the process does not die, it is because something is still alive: a Mongo connection, a setInterval, a server listening. "exit": true hides the problem; false forces you to close resources properly. In 09-06 we will see how to diagnose what was left open.

And now, at last, the script that has been failing since Module 5. Next to the ones that already existed (start, dev, seed, lint, format, audit), we add:

There is no need to pass paths any more: Mocha reads .mocharc.json. test:watch re-runs on save, which is how you work while developing. npm test now answers 0 passing with exit code 0: the project's first green.

Mocha exposes globals (describe, it, before...) without importing them; Chai does have to be imported.

describe groups and nests freely: by convention the outer one names the unit and the inner ones the method or the scenario. it is one test: it passes if the function finishes without throwing, and fails if it throws (and a failed Chai assertion throws). Style rule: do not use arrow functions if you need Mocha's this (for example this.timeout(10000)), because arrows have no this of their own.

With an outer describe that has all four hooks plus test A, and an inner describe with its own four hooks plus tests B and C, the actual trace is exactly this:

The three rules that follow: beforeEach hooks run from the outside in and afterEach hooks from the inside out, like a stack; the outer beforeEach also runs for the tests in inner blocks (the usual source of "why is my object being reset?"); and the inner before does not run until the first test in that block.

What to put in each one: in before, only what is expensive and immutable, never state the tests are going to mutate. In beforeEach, the arrangement, because if two tests share a mutable object they will sooner or later step on each other. In afterEach, the mandatory cleanup (sinon.restore(), dropping collections, restoring clocks): Mocha runs it even if the test fails, and that is why it is the right place. In after, close whatever before opened, or the process will never end.

The classic mistake with .only is forgetting it, pushing it, and having CI go green while running a single test. That is why we set forbidOnly: true: a forgotten .only breaks CI loudly instead of lying quietly (locally you disable it with mocha --forbid-only=false).

Pending tests are an honest way to write down the behavior that is still missing: they show up in the report, so they do not get forgotten the way a TODO does. There is also the conditional skip, before(function () { if (!process.env.MONGODB_URI_TEST) this.skip(); }), useful when a test requires a service that may not be there.

Chai offers three styles for saying the same thing: assert.equal(a, b), expect(a).to.equal(b) and a.should.equal(b). We will use expect because it reads almost like a sentence, it does not modify Object.prototype (unlike should, which blows up with null and undefined), and its failure messages include both the expected and the actual value.

A mnemonic: equal for primitives, deep.equal for anything written with braces or brackets. When you see expected { id: 'evt-001' } to equal { id: 'evt-001' } with two apparently identical objects, you are missing the deep.

With the hierarchy from Module 6, checking only that "something threw" is not enough: if sell(0) threw an internal TypeError instead of the expected ValidationError, a sloppy test would pass all the same. The scale goes from a bare to.throw() (sloppy), to to.throw(ValidationError) (better), to to.throw(ValidationError, /integer/) (type and message).

But what really travels to the client is the appCode, on which the HTTP status depends through STATUS_BY_CODE. The capture pattern lets you assert on it:

The expect.fail(...) is essential: without it, if sell(5) did not throw, the catch would never run, caught would still be null and the assertions would fail with a confusing message. When a single property is enough there is a compact version: expect(() => session.sell(5)).to.throw(StateConflict).with.property('appCode', 'INSUFFICIENT_CAPACITY').

Mocha offers three mechanisms: async/await in the it (the right way), returning the promise (equivalent) and the done callback, a legacy of the pre-promise era that is still the best option for events emitted in the future.

You will see done in action a few pages further down, with SalesManager. Its traps: if you never call it the test dies by timeout with a generic message; if an assertion fails inside the callback it may not be attributed to the right test; and never mix it with async (Mocha throws Resolution method is overspecified).

Mocha marks the it as good immediately and the assertion is evaluated into the void: if it fails, it will show up as an unhandledRejection with no apparent relation to the test, or it will not show up at all. Rule: if async or .then appears in the body of an it, the it must be async and must await.

To test that a promise rejects, the same try/catch with expect.fail works, as does the chai-as-promised plugin (npm i -D chai-as-promised@7 and chai.use(chaiAsPromised)), which adds await expect(promise).to.be.rejectedWith(ResourceNotFound). Watch the await in front of expect: without it you are back to an unawaited promise and the test always passes. It is the same trap in disguise.

The message Error: Timeout of 2000ms exceeded means one of three things, in order of frequency: you forgot done() or returned a promise that never settles; the operation is genuinely slow (database, bcrypt at cost 12); or there is a deadlock waiting for an event nobody emits. You adjust it per block (describe('...', function () { this.timeout(10000); })), per test, or you disable it with this.timeout(0) while debugging. Do not raise the global timeout to paper over a slow test: you would turn a two-second deadlock into a thirty-second wait.

Still missing are the derived properties (occupancy with be.closeTo, priceEuros, soldOut being false), which follow the same mold. The boundary case — selling exactly the last three — is the <= versus < that someone writes wrong one day and turns into an oversale of one ticket.

Event is an aggregate, so its tests are about the sums and about reconstruction: totalCapacity is 800 and ticketsSold is 350 with two sessions of 400 capacity and 100/250 sold; soldOut is false if a single session still has room; and Event.fromJSON({ id, title, venueId, sessions }) returns an instanceOf(Event) whose sessions are Session instances with their available already computed, and also throws if the JSON carries no identifier. It is the same pattern as in Session: a minimal scenario, one operation, an assertion on the observable value.

The test promised back in Module 8. Since hasPermission, canManageEvent and canViewOrder are pure functions, we walk the entire matrix with case tables and loops:

Seventeen cells walked with two three-line loops, edge cases included. Mocha's output reads like a security specification, and if someone inverts an if in canManageEvent, several tests turn red naming exactly the problem.

SalesManager is an EventEmitter, so we test that it emits what it should:

With a beforeEach(() => { manager = new SalesManager(); }) in front and a third, analogous test for session-sold-out. Two techniques live side by side: done for the asynchronous event and collecting into a variable for the synchronous ones, which lets you count how many times it was emitted. The second is the kind of rule nobody remembers when refactoring six months later.

Repeating the full constructor in every test is noise: it hides which piece of data matters in each case. The solution is factories with default values and partial overrides:

Three properties make a factory good: it always returns a fresh object (no shared constants), its defaults are valid (createSession() with no arguments produces a usable session) and the overrides make the relevant part visible (createSession({ sold: 398 }) says without noise that this test is about a nearly full house).

Run npm test now: 38 passing (52 ms). That is the speed of unit tests over a pure domain, and the reason the base of the pyramid is so wide.

• ERR_REQUIRE_ESM when importing Chai. You are on Chai 5 with CommonJS. Install chai@4.
• Using equal with objects. The failure shows two identical objects and drives you mad: you need deep.equal.
• Resolution method is overspecified. You put both done and async on the same it. Pick one.
• A forgotten .only. CI goes green after running one test. Turn on forbidOnly.
• this.timeout() inside an arrow function. It does not work: use function ().
• Arranging in before instead of beforeEach. The first test mutates the object and the following ones receive it dirty. When in doubt, beforeEach.
• Assertions that never run. Every test with try/catch needs its expect.fail on the happy path.
• Tip: verify each new test by breaking the code on purpose (change >= to > in sell and check that it turns red), and run a single file with npx mocha test/unit/session.test.js instead of reaching for .only.

Write test/unit/order.test.js with four tests for Order: that the total adds up the lines in cents, that a newly created order is in pending status, that it accepts no more than 6 tickets per session, and that an order with no lines throws. Use a local factory.

The CASES table is missing PERMISSIONS.CANCEL_ORDER. Add it for the three roles with this rule: the attendee can cancel their own orders, the organizer cannot, the administrator can. Then write the canChangeRole test that verifies that only the administrator can change roles and that nobody can change their own role.

Explain why this test always passes, even if findById returns null, and rewrite it:

Exercise 1. With a local createOrder() factory that by default carries one line of 2 tickets at 2500 cents:

The other three are straightforward: createOrder().status must be 'pending' with paidAt null; a line with quantity: 7 must throw ValidationError with a message that includes the 6; and createOrder({ lines: [] }) must throw as well.

Exercise 2. Three new rows in CASES (['attendee', PERMISSIONS.CANCEL_ORDER, true], ['organizer', ..., false], ['administrator', ..., true]) and four canChangeRole tests with admin, marta (organizer) and lucia (attendee):

The last one is the important one: it stops the last administrator from demoting themselves by mistake and leaving the platform with nobody able to manage users.

Exercise 3. The it is not async and does not return the promise from .then, so Mocha considers the test finished before the .then runs; if the assertion fails afterwards, the failure arrives orphaned. The correct version is async, with await and a preceding expect(event).to.not.be.null that gives a far clearer failure message than a Cannot read properties of null.

npm test is green. We have Mocha configured through .mocharc.json, Chai in the expect style, the hooks with their order genuinely understood, the assertion catalog you use every day, the technique for checking that an error is the right error with its code, the ways to test asynchronous code along with the unawaited-promise trap, and a real suite covering the domain and the complete permission matrix.

But notice what all these tests have in common: none of their units depends on anything external. Session makes no network calls, policy.js queries no database, SalesManager never looks at the clock. That is why they run in milliseconds and deterministically.

The moment we step out of that bubble, the terrain changes. currency-exchange.js calls an API through fetch, generateTicketCode uses the current year, access tokens expire after 15 minutes and the repositories open connections to Mongo. None of those units can be tested deterministically as they stand.

In the next lesson, Test Doubles with Sinon, we will replace the clock, the network and the database with controlled versions: spies, stubs, mocks and fake clocks. And we will also see where the limit is, because faking too much produces tests that only check your own assumptions.