testdouble.js

Welcome! Are you writing JavaScript tests and in the market for a mocking library to fake out real things for you? testdouble.js is an opinionated, carefully-designed test double library maintained by, oddly enough, a software agency that's also named Test Double.

If you practice test-driven development, testdouble.js was designed to promote terse, clear, and easy-to-understand tests. There's an awful lot to cover, so please take some time and enjoy our documentation, which itself is designed to show you how to make the most out of test doubles in your tests.

The pitch

Interested in learning what testdouble.js is, why it exists, and what the API offers? The quickest path is this fast-paced 20-minute talk:

Coming from Sinon.js?

Right now, Sinon.js is the test double incumbent in JavaScript, with over 1.7 million downloads in the last month. If you've got experience with Sinon, check out our side-by-side comparison to see why we wrote testdouble.js and how some of the API translates.

The Very Basics

Before diving into our in-depth docs, here is a quick intro of the basic uses:

Stubbing return values for functions

var td = require('testdouble');

var fetch = td.function();
td.when(fetch(42)).thenReturn('Jane User');

fetch(42); // -> 'Jane User'

Verifying a function was invoked

var td = require('testdouble');

var save = td.function('.save');
save(41, 'Jane');

td.verify(save(41, 'Jill'));
//
// Error: Unsatisfied verification on test double `.save`.
//
//   Wanted:
//     - called with `(41, "Jill")`.
//
//   But was actually called:
//     - called with `(41, "Jane")`.

Docs

All of our docs are in the docs/ directory inside this repository and numbered for easy reading in the priority-order we anticipate people needing them. Here's a rough outline:

1. Installation
   1. for Node.js
   2. for browsers
   3. initial configuration
2. Purpose of testdouble.js
   1. in unit tests
   2. in integration tests
3. Getting started tutorial
4. Creating test doubles
   1. test double functions with td.function()
   2. test double objects with td.object()
   3. test double constructors with td.constructor()
5. Stubbing responses
   1. td.when() API
   2. equality argument matching
   3. one-liner stubbings
   4. stubbing sequential return values
   5. argument matchers
      1. td.matchers.anything()
      2. td.matchers.isA()
      3. td.matchers.contains()
         1. matching strings
         2. matching arrays
         3. matching objects
      4. td.matchers.argThat()
      5. td.matchers.not()
   6. Stubbing callback APIs
   7. Stub exceptions with thenThrow
   8. Stub promises with thenResolve and thenReject
   9. Stub side effects with thenDo
   10. Configuring stubbings
   11. ignoreExtraArgs
   12. times
   13. defer
   14. delay
6. Verifying invocations
   1. td.verify() API
   2. equality argument matching
   3. argument matchers
      1. td.matchers.anything()
      2. td.matchers.isA()
      3. td.matchers.contains()
         1. matching strings
         2. matching arrays
         3. matching objects
      4. td.matchers.argThat()
   4. Argument captors
   5. Configuring verifications
      1. ignoreExtraArgs
      2. times
7. Replacing dependencies with test doubles
   1. for Node.js
   2. for Browser JS
   3. td.replace() API
8. Writing custom argument matchers
9. Debugging with testdouble.js
   1. td.explain() API
10. Plugins
    1. testdouble-chai
    2. testdouble-jasmine
11. Frequently Asked Questions
    1. Why shouldn't I call both td.when and td.verify for a single interaction with a test double?
12. Configuration
    1. td.config