Merge pull request #220 from testdouble/third-party-module-replacement

Add support for third party modules

Author: searls

docs/7-replacing-dependencies.md

@@ -103,9 +103,43 @@ late to have their intended effect).
 
 ### Aside: third-party modules
 
-If you're curious why testdouble.js doesn't support replacing third-party
-modules, you can see our commentary on why we "[don't mock what we don't
-own](B-frequently-asked-questions.md#why-doesnt-tdreplace-work-with-external-commonjs-modules)".
+testdouble.js can also replace third-party npm modules. For instance, if you
+depend on the module [is-number](https://npmjs.org/package/is-number), you can,
+in your test:
+
+```js
+var isNumber = td.replace('is-number')
+var numbersOnly = require('./numbers-only')
+td.when(isNumber('a string')).thenReturn(true) // tee-hee, this is silly
+
+var result = numbersOnly('a string')
+
+assert.equal(result, true)
+```
+
+Should pass for a subject:
+
+```js
+var isNumber = require('is-number')
+
+module.exports = function (thing) {
+  if (!isNumber(thing)) {
+    throw new Error('numbers only!')
+  }
+  return true
+}
+```
+
+Even though testdouble.js does support replacing third-party npm modules, it is
+not recommended unless you own the module! Typically, when practicing the sort
+of outside-in test-driven development that testdouble.js is designed to
+facilitate, you should keep third-party dependencies at arms-length by only
+[mocking what you
+own](http://github.com/testdouble/contributing-tests/wiki/Don%27t-mock-what-you-don%27t-own).
+But if you're managing lots of internal modules and they're all in a consistent
+style such that the line between first-party & third-party code is blurred, then
+`td.replace` has you covered and should be able to replace third-party modules
+or npm packages just like it can for local paths.
 
 ## Browser
 

docs/B-frequently-asked-questions.md

@@ -4,46 +4,6 @@ Whenever someone asks a particularly salient question about testdouble.js, we'll
 log it here for the benefit of anyone reading up on how to make the most use of
 the library.
 
-## Why doesn't `td.replace()` work with external CommonJS modules?
-
-[Jörn Zaefferer asked](https://github.com/testdouble/testdouble.js/issues/51)
-whether testdouble.js would support replacing third-party CommonJS modules in
-Node.js with the [td.replace()](7-replacing-dependencies.md) feature.
-
-The short answer is "no, testdouble.js does not plan to support this".
-
-The longer answer is that when we practice TDD with test doubles, we "don't mock
-what we don't own". The reason for using mocks in our practice is to improve the
-richness of design feedback by making awkward interactions with dependencies
-painful; the appropriate response to that pain is to make that dependency's API
-better.
-
-With that being the purpose of using test doubles, replacing a third-party API
-will often just lead to *useless pain*, because the author isn't in an immediate
-position to improve the third party API.
-
-Rather, our use of 3rd party dependencies (insofar as how our unit tests interact
-with them) typically break down into two categories:
-
-* Utility functions (e.g. `lodash`) — we call through to the real utility
-function from our unit test so long as they don't add additional side effects or
-break the purity of the function; I use these much more in unit tests of pure
-functions, which themselves typically don't require any dependencies (and
-therefore test doubles) at all
-* Integration functions (e.g. `request`) — we create adapters/wrappers of these
-dependencies that delegate to the third-party functions and then we replace those
-adapters/wrappers in our tests. That way, any custom branching, configuration,
-or API de-awkward-ification we apply to that dependency is in the wrapper and
-effectively centralized in a single place in the app. Not only is this a great
-way to prevent a third party module from seeping throughout the codebase, but it
-can provide a template for how to later replace that area of functionality with
-a different 3rd party dependency. It can even be a good first step towards
-introducing an adapter pattern to deal with an option of multiple 3rd party
-dependencies.
-
-As a result, we aren't planning to go out of our way to support replacing modules
-with quibble / td.js
-
 ## Why shouldn't I call both td.when and td.verify for a single interaction with a test double?
 
 It's a common mistake to call `td.verify` for an invocation that's already been

examples/node/lib/elastic-thing.js

@@ -0,0 +1,5 @@
+var elasticsearch = require('elasticsearch')
+
+module.exports = function () {
+  return elasticsearch.Client()
+}

examples/node/lib/numbers-only.js

@@ -0,0 +1,8 @@
+var isNumber = require('is-number')
+
+module.exports = function (thing) {
+  if (!isNumber(thing)) {
+    throw new Error('numbers only!')
+  }
+  return true
+}

examples/node/package.json

@@ -7,6 +7,8 @@
   },
   "devDependencies": {
     "chai": "^3.3.0",
+    "elasticsearch": "^12.1.3",
+    "is-number": "^3.0.0",
     "mocha": "^2.3.3",
     "testdouble": "*"
   }

examples/node/test/lib/elastic-thing-test.js

@@ -0,0 +1,11 @@
+describe('elastic-thing', function () {
+  it('is quite elastic', function () {
+    var elasticsearch = td.replace('elasticsearch')
+    var subject = require('../../lib/elastic-thing')
+    td.when(elasticsearch.Client()).thenReturn('pants')
+
+    var result = subject()
+
+    expect(result).to.eq('pants')
+  })
+})

examples/node/test/lib/numbers-only-test.js

@@ -0,0 +1,11 @@
+describe('numbers-only', function () {
+  it('replaces modules ok', function () {
+    var isNumber = td.replace('is-number')
+    var numbersOnly = require('../../lib/numbers-only')
+    td.when(isNumber('a string')).thenReturn(true) // tee-hee, this is silly
+
+    var result = numbersOnly('a string')
+
+    expect(result).to.eq(true)
+  })
+})

examples/node/yarn.lock

@@ -2,6 +2,18 @@
 # yarn lockfile v1
 
 
+ansi-regex@^2.0.0:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-2.1.1.tgz#c3b33ab5ee360d86e0e628f0468ae7ef27d654df"
+
+ansi-styles@^2.2.1:
+  version "2.2.1"
+  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-2.2.1.tgz#b432dd3358b634cf75e1e4664368240533c1ddbe"
+
+asap@~2.0.3:
+  version "2.0.5"
+  resolved "https://registry.yarnpkg.com/asap/-/asap-2.0.5.tgz#522765b50c3510490e52d7dcfe085ef9ba96958f"
+
 assertion-error@^1.0.1:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/assertion-error/-/assertion-error-1.0.2.tgz#13ca515d86206da0bac66e834dd397d87581094c"
@@ -14,6 +26,16 @@ chai@^3.3.0:
     deep-eql "^0.1.3"
     type-detect "^1.0.0"
 
+chalk@^1.0.0:
+  version "1.1.3"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-1.1.3.tgz#a8115c55e4a702fe4d150abd3872822a7e09fc98"
+  dependencies:
+    ansi-styles "^2.2.1"
+    escape-string-regexp "^1.0.2"
+    has-ansi "^2.0.0"
+    strip-ansi "^3.0.0"
+    supports-color "^2.0.0"
+
 [email protected]:
   version "0.6.1"
   resolved "https://registry.yarnpkg.com/commander/-/commander-0.6.1.tgz#fa68a14f6a945d54dbbe50d8cdb3320e9e3b1a06"
@@ -38,10 +60,23 @@ [email protected]:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/diff/-/diff-1.4.0.tgz#7f28d2eb9ee7b15a97efd89ce63dcfdaa3ccbabf"
 
-[email protected]:
+elasticsearch@^12.1.3:
+  version "12.1.3"
+  resolved "https://registry.yarnpkg.com/elasticsearch/-/elasticsearch-12.1.3.tgz#5108e67ae5d83e5e7f30d3d294fd7017df0e3771"
+  dependencies:
+    chalk "^1.0.0"
+    forever-agent "^0.6.0"
+    lodash "^4.12.0"
+    promise "^7.1.1"
+
+[email protected], escape-string-regexp@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.2.tgz#4dbc2fe674e71949caf3fb2695ce7f2dc1d9a8d1"
 
+forever-agent@^0.6.0:
+  version "0.6.1"
+  resolved "https://registry.yarnpkg.com/forever-agent/-/forever-agent-0.6.1.tgz#fbc71f0c41adeb37f96c577ad1ed42d8fdacca91"
+
 [email protected]:
   version "3.2.11"
   resolved "https://registry.yarnpkg.com/glob/-/glob-3.2.11.tgz#4a973f635b9190f715d10987d5c00fd2815ebe3d"
@@ -53,10 +88,26 @@ [email protected]:
   version "1.9.2"
   resolved "https://registry.yarnpkg.com/growl/-/growl-1.9.2.tgz#0ea7743715db8d8de2c5ede1775e1b45ac85c02f"
 
+has-ansi@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/has-ansi/-/has-ansi-2.0.0.tgz#34f5049ce1ecdf2b0649af3ef24e45ed35416d91"
+  dependencies:
+    ansi-regex "^2.0.0"
+
 inherits@2:
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.3.tgz#633c2c83e3da42a502f52466022480f4208261de"
 
+is-buffer@^1.0.2:
+  version "1.1.5"
+  resolved "https://registry.yarnpkg.com/is-buffer/-/is-buffer-1.1.5.tgz#1f3b26ef613b214b88cbca23cc6c01d87961eecc"
+
+is-number@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/is-number/-/is-number-3.0.0.tgz#24fd6201a4782cf50561c810276afc7d12d71195"
+  dependencies:
+    kind-of "^3.0.2"
+
 is-plain-obj@^1.0.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/is-plain-obj/-/is-plain-obj-1.1.0.tgz#71a50c8429dfca773c92a390a4a03b39fcd51d3e"
@@ -72,7 +123,13 @@ [email protected]:
     commander "0.6.1"
     mkdirp "0.3.0"
 
-lodash@^4.15.0, lodash@^4.17.2:
+kind-of@^3.0.2:
+  version "3.1.0"
+  resolved "https://registry.yarnpkg.com/kind-of/-/kind-of-3.1.0.tgz#475d698a5e49ff5e53d14e3e732429dc8bf4cf47"
+  dependencies:
+    is-buffer "^1.0.2"
+
+lodash@^4.12.0, lodash@^4.15.0, lodash@^4.17.2:
   version "4.17.4"
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.4.tgz#78203a4d1c328ae1d86dca6460e369b57f4055ae"
 
@@ -120,6 +177,12 @@ [email protected]:
   version "0.7.1"
   resolved "https://registry.yarnpkg.com/ms/-/ms-0.7.1.tgz#9cd13c03adbff25b65effde7ce864ee952017098"
 
+promise@^7.1.1:
+  version "7.1.1"
+  resolved "https://registry.yarnpkg.com/promise/-/promise-7.1.1.tgz#489654c692616b8aa55b0724fa809bb7db49c5bf"
+  dependencies:
+    asap "~2.0.3"
+
 quibble@^0.4.0:
   version "0.4.0"
   resolved "https://registry.yarnpkg.com/quibble/-/quibble-0.4.0.tgz#a1535c4a80b3d3617d23c5d770f1ec2c7b5523a1"
@@ -137,10 +200,20 @@ stringify-object@^2.4.0:
     is-plain-obj "^1.0.0"
     is-regexp "^1.0.0"
 
+strip-ansi@^3.0.0:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-3.0.1.tgz#6a385fb8853d952d5ff05d0e8aaf94278dc63dcf"
+  dependencies:
+    ansi-regex "^2.0.0"
+
 [email protected]:
   version "1.2.0"
   resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-1.2.0.tgz#ff1ed1e61169d06b3cf2d588e188b18d8847e17e"
 
+supports-color@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-2.0.0.tgz#535d045ce6b6363fa40117084629995e9df324c7"
+
 testdouble@*:
   version "1.11.2"
   resolved "https://registry.yarnpkg.com/testdouble/-/testdouble-1.11.2.tgz#8b6a2e418ad1da9991e479203e37528dfd81d557"

package.json

@@ -61,6 +61,7 @@
   "dependencies": {
     "lodash": "^4.15.0",
     "quibble": "^0.4.1",
+    "resolve": "^1.3.2",
     "stringify-object-es5": "^2.5.0"
   },
   "devDependencies": {
@@ -73,6 +74,7 @@
     "coffee-script": "^1.10.0",
     "coffeeify": "^2.1.0",
     "headerify": "^1.0.1",
+    "is-number": "^3.0.0",
     "mocha": "^3.2.0",
     "mocha-given": "^0.1.3",
     "nyc": "^10.1.2",

src/replace/module.js

@@ -1,12 +1,23 @@
 import imitate from './imitate'
 import quibble from 'quibble'
+import resolve from 'resolve'
 
 quibble.ignoreCallsFromThisFile()
 
 export default function (path, stub) {
   if (arguments.length > 1) { return quibble(path, stub) }
-  const realThing = require(quibble.absolutify(path))
+  const realThing = requireAt(path)
   const fakeThing = imitate(realThing, path)
   quibble(path, fakeThing)
   return fakeThing
 }
+
+var requireAt = (path) => {
+  try {
+    // 1. Try just following quibble's inferred path
+    return require(quibble.absolutify(path))
+  } catch (e) {
+    // 2. Try including npm packages
+    return require(resolve.sync(path, { basedir: process.cwd() }))
+  }
+}