From 61122fb7deaeec0ebf543d594f456de9efa5a622 Mon Sep 17 00:00:00 2001 From: Rhys Evans Date: Tue, 5 May 2015 23:41:50 +0100 Subject: [PATCH] Better API docs --- README.md | 56 +++++++++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 568bdf88..68fe18eb 100644 --- a/README.md +++ b/README.md @@ -11,24 +11,24 @@ Mock http requests made using fetch (or isomorphic-fetch) `require('fetch-mock')` exports a singleton with the following methods ### `mock(config)` -Replaces `fetch` with a sinon stub which, in addition to the default sinon behaviour, records each of its calls and optionally returns a stub response or passes the call through to `fetch`. `config` is an optional* object with the following properties. - -* `routes` Either a single object or an array of similar objects each defining how the mock handles a given request. Each route object must have the following properties. If multiple routes are specified the first matching route will be used to define the response - * `name` A unique string naming the route - * `matcher` The rule for matching calls to `fetch`. Accepts any of the following - * `string` Either an exact url to match e.g. 'http://www.site.com/page.html' or, if the string begins with a `^`, the string following the `^` must begin the url e.g. '^http://www.site.com' would match 'http://www.site.com' or '^http://www.site.com/page.html' - * `RegExp` A regular expression to test the url against - * `Function(url, opts)` A function that is passed the url and opts `fetch` is called with and that returns a Boolean - * `response` Configures the response object returned by the mock. Can have one of the following values - * `string` creates a 200 response with the string as the response body - * `config object` If the object contains any of the properties body, status, headers, throws; then these properties - all of them optional - are used to construct a response as follows - * `body` Retunred in the response body - * `status` Returned in the response status - * `headers` Returned in the response headers. They should be defined as an object literal (property names case-insensitive) which will be converted to a `Headers` instance - * `throws` If this property is present then a `Promise` rejected with the value of `throws` is returned - * `object literal` As long as the object does not contain any of the above properties it is converted into a json string and this is returned as the body of a 200 response - * `Function(url, opts)` A function that is passed the url and opts `fetch` is called with and that returns any of the responses listed above -* `responses` When `registerRoute` has already been used to register some routes then `responses` can be used to override the default response. It's value should be an object mapping route names to responses, which should be similar to those listed immediately above e.g. +Replaces `fetch()` with a sinon stub which, in addition to the default sinon behaviour, records each of its calls and optionally returns a stub response or passes the call through to `fetch()`. `config` is an optional* object with the following properties. + +* `routes`: Either a single object or an array of similar objects each defining how the mock handles a given request. Each route object must have the following properties. If multiple routes are specified the first matching route will be used to define the response + * `name`: A unique string naming the route + * `matcher`: The rule for matching calls to `fetch()`. Accepts any of the following + * `string`: Either an exact url to match e.g. 'http://www.site.com/page.html' or, if the string begins with a `^`, the string following the `^` must begin the url e.g. '^http://www.site.com' would match 'http://www.site.com' or 'http://www.site.com/page.html' + * `RegExp`: A regular expression to test the url against + * `Function(url, opts)`: A function that is passed the url and opts `fetch` is called with and that returns a Boolean + * `response`: Configures the response object returned by the mock. Can have one of the following values + * `string`: creates a 200 response with the string as the response body + * `object`: If the object contains any of the properties body, status, headers, throws; then these properties - all of them optional - are used to construct a response as follows + * `body`: Retunred in the response body + * `status`: Returned in the response status + * `headers`: Returned in the response headers. They should be defined as an object literal (property names case-insensitive) which will be converted to a `Headers` instance + * `throws`: If this property is present then a `Promise` rejected with the value of `throws` is returned + As long as the object does not contain any of the above properties it is converted into a json string and this is returned as the body of a 200 response + * `Function(url, opts)`: A function that is passed the url and opts `fetch()` is called with and that returns any of the responses listed above +* `responses`: When `registerRoute()` has already been used to register some routes then `responses` can be used to override the default response. Its value should be an object mapping route names to responses, which should be similar to those listed immediately above e.g. ```javascript responses: { @@ -42,8 +42,8 @@ Replaces `fetch` with a sinon stub which, in addition to the default sinon behav } ``` -* `greed` Determines how the mock handles unmatched requests - * 'none': all unmatched calls get passed through to `fetch` +* `greed`: Determines how the mock handles unmatched requests + * 'none': all unmatched calls get passed through to `fetch()` * 'bad': all unmatched calls result in a rejected promise * 'good': all unmatched calls result in a resolved promise with a 200 status @@ -52,13 +52,13 @@ Replaces `fetch` with a sinon stub which, in addition to the default sinon behav ### `restore()` -Restores `fetch` to its unstubbed state and clears all data recorded for its calls +Restores `fetch()` to its unstubbed state and clears all data recorded for its calls ### `reset()` -Clears all data recorded for `fetch`'s calls +Clears all data recorded for `fetch()`'s calls ### `calls(routeName)` -Returns an array of arrays of the arguments passed to `fetch` that matched the given route +Returns an array of arrays of the arguments passed to `fetch()` that matched the given route ### `called(routeName)` Returns a Boolean denoting whether any calls matched the given route @@ -67,12 +67,12 @@ Returns a Boolean denoting whether any calls matched the given route Normally calling `mock()` twice without restoring inbetween will throw an error. `reMock()` calls `restore()` internally before calling `mock()` again. This allows you to put a generic call to `mock()` in a `beforeEach()` while retaining the flexibility to vary the responses for some tests ### `registerRoute(name, matcher, response)` -Often your application/module will always need responses for some calls in order to initialise properly, even if the content of those calls are not the subject of a given test e.g. a mock response from an authentication service and a lti-variant testing service might be necessary in order to test the UI for a version of a log in form. It's helpful to be able to define some default responses for these services which will exist throughout all or a large subset of your tests. `registerRoute` aims to fulfil this need. All these predefined routes can be overridden when `mock(config)` is called. +Often your application/module will always need responses for some calls in order to initialise properly, even if the content of those calls are not the subject of a given test e.g. a mock response from an authentication service and a lti-variant testing service might be necessary in order to test the UI for a version of a log in form. It's helpful to be able to define some default responses for these services which will exist throughout all or a large subset of your tests. `registerRoute()` aims to fulfil this need. All these predefined routes can be overridden when `mock(config)` is called. -`registerRoute` takes either of the following parameters -* `object` An object similar to the route objects accepted by `mock()` -* `array` An array of the above objects -* `name`, `matcher`, `response` The 3 properties of the route object spread across 3 parameters +`registerRoute()` takes either of the following parameters +* `object`: An object similar to the route objects accepted by `mock()` +* `array`: An array of the above objects +* `name`, `matcher`, `response`: The 3 properties of the route object spread across 3 parameters ### `unregisterRoute(name)` Unregisters one or more previously registered routes. Accepts either a string or an array of strings