move outline

searls · searls · commit b49b9b3af1ba · 2018-02-08T16:31:51.000-05:00
diff --git a/README.md b/README.md
@@ -90,7 +90,7 @@ uses a library we wrote called [quibble](https://github.com/testdouble/quibble)
 to monkey-patch the `require()` feature so that your subject will automatically
 receive your faked dependencies simply by requiring them. (If you've used
 something like [proxyquire](https://github.com/thlorenz/proxyquire), this is
-like a slightly terser form of that)
+like a slightly terser form of that.)
 
 Here's an example of using `td.replace` in the setup of a test of a Node.js
 module:
@@ -128,17 +128,19 @@ in order to bypass Node's module cache and avoid test pollution
 * The test suite (usually in a global after-each hook) must call `td.reset()` to
 avoid test pollution
 
-##### default exports with ES modules
+##### Default exports with ES modules
 
-If your production code is written in ES module syntax and specifies a default
-export, just remember that you'll need to reference `.default` when translating
-to CJS syntax. That means:
+If your modules are written in the ES module syntax and they specify default
+exports, just remember that you'll need to reference `.default` when translating
+to CJS syntax.
+
+That means instead of this:
 
 ```js
 loadsPurchases = td.replace('../src/loads-purchases')
 ```
 
-Probably needs to be written as:
+You probable mean to assign the fake like this:
 
 ```js
 loadsPurchases = td.replace('../src/loads-purchases').default
@@ -151,7 +153,7 @@ loadsPurchases = td.replace('../src/loads-purchases').default
 If you're running tests outside Node.js or otherwise injecting dependencies
 manually (or with a DI tool like
 [dependable](https://github.com/testdouble/dependable)), then you may still use
-`td.replace` to automatically replace things if they're addressable as
+`td.replace` to automatically replace things if they're referenceable as
 properties on an object.
 
 To illustrate, suppose our subject depends on `app.signup` below:
@@ -163,7 +165,7 @@ app.signup = {
 }
 ```
 
-If our goal is to replace `app.signup` so during a test of `app.user.create(),
+If our goal is to replace `app.signup` during a test of `app.user.create()`,
 our test setup might look like this:
 
 ```js
@@ -183,16 +185,16 @@ in this case it's obviously still referenceable by the test and subject alike
 with `app.signup`. If we had wanted to only replace the `onCancel` function for
 whatever reason (though in this case, that would smell like a [partial
 mock](https://github.com/testdouble/contributing-tests/wiki/Partial-Mock)), we
-could have called `td.replace(app.signup, 'onCancel)`, instead.
+could have called `td.replace(app.signup, 'onCancel')`, instead.
 
 Remember, calling `td.reset()` in an after-each hook (preferably globally so one
-doesn't have to remember in each-and-every test) so that testdouble.js can
-replace the original is crucial to avoiding test pollution!
+doesn't have to remember to do so in each-and-every test) so that testdouble.js
+can replace the original is crucial to avoiding hard-to-debug test pollution!
 
 #### Specifying a custom replacement
 
 The library's [imitation
-feature](https://github.com/testdouble/testdouble.js/blob/updte-readme/src/imitate/index.js)
+feature](https://github.com/testdouble/testdouble.js/blob/master/src/imitate/index.js)
 is pretty sophisticated, but it's not perfect. It's also going to be pretty slow
 on large, complex objects. If you'd like to specify exactly what to replace a
 real dependency with, you can do so in either of the above modes by providing a
@@ -216,6 +218,93 @@ signup = td.replace(app, 'signup', {
 })
 ```
 
+### `td.func()`, `td.object()`, and `td.constructor()` to create test doubles
+
+`td.replace()`'s imitation and injection convenience is great when your
+project's build configuration allows for it, but in many cases you'll want or
+need the control to create fake things directly. Each creation function can
+either imitate a real thing or be specified by passing a bit of configuration.
+
+Each test double creation function is very flexible and can take a variety of
+inputs. What gets returned generally depends on the number and type of configuration
+parameters passed in, so we'll highlight each supported usage separately with an
+example invocation:
+
+#### `td.func()`
+
+The `td.func()` function (also available as `td.function()`) returns a test
+double function and can be called in three modes:
+
+* **`td.func(someRealFunction)`** - returns a test double function of the same
+  `name`, including a deep
+  [imitation](https://github.com/testdouble/testdouble.js/blob/master/src/imitate/index.js)
+  of all of its custom properties
+* **`td.func()`** - returns an anonymous test double function that can be used
+  for stubbing and verifying any calls against it, but whose error messages and
+  debugging output won't have a name to trace back to it
+* **`td.func('some name')** - returns a test double function named 'some name',
+  which will appear in any error messages as well as the debug info returned by
+  passing the returned test double into `td.explain()`
+
+#### `td.object()`
+
+The `td.object()` function returns an object containing test double functions,
+and supports three types of invocations:
+
+* **`td.object(realObject)`** - returns a deep
+  [imitation](https://github.com/testdouble/testdouble.js/blob/master/src/imitate/index.js)
+  the passed object, where each function is replaced with a test double function
+  named for the property path (e.g. If `realObject.invoices.send()` was a
+  function, the returned object would have a test double named
+  `'.invoices.send'`)
+* **`td.object(['add', 'subtract'])`** - returns a plain JavaScript object
+  containing two properties `add` and `subtract` that are both assigned to test
+  double functions named `'.add'` and `'.subtract'`, respectively.
+* **`td.object(['a Person', {excludeMethods: ['then']})`** - when passed with no
+  args or with a string as the first argument, returns an [ES
+  Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).
+  The proxy will automatically intercept any call made to it and shunt in a test
+  double that can be used for stubbing or verification. More details can be
+  found in [our full docs](/docs/4-creating-test-doubles.md#objectobjectname)
+
+#### `td.constructor()`
+
+If your code depends on ES classes or functions intended to be called with
+`new`, then the `td.constructor()` function can replace those dependencies as
+well.
+
+* **`td.constructor(RealConstructor)`** - returns a constructor whose calls can
+  be verified and whose `prototype` functions have all been replaced with test
+  double functions using the same
+  [imitation](https://github.com/testdouble/testdouble.js/blob/master/src/imitate/index.js)
+* **`td.constructor(['select', 'save'])`** - returns a constructor with `select`
+  and `save` properties set to test double functions named `'#select'` and
+  `'#save'` on its `prototype` object
+
+When replacing a constructor, typically the test will configure stubbing &
+verification by directly addressing its prototype functions.
+
+To illustrate, That means in your test you might write:
+
+```js
+const FakeConstructor = td.constructor(RealConstructor)
+td.when(FakeConstructor.prototype.doStuff()).thenReturn('ok')
+subject(FakeConstructor)
+```
+
+So that in your production code you can:
+
+```js
+const subject = function (SomeConstructor) {
+  const thing = new SomeConstructor()
+  return thing.doStuff() // returns "ok"
+}
+```
+
+---
+# old docs:
+---
+
 ### Stubbing return values for functions
 
 ```js
@@ -246,73 +335,3 @@ td.verify(save(41, 'Jill'));
 //     - called with `(41, "Jane")`.
 ```
 
-## Docs
-
-All of our docs are in the [docs/](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](docs/1-installation.md#installing-testdoublejs)
-   1. [for Node.js](docs/1-installation.md#for-use-in-nodejs-or-browserify)
-   2. [for browsers](docs/1-installation.md#for-use-in-browsers)
-   3. [initial configuration](docs/1-installation.md#configuring-testdoublejs-setting-up-in-your-test-suite)
-2. [Purpose of testdouble.js](docs/2-howto-purpose.md#purpose)
-   1. [in unit tests](docs/2-howto-purpose.md#test-doubles-and-unit-tests)
-   2. [in integration tests](docs/2-howto-purpose.md#test-doubles-and-integration-tests)
-3. [Getting started tutorial](docs/3-getting-started.md#getting-started)
-4. [Creating test doubles](docs/4-creating-test-doubles.md#creating-test-doubles)
-   1. [test double functions with `td.function()`](docs/4-creating-test-doubles.md#tdfunctionname)
-   2. [test double objects with `td.object()`](docs/4-creating-test-doubles.md#tdobject)
-   3. [test double constructors with `td.constructor()`](docs/4-creating-test-doubles.md#tdconstructor)
-5. [Stubbing responses](docs/5-stubbing-results.md#stubbing-behavior)
-   1. [td.when() API](docs/5-stubbing-results.md#tdwhen)
-   2. [equality argument matching](docs/5-stubbing-results.md#simple-precise-argument-stubbing)
-   3. [one-liner stubbings](docs/5-stubbing-results.md#one-liner-stubbings)
-   4. [stubbing sequential return values](docs/5-stubbing-results.md#stubbing-sequential-return-values)
-   5. [argument matchers](docs/5-stubbing-results.md#loosening-stubbings-with-argument-matchers)
-      1. [td.matchers.anything()](docs/5-stubbing-results.md#tdmatchersanything)
-      2. [td.matchers.isA()](docs/5-stubbing-results.md#tdmatchersisa)
-      3. [td.matchers.contains()](docs/5-stubbing-results.md#tdmatcherscontains)
-         1. [matching strings](docs/5-stubbing-results.md#strings)
-         2. [matching arrays](docs/5-stubbing-results.md#arrays)
-         3. [matching objects](docs/5-stubbing-results.md#objects)
-      4. [td.matchers.argThat()](docs/5-stubbing-results.md#tdmatchersargthat)
-      5. [td.matchers.not()](docs/5-stubbing-results.md#tdmatchersnot)
-   6. [Stubbing callback APIs](docs/5-stubbing-results.md#stubbing-callback-apis)
-   7. [Stub exceptions with thenThrow](docs/5-stubbing-results.md#stub-exceptions-with-thenthrow)
-   8. [Stub promises with thenResolve and thenReject](docs/5-stubbing-results.md#stub-promises-with-thenresolve-and-thenreject)
-   9. [Stub side effects with thenDo](docs/5-stubbing-results.md#stub-side-effects-with-thendo)
-   10. [Configuring stubbings](docs/5-stubbing-results.md#configuring-stubbings)
-      1. [ignoreExtraArgs](docs/5-stubbing-results.md#ignoreextraargs)
-      2. [times](docs/5-stubbing-results.md#times)
-      3. [defer](docs/5-stubbing-results.md#defer)
-      4. [delay](docs/5-stubbing-results.md#delay)
-6. [Verifying invocations](docs/6-verifying-invocations.md#verifying-interactions)
-   1. [td.verify() API](docs/6-verifying-invocations.md#tdverify)
-   2. [equality argument matching](docs/6-verifying-invocations.md#arguments)
-   3. [argument matchers](docs/6-verifying-invocations.md#relaxing-verifications-with-argument-matchers)
-      1. [td.matchers.anything()](docs/6-verifying-invocations.md#tdmatchersanything)
-      2. [td.matchers.isA()](docs/6-verifying-invocations.md#tdmatchersisa)
-      3. [td.matchers.contains()](docs/6-verifying-invocations.md#tdmatcherscontains)
-         1. [matching strings](docs/6-verifying-invocations.md#strings)
-         2. [matching arrays](docs/6-verifying-invocations.md#arrays)
-         3. [matching objects](docs/6-verifying-invocations.md#objects)
-      4. [td.matchers.argThat()](docs/6-verifying-invocations.md#tdmatchersargthat)
-   4. [Argument captors](docs/6-verifying-invocations.md#multi-phase-assertions-with-argument-captors)
-   5. [Configuring verifications](docs/6-verifying-invocations.md#configuring-verifications)
-      1. [ignoreExtraArgs](docs/6-verifying-invocations.md#ignoreextraargs)
-      2. [times](docs/6-verifying-invocations.md#times)
-7. [Replacing dependencies with test doubles](docs/7-replacing-dependencies.md#replacing-real-dependencies-with-test-doubles)
-   1. [for Node.js](docs/7-replacing-dependencies.md#nodejs)
-   2. [for Browser JS](docs/7-replacing-dependencies.md#browser)
-   3. [td.replace() API](docs/7-replacing-dependencies.md#testdoublereplace-api)
-8. [Writing custom argument matchers](docs/8-custom-matchers.md#custom-argument-matchers)
-9. [Debugging with testdouble.js](docs/9-debugging.md#debugging-with-testdoublejs)
-   1. [td.explain() API](docs/9-debugging.md#tdexplainsometestdouble)
-10. [Plugins](docs/A-plugins.md#plugins)
-    1. [testdouble-chai](https://github.com/basecase/testdouble-chai)
-    2. [testdouble-jasmine](https://github.com/BrianGenisio/testdouble-jasmine)
-11. [Frequently Asked Questions](docs/B-frequently-asked-questions.md#frequently-asked-questions)
-    1. [Why shouldn't I call both td.when and td.verify for a single interaction with a test double?](docs/B-frequently-asked-questions.md#why-shouldnt-i-call-both-tdwhen-and-tdverify-for-a-single-interaction-with-a-test-double)
-12. [Configuration](docs/C-configuration.md#configuration)
-    1. [td.config](docs/C-configuration.md#tdconfig)
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,70 @@
+# Docs
+
+All of our docs are in this are numbered for easy reading in the order we
+anticipate people will needing them.  Here's an outline with links to each
+section:
+
+1. [Installation](1-installation.md#installing-testdoublejs)
+   1. [for Node.js](1-installation.md#for-use-in-nodejs-or-browserify)
+   2. [for browsers](1-installation.md#for-use-in-browsers)
+   3. [initial configuration](1-installation.md#configuring-testdoublejs-setting-up-in-your-test-suite)
+2. [Purpose of testdouble.js](2-howto-purpose.md#purpose)
+   1. [in unit tests](2-howto-purpose.md#test-doubles-and-unit-tests)
+   2. [in integration tests](2-howto-purpose.md#test-doubles-and-integration-tests)
+3. [Getting started tutorial](3-getting-started.md#getting-started)
+4. [Creating test doubles](4-creating-test-doubles.md#creating-test-doubles)
+   1. [test double functions with `td.function()`](4-creating-test-doubles.md#tdfunctionname)
+   2. [test double objects with `td.object()`](4-creating-test-doubles.md#tdobject)
+   3. [test double constructors with `td.constructor()`](4-creating-test-doubles.md#tdconstructor)
+5. [Stubbing responses](5-stubbing-results.md#stubbing-behavior)
+   1. [td.when() API](5-stubbing-results.md#tdwhen)
+   2. [equality argument matching](5-stubbing-results.md#simple-precise-argument-stubbing)
+   3. [one-liner stubbings](5-stubbing-results.md#one-liner-stubbings)
+   4. [stubbing sequential return values](5-stubbing-results.md#stubbing-sequential-return-values)
+   5. [argument matchers](5-stubbing-results.md#loosening-stubbings-with-argument-matchers)
+      1. [td.matchers.anything()](5-stubbing-results.md#tdmatchersanything)
+      2. [td.matchers.isA()](5-stubbing-results.md#tdmatchersisa)
+      3. [td.matchers.contains()](5-stubbing-results.md#tdmatcherscontains)
+         1. [matching strings](5-stubbing-results.md#strings)
+         2. [matching arrays](5-stubbing-results.md#arrays)
+         3. [matching objects](5-stubbing-results.md#objects)
+      4. [td.matchers.argThat()](5-stubbing-results.md#tdmatchersargthat)
+      5. [td.matchers.not()](5-stubbing-results.md#tdmatchersnot)
+   6. [Stubbing callback APIs](5-stubbing-results.md#stubbing-callback-apis)
+   7. [Stub exceptions with thenThrow](5-stubbing-results.md#stub-exceptions-with-thenthrow)
+   8. [Stub promises with thenResolve and thenReject](5-stubbing-results.md#stub-promises-with-thenresolve-and-thenreject)
+   9. [Stub side effects with thenDo](5-stubbing-results.md#stub-side-effects-with-thendo)
+   10. [Configuring stubbings](5-stubbing-results.md#configuring-stubbings)
+      1. [ignoreExtraArgs](5-stubbing-results.md#ignoreextraargs)
+      2. [times](5-stubbing-results.md#times)
+      3. [defer](5-stubbing-results.md#defer)
+      4. [delay](5-stubbing-results.md#delay)
+6. [Verifying invocations](6-verifying-invocations.md#verifying-interactions)
+   1. [td.verify() API](6-verifying-invocations.md#tdverify)
+   2. [equality argument matching](6-verifying-invocations.md#arguments)
+   3. [argument matchers](6-verifying-invocations.md#relaxing-verifications-with-argument-matchers)
+      1. [td.matchers.anything()](6-verifying-invocations.md#tdmatchersanything)
+      2. [td.matchers.isA()](6-verifying-invocations.md#tdmatchersisa)
+      3. [td.matchers.contains()](6-verifying-invocations.md#tdmatcherscontains)
+         1. [matching strings](6-verifying-invocations.md#strings)
+         2. [matching arrays](6-verifying-invocations.md#arrays)
+         3. [matching objects](6-verifying-invocations.md#objects)
+      4. [td.matchers.argThat()](6-verifying-invocations.md#tdmatchersargthat)
+   4. [Argument captors](6-verifying-invocations.md#multi-phase-assertions-with-argument-captors)
+   5. [Configuring verifications](6-verifying-invocations.md#configuring-verifications)
+      1. [ignoreExtraArgs](6-verifying-invocations.md#ignoreextraargs)
+      2. [times](6-verifying-invocations.md#times)
+7. [Replacing dependencies with test doubles](7-replacing-dependencies.md#replacing-real-dependencies-with-test-doubles)
+   1. [for Node.js](7-replacing-dependencies.md#nodejs)
+   2. [for Browser JS](7-replacing-dependencies.md#browser)
+   3. [td.replace() API](7-replacing-dependencies.md#testdoublereplace-api)
+8. [Writing custom argument matchers](8-custom-matchers.md#custom-argument-matchers)
+9. [Debugging with testdouble.js](9-debugging.md#debugging-with-testdoublejs)
+   1. [td.explain() API](9-debugging.md#tdexplainsometestdouble)
+10. [Plugins](A-plugins.md#plugins)
+    1. [testdouble-chai](https://github.com/basecase/testdouble-chai)
+    2. [testdouble-jasmine](https://github.com/BrianGenisio/testdouble-jasmine)
+11. [Frequently Asked Questions](B-frequently-asked-questions.md#frequently-asked-questions)
+    1. [Why shouldn't I call both td.when and td.verify for a single interaction with a test double?](B-frequently-asked-questions.md#why-shouldnt-i-call-both-tdwhen-and-tdverify-for-a-single-interaction-with-a-test-double)
+12. [Configuration](C-configuration.md#configuration)
+    1. [td.config](C-configuration.md#tdconfig)
