Merge pull request #84 from testdouble/better-tostring

Stringify objects better

Author: searls

docs/8-custom-matchers.md

@@ -7,9 +7,13 @@ it's easy to define custom argument matchers to meet your specific needs as well
 There's nothing magical about matchers. Any object passed into a `when()` or
 `verify()` invocation that has a `__matches` function on it and returns truthy
 when it matches and falsey when it doesn't is considered a matcher by
-testdouble.js. Anything without a `__matches` function will only match an
+testdouble.js. That said, we provide a `td.matchers.create()` helper for creating
+your own custom matchers in a way that'll help ensure your users will get better
+messages from `td.explain` calls and `td.verify` failures.
+
+(For the record, arguments without a `__matches` property will only match an
 actual invocation if it passes lodash's deep
-[_.isEqual](https://lodash.com/docs#isEqual) test.
+[_.isEqual](https://lodash.com/docs#isEqual) test.)
 
 The examples in this document assume you've aliased `testdouble` to `td`.
 
@@ -20,13 +24,13 @@ the expected type of an argument matches the type of the argument actually passe
 to the test double function from the subject under test.
 
 ``` javascript
-isA = function(expected) {
-  return {
-    __matches: function(actual) {
-      return actual instanceof expected;
-    }
+isA = td.matchers.create({
+  name: 'isA',
+  matches: function(matcherArgs, actual) {
+    var expected = matcherArgs[0]
+    return actual instanceof expected
   }
-}
+})
 ```
 
 Once defined, the above function can be used in a test like this:
@@ -39,3 +43,24 @@ td.when(datePicker(isA(Date))).thenReturn('good')
 datePicker(new Date()) // 'good'
 datePicker(5) // undefined
 ```
+
+#### td.matchers.create API
+
+The `create` function takes a configuration object with the following properties
+
+* **matches(matcherArgs, actual)** - _required_ - a function that returns truthy
+when an `actual` argument satisfies the matcher's rules, given what the user
+passed to the matcher as `matcherArgs` when setting it up. For instance, if
+`td.when(func(isFooBar('foo','bar')).thenReturn('baz')` is configured, then
+`func('biz')` is invoked, then `isFooBar`'s `matches` function will be invoked
+with `matcherArgs` of `['foo','bar']` and `actual` of `'biz'`
+* **name** - _optional_ - a string name for better messages. A function can
+also be provided, which will be passed the user's `matcherArgs` and should return
+a string name
+* **onCreate(matcherInstance, matcherArgs)** - _optional_ - a function invoked
+whenever an instance of a matcher is created to give the matcher author an
+opportunity to mutate the matcher instance or have some other side effect. The
+`td.callback` functionality of the library depends on this option
+
+For some examples of `td.matchers.create()` in action, check out the
+[built-in matchers](src/matchers/index.coffee) provided by testdouble.js.

package.json

@@ -40,7 +40,8 @@
   },
   "dependencies": {
     "lodash": "^3.10.1",
-    "quibble": "^0.3.0"
+    "quibble": "^0.3.0",
+    "stringify-object-with-one-liners": "^1.0.0"
   },
   "devDependencies": {
     "browserify": "^11.0.1",

src/explain.coffee

@@ -3,7 +3,7 @@ _ = require('lodash')
 store = require('./store')
 callsStore = require('./store/calls')
 stubbingsStore = require('./store/stubbings')
-stringifyArgs = require('./stringify-args')
+stringifyArgs = require('./stringify/arguments')
 
 module.exports = (testDouble) ->
   return nullDescription() unless store.for(testDouble, false)?

src/matchers/callback.coffee

@@ -1,10 +1,16 @@
 _ = require('lodash')
+create = require('./create')
 
-module.exports = callback = (args...) ->
-  args: args
-  __testdouble_callback: true
-  __matches: _.isFunction
+module.exports = callback = create
+  name: 'callback'
+  matches: (matcherArgs, actual) ->
+    _.isFunction(actual)
+  onCreate: (matcherInstance, matcherArgs) ->
+    matcherInstance.args = matcherArgs
+    matcherInstance.__testdouble_callback = true
 
+# Make callback itself quack like a matcher for its non-invoked use case.
+callback.__name = 'callback'
 callback.__matches = _.isFunction
 
 callback.isCallback = (obj) ->

src/matchers/captor.coffee

@@ -1,6 +1,9 @@
+create = require('./create')
+
 module.exports = ->
   captor =
-    capture: ->
-      __matches: (actual) ->
+    capture: create
+      name: 'captor.capture'
+      matches: (matcherArgs, actual) ->
         captor.value = actual
         return true

src/matchers/create.coffee

@@ -0,0 +1,18 @@
+_ = require('lodash')
+stringifyArguments = require('../stringify/arguments')
+
+module.exports = (config) ->
+  (matcherArgs...) ->
+    matcherInstance =
+      __name: if _.isFunction(config.name)
+          config.name(matcherArgs)
+        else if config.name?
+          "#{config.name}(#{stringifyArguments(matcherArgs)})"
+        else
+          "[Matcher for (#{stringifyArguments(matcherArgs)})]"
+      __matches: (actualArg) ->
+        config.matches(matcherArgs, actualArg)
+
+    config.onCreate?(matcherInstance, matcherArgs)
+
+    return matcherInstance

src/matchers/index.coffee

@@ -1,11 +1,21 @@
 _ = require('lodash')
-captor = require('./captor')
+create = require('./create')
+stringifyArguments = require('../stringify/arguments')
 
 module.exports =
-  captor: captor
+  create: create
+  captor: require('./captor')
+
+  isA: create
+    name: (matcherArgs) ->
+      s = if matcherArgs[0]?.name?
+          matcherArgs[0].name
+        else
+          stringifyArguments(matcherArgs)
+      "isA(#{s})"
+    matches: (matcherArgs, actual) ->
+      type = matcherArgs[0]
 
-  isA: (type) ->
-    __matches: (actual) ->
       if type == Number
         _.isNumber(actual)
       else if type == String
@@ -15,34 +25,40 @@ module.exports =
       else
         actual instanceof type
 
-  anything: ->
-    __matches: -> true
+  anything: create
+    name: 'anything'
+    matches: -> true
 
-  contains: (containings...) ->
-    containsAllSpecified = (containing, actual) ->
-      _.all containing, (val, key) ->
-        return false unless actual?
-        if _.isPlainObject(val)
-          containsAllSpecified(val, actual[key])
-        else
-          _.eq(val, actual[key])
+  contains: create
+    name: 'contains'
+    matches: (containings, actualArg) ->
+      containsAllSpecified = (containing, actual) ->
+        _.all containing, (val, key) ->
+          return false unless actual?
+          if _.isPlainObject(val)
+            containsAllSpecified(val, actual[key])
+          else
+            _.eq(val, actual[key])
 
-    __matches: (actual) ->
       _.all containings, (containing) ->
         if _.isString(containing)
-          _.include(actual, containing)
+          _.include(actualArg, containing)
         else if _.isArray(containing)
-          _.any actual, (actualElement) ->
+          _.any actualArg, (actualElement) ->
             _.eq(actualElement, containing)
         else if _.isPlainObject(containing)
-          containsAllSpecified(containing, actual)
+          containsAllSpecified(containing, actualArg)
         else
           throw new Error("the contains() matcher only supports strings, arrays, and plain objects")
 
-  argThat: (predicate) ->
-    __matches: (actual) ->
+  argThat: create
+    name: 'argThat'
+    matches: (matcherArgs, actual) ->
+      predicate = matcherArgs[0]
       predicate(actual)
 
-  not: (expected) ->
-    __matches: (actual) ->
+  not: create
+    name: 'not'
+    matches: (matcherArgs, actual) ->
+      expected = matcherArgs[0]
       !_.eq(expected, actual)

src/stringify-args.coffee

@@ -0,0 +1,16 @@
+_ = require('lodash')
+stringifyObject = require('stringify-object-with-one-liners')
+
+module.exports = (anything) ->
+  if _.isString(anything)
+    if _.contains(anything, '\n')
+      "\"\"\"\n#{anything}\n\"\"\""
+    else
+      "\"#{anything.replace(new RegExp('"', 'g'), '\\"')}\""
+  else if anything?.__matches?
+    anything.__name
+  else
+    stringifyObject anything,
+      indent: '  '
+      singleQuotes: false
+      inlineCharacterLimit: 65

src/stringify/anything.coffee

@@ -0,0 +1,7 @@
+_ = require('lodash')
+stringifyAnything = require('./anything')
+
+module.exports = (args, joiner = ", ", wrapper = "") ->
+  _(args).map (arg) ->
+    "#{wrapper}#{stringifyAnything(arg)}#{wrapper}"
+  .join(joiner)