# Debugging with testdouble.js

One weakness of many test double libraries is a lack of introspection capabilities.
Reading some bit of code you might find a test double and ask "what stubbings
have been set up on this double?" or "how many times has this been invoked?". Or,
perhaps the semantics of using `td.verify()` don't fit the flow of a complex test
assertion very well, and you'd rather dig into the history of calls made against
a test double and assert whether it was interated with manually.

Fortunately, testdouble.js was designed with this in mind. In addition to
encouraging every test double object & function to have a name (so you can figure
which one is causing you grief easily), the error messages the library produces
are on the verbose side. When those aren't enough, there is a method named
`explain()` which takes a test double function as an argument and will describe
the current configuration and state of the test double.

The examples in this document assume you've aliased `testdouble` to `td`.

## td.explain(someTestDouble)


``` javascript
var myTestDouble = td.function('.someFunction')

td.explain(myTestDouble) /*
  {
    name: '.someFunction',
    callCount: 0,
    calls: [],
    description: 'This test double has 0 stubbings and 0 invocations.'
  }
*/
```

If the test double does have stubbings or invocations, they'll be listed in the
description body as well. For instance, suppose you set up a stubbing on the
test double:

``` javascript
td.when(myTestDouble(5)).thenReturn(10)

td.explain(myTestDouble) /*
  {
    name: 'someFunction',
    callCount: 0,
    calls: [],
    description: 'This test double `.someFunction` has 1 stubbings and 0 invocations.

      Stubbings:
      - when called with `(5)`, then return `10`.'
  }
*/

```

Explain will also summarize any calls made to the test double. Let's say we
call the test double function but fail to satisfy the stubbing we just
configured:

``` javascript
myTestDouble(7) // undefined

td.explain(myTestDouble) /*
  {
    name: '.someFunction',
    callCount: 1,
    calls: [ { args: [7], context: window } ],
    description: 'This test double has 1 stubbings and 1 invocations.
      Stubbings:
      - when called with `(5)`, then return `10`.

      Invocations:
      - called with `(7)`.'
  }
*/
```

You can actually pass anything created by `td.func()`, `td.object()`,
`td.constructor()` and `td.imitate()` to `td.explain()` and it will be
recursively described, with all of the functions found explained in this format.

***
Previous: [Custom argument matchers](8-custom-matchers.md#custom-argument-matchers)
Next: [Plugins](A-plugins.md#plugins)