Merge pull request #359 from wheresrhys/docs-redux

Docs redux

.eslintignore

@@ -3,3 +3,4 @@ dist/*
 coverage/*
 es5/*
 .nyc_output/
+docs/js

.gitignore

@@ -6,3 +6,5 @@ coverage/
 /test/fixtures/built-sw.js
 .nyc_output
 .eslintcache
+/docs/_site/
+/docs/.sass-cache/

Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+gem 'jekyll', '3.7.2'
+
+group :jekyll_plugins do
+  gem 'jekyll-seo-tag', '2.4.0'
+  gem 'jekyll-sitemap', '1.2.0'
+end

Gemfile.lock

@@ -0,0 +1,69 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.0.5)
+    em-websocket (0.5.1)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    ffi (1.9.25)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.6.0)
+    i18n (0.9.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (3.7.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 0.7)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 1.14)
+      liquid (~> 4.0)
+      mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
+      rouge (>= 1.7, < 4)
+      safe_yaml (~> 1.0)
+    jekyll-sass-converter (1.5.2)
+      sass (~> 3.4)
+    jekyll-seo-tag (2.4.0)
+      jekyll (~> 3.3)
+    jekyll-sitemap (1.2.0)
+      jekyll (~> 3.3)
+    jekyll-watch (2.0.0)
+      listen (~> 3.0)
+    kramdown (1.17.0)
+    liquid (4.0.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    mercenary (0.3.6)
+    pathutil (0.16.1)
+      forwardable-extended (~> 2.6)
+    public_suffix (3.0.3)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rouge (3.2.1)
+    ruby_dep (1.5.0)
+    safe_yaml (1.0.4)
+    sass (3.5.7)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jekyll (= 3.7.2)
+  jekyll-seo-tag (= 2.4.0)
+  jekyll-sitemap (= 1.2.0)
+
+BUNDLED WITH
+   1.16.1

docs/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 CloudCannon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/_about/introduction.md

@@ -0,0 +1,19 @@
+---
+title:
+position: 1
+content_markdown: |-
+  fetch-mock allows mocking http requests made using [fetch](https://fetch.spec.whatwg.org/), or one of the many libraries imitating its api, such as [node-fetch](https://www.npmjs.com/package/node-fetch) or [fetch-ponyfill](https://www.npmjs.com/package/fetch-ponyfill).
+
+  It supports most JavaScript environments, including nodejs, web workers and service workers, and any browser that either supports fetch natively or that can have a fetch polyfill installed.
+
+  As well as shorthand methods for the simplest use cases, it offers a flexible API for customising all aspects of mocking behaviour.
+
+left_code_blocks:
+  - code_block: |-
+      fetchMock.mock('http://example.com', 200);
+      const res = await fetch('http://example.com');
+      assert(res.ok);
+      fetchMock.restore();
+    title: Example
+    language: javascript
+---

docs/_about/previous-versions.md

@@ -0,0 +1,9 @@
+---
+title: Previous versions
+position: 3
+content_markdown: |-
+  - [v7 upgrade guide](https://github.com/wheresrhys/fetch-mock/blob/master/docs/v6-v7-upgrade-guide.md)
+  - [v6 docs](https://github.com/wheresrhys/fetch-mock/tree/4231044aa94e234b53e296181ca5b6b4cecb6e3f/docs)
+  - [v5 docs](https://github.com/wheresrhys/fetch-mock/tree/b8270640d5711feffb01d1bf85bb7da95179c4de/docs)
+
+---

docs/_about/quickstart.md

@@ -0,0 +1,68 @@
+---
+title: Quickstart
+position: 2
+
+content_markdown: |-
+
+  #### Setting up your mock
+
+  - The commonest use case is `fetchMock.mock(matcher, response)`, where `matcher` is an exact url or regex to match, and `response` is a status code, string or object literal.
+  - You can also use `fetchMock.once()` to limit to a single call or `fetchMock.get()`, `fetchMock.post()` etc. to limit to a method.
+  - All these methods are chainable so you can easily define several mocks in a single test.
+
+  ```javascript
+  fetchMock
+    .get('http://good.com/', 200)
+    .post('http://good.com/', 400)
+    .get(/bad\.com/, 500)
+  ```
+  #### Analysing calls to your mock
+
+  - `fetchMock.called(matcher)` reports if any calls matched your mock (or leave `matcher` out if you just want to check `fetch` was called at all).
+  - `fetchMock.lastCall()`, `fetchMock.lastUrl()` or `fetchMock.lastOptions()` give you access to the parameters last passed in to `fetch`.
+  - `fetchMock.done()` will tell you if `fetch` was called the expected number of times.
+
+  #### Tearing down your mock
+
+  - `fetchMock.resetHistory()` resets the call history.
+  - `fetchMock.reset()` or `fetchMock.restore()` will also restore `fetch()` to its native implementation
+
+  #### Example
+
+  Example with node: suppose we have a file `make-request.js` with a function that calls `fetch`:
+
+  ```js
+  module.exports = function makeRequest() {
+    return fetch('http://httpbin.org/get').then(function(response) {
+      return response.json();
+    });
+  };
+  ```
+
+
+  We can use fetch-mock to mock `fetch`. In `mocked.js`:
+
+  ```js
+  var fetchMock = require('fetch-mock');
+  var makeRequest = require('./make-request');
+
+  // Mock the fetch() global to always return the same value for GET
+  // requests to all URLs.
+  fetchMock.get('*', { hello: 'world' });
+
+  makeRequest().then(function(data) {
+    console.log('got data', data);
+  });
+
+  // Unmock.
+  fetchMock.reset();
+  ```
+
+  Result:
+
+  ```bash
+  $ node mocked.js
+  'got data' { hello: 'world' }
+  ```
+
+---

docs/_api-inspection/called.md

@@ -0,0 +1,7 @@
+---
+title: .called(filter, options)
+navTitle: .called()
+position: 1
+description: |-
+  Returns a Boolean indicating whether any calls to `fetch` matched the given filter
+---

docs/_api-inspection/calls.md

@@ -0,0 +1,7 @@
+---
+title: .calls(filter, options)
+navTitle: .calls()
+position: 2
+description: |-
+  Returns an array of all calls to fetch matching the given filters. Each call is returned as a `[url, options]` array. If `fetch` was called using a `Request` instance, this will be available as a `request` property on this array.
+---

docs/_api-inspection/done.md

@@ -0,0 +1,10 @@
+---
+title: .done(filter, options)
+navTitle: .done()
+position: 6
+description: |-
+  Returns a Boolean indicating whether `fetch` was called the expected number of times (or has been called at least once if `repeat` is undefined for the route)
+content_markdown: |-
+  Unlike the other methods for inspecting calls, unmatched calls are irrelevant. If no `filter` is passed, `done()` returns `true` if every route has been called the number of expected times.
+  {: .warning}
+---

docs/_api-inspection/filtering.md

@@ -0,0 +1,47 @@
+---
+title: "Filtering basics"
+position: 0
+description: |-
+  Most inspection methods take two arguments — `filter` and `options` — which allow groups of fetch calls to be extracted and inspected.
+parameters:
+  - name: filter
+    types:
+      - String
+      - RegExp
+      - Function
+    content: |-
+      Enables filtering fetch calls for the most commonly use cases. The behaviour can be counterintuitive. The following rules, applied in the order they are described, are used to try to retrieve calls. If any rule retrieves no calls the next rule will be tried.
+    options:
+      - name: matcher
+        content: |-
+          If `options` is defined (it can even be an empty object), `filter` will be executed using the same execution plan as [matchers](#api-mockingmock_matcher). Any calls matched by it will be returned.
+        types:
+          - String
+          - RegExp
+          - Function
+      - types:
+        - undefined
+        content: |-
+          Retrieves all calls made to `fetch`, whether fetch-mock matched them or not
+      - types:
+        - true
+        content: |-
+          Retrieves all calls matched by `fetch`. `fetchMock.MATCHED` is an alias for `true` and may be used to make tests more readable
+      - types:
+        - false
+        content: |-
+          Retrieves all calls not matched by `fetch` (i.e. those handled by `catch()` or `spy()`. `fetchMock.UNMATCHED` is an alias for `false` and may be used to make tests more readable
+      - name: route
+        types:
+          - String
+        content: Retrieves calls handled by a named route (see [mocking options](#api-mockingmock_options). Failing that, a route whose matcher, when coerced to a string, is equal to the string provided
+      - name: asdkash d
+        content: Do I want to fallback to a matcher again?? Seems confusing as hell
+
+  - name: options
+    types:
+      - Object
+      - String
+    content: |-
+      Either an object compatible with the [mocking api](#api-mockingmock_options) or a string specifying a http `method` to filter by
+---

docs/_api-inspection/lastCall.md

@@ -0,0 +1,7 @@
+---
+title: .lastCall(filter, options)
+navTitle: .lastCall()
+position: 3
+description: |-
+  Returns the arguments for the last call to `fetch` matching the given filter
+---

docs/_api-inspection/lastOptions.md

@@ -0,0 +1,7 @@
+---
+title: .lastOptions(filter, options)
+navTitle: .lastOptions()
+position: 5
+description: |-
+  Returns the options for the call to `fetch` matching the given filter. If `fetch` was last called using a `Request` instance, a set of `options` inferred from the `Request` will be returned
+---

docs/_api-inspection/lastUrl.md

@@ -0,0 +1,7 @@
+---
+title: .lastUrl(filter, options)
+navTitle: .lastUrl()
+position: 4
+description: |-
+  Returns the url for the last call to `fetch` matching the given filter. If `fetch` was last called using a `Request` instance, the url will be extracted from this
+---

docs/_api-lifecycle/flush.md

@@ -0,0 +1,12 @@
+---
+title: .flush(waitForBody)
+navTitle: ".flush()"
+position: 2
+description: |-
+  Returns a `Promise` that resolves once all fetches handled by fetch-mock have resolved
+content_markdown: |-
+  Useful for testing code that uses `fetch` but doesn't return a promise.
+
+  Pass in `true` to wait for all body parsing methods (`res.json()`, `res.text()`, etc.) to resolve too.
+  {: .info}
+---

docs/_api-lifecycle/resetHistory.md

@@ -0,0 +1,6 @@
+---
+title: .resetHistory()
+position: 4
+description: |-
+  Clears all data recorded for `fetch()`'s calls. It _will not_ restore fetch to its default implementation
+---

docs/_api-lifecycle/restore_reset.md

@@ -0,0 +1,20 @@
+---
+title: .restore(), .reset()
+navTitle: .restore(), .reset()
+position: 3
+description: |-
+  Restores `fetch()` to its unstubbed state and clears all data recorded for its calls. `reset()` is an alias for `restore()`
+---
+
+#### ``
+
+Chainable method that .
+
+#### `resetHistory()`
+
+Chainable method that clears all data recorded for `fetch()`'s calls. _It will not restore fetch to its default implementation_
+
+_Note that `restore()`, `reset()` and `resetHistory()` are all bound to fetchMock, and can be used directly as callbacks e.g. `afterEach(fetchMock.reset)` will work just fine. There is no need for `afterEach(function () {fetchMock.reset()})`_
+
+#### `flush()`
+

docs/_api-lifecycle/sandbox.md

@@ -0,0 +1,14 @@
+---
+title: ".sandbox()"
+position: 1.0
+description: |-
+  Returns a drop-in mock for fetch which can be passed to other mocking libraries. It implements the full fetch-mock api and maintains its own state independent of other instances, so tests can be run in parallel.
+left_code_blocks:
+  - code_block: |-
+      fetchMock
+        .sandbox()
+        .mock('http://domain.com', 200)
+    title: Example
+    language: javascript
+
+---

docs/_api-mocking/_defaults.md

@@ -0,0 +1,16 @@
+---
+title: 
+position:
+parameters:
+  - name:
+    content:
+content_markdown:
+left_code_blocks:
+  - code_block:
+    title:
+    language:
+right_code_blocks:
+  - code_block:
+    title:
+    language:
+---

docs/_api-mocking/catch.md

@@ -0,0 +1,12 @@
+---
+title: ".catch(response)"
+navTitle: .catch()
+position: 5
+description: |-
+  Specifies how to respond to calls to `fetch` that don't match any mocks.
+parentMethodGroup: mocking
+content_markdown: |-
+  It accepts any valid [fetch-mock response](/#api-mockingmock_response), and can also take an arbitrary function to completely customise behaviour. If no argument is passed, then every unmatched call will receive a `200` response
+---
+
+