feat: Allow optionally() to be called with a value, specifying if the…

… mock should be optional

When setting up a mock, you can call `optionally()` to specify
that the mock is __optional__, meaning that it won't be
returned in `nock.pendingMocks()` and it won't affect the
result of `nock.isDone()`.

You have to call `optionally()` before you call a method like
`reply()` to specify the response, because at that point the
mock is persisted and you can no longer touch it (that is to
say, `reply()` returns the scope rather than the mock).

This part of Nock's API makes life painful if you want to
have a mock which is configurable as either optional or
required. The way that mocks are chained together makes
your code long-winded and hard to read:

```js
const getLoginMock = ({ optional = false }) => {
  const mock = nock('https://supercoolauthservice.com')
    .post('/login');

  if (optional) {
    mock = mock.optionally();
  }

  mock.reply(200);
}
```

This change makes life simpler, allowing you to specify
when you call `optionally()` whether you want the mock
to be optional or not:

```js
const getLoginMock = ({ optional = false }) => {
  nock('https://supercoolauthservice.com')
    .post('/login')
    .optionally(optional)
    .reply(200);
}
```

README.md

@@ -840,6 +840,19 @@ example.pendingMocks() // []
 
 example.get("/pathB").optionally().reply(200);
 example.pendingMocks() // []
+
+// You can also pass a boolean argument to `optionally()`. This
+// is useful if you want to conditionally make a mocked request
+// optional.
+var getMock = function(optional) {
+  return example.get("/pathC").optionally(optional).reply(200);
+}
+
+getMock(true);
+example.pendingMocks() // []
+getMock(false);
+example.pendingMocks() // ["GET http://example.com:80/pathC"]
+
 ```
 
 ### Allow __unmocked__ requests on a mocked hostname

lib/interceptor.js

@@ -43,8 +43,12 @@ function Interceptor(scope, uri, method, requestBody, interceptorOptions) {
     this.optional = false;
 }
 
-Interceptor.prototype.optionally = function optionally() {
-    this.optional = true;
+Interceptor.prototype.optionally = function optionally(value) {
+    // The default behaviour of optionally() with no arguments is to make the mock optional.
+    value = (typeof value === 'undefined') ? true : value;
+
+    this.optional = value;
+
     return this;
 }
 

tests/test_intercept.js

@@ -2414,6 +2414,27 @@ test('pending mocks doesn\'t include optional mocks', function(t) {
   t.end();
 });
 
+test('calling optionally(true) on a mock makes it optional', function (t) {
+  nock('http://example.com')
+    .get('/nonexistent')
+    .optionally(true)
+    .reply(200);
+
+  t.deepEqual(nock.pendingMocks(), []);
+  t.end();
+});
+
+test('calling optionally(false) on a mock leaves it as required', function(t) {
+  nock('http://example.com')
+    .get('/nonexistent')
+    .optionally(false)
+    .reply(200);
+
+  t.notEqual(nock.pendingMocks(), []);
+  nock.cleanAll();
+  t.end();
+});
+
 test('optional mocks are still functional', function(t) {
   nock('http://example.com')
     .get('/abc')