testdouble

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.

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
2. for Node.js
3. for browsers
4. initial configuration
5. Purpose of testdouble.js
6. in unit tests
7. in integration tests
8. Getting started tutorial
9. Creating test doubles
10. test double functions with td.function()
11. test double objects with td.object() 1. objects that mirror a constructor function 2. objects that mirror an object of functions 3. object of functions for an array of names 4. object of any functions using ES2015 Proxy
12. Stubbing responses
13. td.when() API
14. equality argument matching
15. one-liner stubbings
16. stubbing sequential return values
17. 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()
18. Stubbing callback APIs
19. Stub exceptions with thenThrow
20. Stub side effects with thenDo
21. Configuring stubbings 1. ignoreExtraArgs 2. times
22. Verifying invocations
23. td.verify() API
24. equality argument matching
25. 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()
26. Argument captors
27. Configuring verifications 1. ignoreExtraArgs 2. times
28. Replacing dependencies with test doubles
29. for Node.js
30. for Browser JS
31. td.replace() API
32. Writing custom argument matchers
33. Debugging with testdouble.js
34. td.explain() API
35. Plugins
36. testdouble-chai
37. testdouble-jasmine
38. Frequently Asked Questions
39. Why doesn't td.replace() work with external CommonJS modules?
40. Configuration
41. td.config

Changelog

v1.4.3 (2016-06-22)

Full Changelog

Closed issues:

• Build with Travis on Node 6.x #114
• Wrong test double name for proxies #112
• Improve error output message #111
• Flexible parameters #110
• How can I install and use this in an ember/ember-cli project? #105
• td.replace breaks subsequent require calls #103

Merged pull requests:

• Generate test double name for a Proxy test double #113 (mgryszko)