Skip to content
Tutorials Center
My learning

Topics

Lesson 104 of 133 ยท Testing

Test-Driven Development Workshop

Practice test-driven development in Node.js. Build a rate limiter with red-green-refactor cycles, injected clocks, edge cases and seeded property-style tests.

Most people write code first and tests afterwards, if at all. Test-driven development (TDD) flips the order: you write a small failing test, then just enough code to make it pass, then clean up. It sounds like extra work. In practice it does three things well: it forces you to decide how the code will be used before you write it, it gives you a safety net for refactoring, and it keeps you from writing code that nothing needs.

This lesson is a workshop. We will build a real module from nothing, a rate limiter that decides whether a client may make another request, one tiny step at a time, with the built-in test runner from The Built-in Test Runner. You should already know assertions and injecting a fake clock. Every step is runnable, so you can follow along and change things.

The test runner prints a duration after every test, for example (1.2ms). These numbers change on every run, so this lesson never quotes them. Read the check marks and crosses.

The red-green-refactor loop

TDD is one loop, repeated hundreds of times:

  1. Red. Write one test for behavior that does not exist yet. Run it and watch it fail, and make sure it fails for the right reason. A test you have never seen fail might not be testing anything.
  2. Green. Write the simplest code that makes the test pass, even if it feels silly. Hard-coding the answer is allowed at first.
  3. Refactor. With all tests green, improve names and structure. The tests tell you immediately if you broke something. Do not add behavior during this step.

Each lap should take a few minutes. If a step feels big, the step is too big: write a smaller test.

The problem

An API must protect itself from a client that sends too many requests. We want a limiter that allows at most limit requests per windowMs milliseconds for each client key (an IP address or user id). A call such as limiter.check('203.0.113.7') answers with an object: whether the request is allowed, how many requests remain, and when to retry if it is blocked.

Before writing code, write down the API you would like to use. That is the first design decision TDD makes you take:

NODE
const limiter = createRateLimiter({ limit: 3, windowMs: 1000 });
limiter.check('ada');   // { allowed: true, remaining: 2 }

The limiter will not call Date.now() itself. It receives a now function as an option, so tests can control time exactly. This is the dependency injection pattern from the mocking lesson, and it is what makes time-based code testable without waiting.

Cycle 1: red

We start with the smallest behavior: the first request is allowed. In a fresh file nothing exists yet, so the "implementation" is a stub that does nothing. Run it and see the test fail.

Node.js Red: the first test fails (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The test fails with TypeError: Cannot read properties of undefined (reading 'allowed'). That is the correct kind of red: the test reached the behavior we want to build and found nothing there. If it had failed with a syntax error in the test file, we would fix the test first.

Cycle 1: green

Now the simplest thing that works. We do not know about limits or windows yet, so we return a constant. This feels like cheating, and that is the point: the next test will force us to do better.

Node.js Green: the simplest code that passes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Cycle 2: blocking over the limit

Next behavior: after limit requests, the next one is blocked. Add the test, watch it fail, then add the counter. Each new test makes the hard-coded version less acceptable. Here are both steps in one runnable file: the test list is the specification, and the implementation is the smallest code that satisfies all tests so far.

Node.js Cycle 2: counting requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

All green. The implementation is still naive: one global counter, and time never passes. That is fine. We only write code that a failing test demands.

Cycle 3: time passes, with an injected clock

The window must expire. A blocked client should be allowed again after windowMs has gone by. Because the limiter takes now as an option, the test controls time with a variable, with no sleeping and no flakiness.

The design that passes this test is a sliding window log: remember the timestamp of each recent request and forget those older than the window. We also fix the earlier shortcut by keeping one log per key.

Notice the order of work. The test was written first and expressed this API; only then did the implementation grow into this shape.

Node.js Cycle 3: a sliding window and an injected clock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first test would have taken a full second with real timers, and the third would be almost impossible to write reliably that way. With an injected clock, they take microseconds and never flake.

Cycle 4: tell the caller when to retry

A good API client should know how long to wait. The HTTP Retry-After header exists for exactly this. We write the test first: a blocked result must include retryAfterMs, the time until the oldest request in the window leaves it.

Work out the expected number by hand in the test, not by copying the implementation's formula. If the limit is 2, requests happened at t = 0 and t = 300, and it is now t = 400 with a 1000 ms window, then the oldest request leaves the window at t = 1000, so the client must wait 600 ms.

Node.js Cycle 4: retryAfterMs, and then a refactor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last test is worth studying: it does not check a specific number, it checks a promise the API makes ("wait this long and you will get through"). Tests of promises survive refactors better than tests of formulas. The recentRequests helper appeared in the refactor step: all earlier tests were still green, so we knew the cleanup was safe.

Cycle 5: edge cases and bad input

Once the main path works, hunt for edges. Ask: what is the smallest input, the largest, the weird one, the invalid one? Typical edge cases for this module are limit of 0 (block everything), a request exactly on the window boundary, and invalid options such as a negative window.

Decide each answer deliberately and write it down as a test. Here we choose that a request made exactly windowMs after an earlier one counts as outside the window (the filter uses >), and that invalid options throw a RangeError with a clear message when the limiter is created, not later at the first request. Failing early is kinder to the person debugging.

Node.js Cycle 5: edge cases (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Three of the four tests pass and one fails on purpose, and its message is the real lesson. The last test expects the wording windowMs must be positive, but the guard says windowMs must be a positive number. The runner reports The input did not match the regular expression /windowMs must be positive/ and shows the real input, RangeError: windowMs must be a positive number. Because the test was written before the message, it caught a mismatch between what we intended and what we typed. In a real session you would now decide which one is better and fix either side; change the test's pattern to /positive number/ and the run turns green.

Property-style tests with a seeded generator

Example-based tests check the cases you thought of. Property-based tests check a rule against hundreds of generated inputs, which finds the cases you did not think of. The idea is to state an invariant that must hold no matter what the input is, then hammer the code with random input.

For our limiter, a strong invariant is: in any window of windowMs, the number of allowed requests per key never exceeds limit. Another is that the optimized limiter must agree with a slow, obviously correct reference model.

Randomness must be reproducible, otherwise a failure cannot be investigated. Use a small seeded generator: the same seed always produces the same sequence. When a property fails, print the seed so you can rerun that exact scenario.

Node.js A property test with a seeded random generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

If a bug existed, for example >= instead of > in the window filter, some seed would eventually break the invariant and the failure message would name it. You would then run only that seed under a debugger. Property tests are not a replacement for example tests; they are a net underneath them. Keep the number of iterations small enough that the test still finishes in well under a second.

When a bug is reported in production, first write a test that reproduces it (red), then fix it (green). The test stays forever as a regression guard, and you have proof that the bug was real and is now gone.

Keeping tests fast and trustworthy

A test suite that takes ten minutes stops being run. A few rules keep TDD pleasant:

  • No real time, no real network, no real randomness in unit tests. Inject clocks, fakes and seeds, as we did here.
  • One reason to fail. A test named works that checks twelve things hides which one broke. Name tests after behavior: blocks the request after the limit is reached.
  • Arrange, act, assert. Set up the state, perform one action, check the result. Blank lines between the three parts make tests easy to scan.
  • Test behavior, not structure. The tests above call check() and read results. They know nothing about the logs map, so the map could become a ring buffer tomorrow without touching a test.
  • Independent tests. Each it builds its own limiter. Shared mutable state between tests causes order-dependent failures.
  • Run the tests constantly. With node --test --watch the runner re-runs files on every save, which makes the red-green loop nearly instant. See Running Node for the watch flag.

TDD is not a religion. For exploratory work (you do not yet know what you are building) it is fine to experiment first and add tests afterwards. For logic with clear rules, such as parsers, calculations, validators and state machines, the loop pays off quickly. The result of this workshop, a small and well-tested module, is exactly the kind of component that later goes behind HTTP middleware (see Middleware) or into the production hardening covered in Error Handling in Production.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In red-green-refactor, what is the purpose of the red step?

    A test you have never seen fail may not be testing anything. Seeing the expected failure proves the test can detect the missing behavior.
  2. 2. Why does the rate limiter take a now function as an option instead of calling Date.now() directly?

    Injecting the clock is dependency injection. The test passes a function it controls, so a one second window can be tested in microseconds.
  3. 3. During the green step, which code is correct to write?

    Green means the least code needed for the current failing test. Later tests force the code to become more general.
  4. 4. Why should a property-based test use a seeded random generator?

    With the same seed the sequence of inputs is identical, so a failing scenario can be rerun and debugged. Print the seed in the failure message.
  5. 5. Which test is better at surviving a refactor?

    Tests of observable behavior stay valid when the internals change. Tests that touch private structure break whenever the structure changes.

Summary

  • TDD is a loop: write a failing test (red), make it pass with the simplest code (green), clean up (refactor).
  • Design the API you want to call before writing the implementation; the tests are its first user.
  • Inject time (a now function) so time-based code is tested instantly and deterministically.
  • Work out expected values by hand in the test; assert on promises the API makes, such as "wait retryAfterMs and you get through".
  • Hunt for edge cases (zero, boundaries, invalid input) and decide each answer with a test.
  • Property-style tests check an invariant over many generated inputs; seed the generator and report the seed.
  • Keep tests fast, independent and focused on behavior. Reproduce every production bug with a test first.

Next: Error Handling in Production