feat: Add conditionally() (#1488)

I am building a test framework which depends on nock and to support concurrency, I need to be able shutoff certain scopes (to prevent cross-pollination) when running tests concurrently.

README.md

@@ -757,6 +757,18 @@ const scope = nock('https://api.dropbox.com', {
   .reply(200)
 ```
 
+### Conditional scope filtering
+
+You can also choose to filter out a scope based on your system environment (or any external factor). The filtering function is accepted at the `conditionally` field of the `options` argument.
+
+This can be useful if you only want certain scopes to apply depending on how your tests are executed.
+
+```js
+const scope = nock('https://api.myservice.com', {
+  conditionally: () => true,
+})
+```
+
 ### Path filtering
 
 You can also filter the URLs based on a function.

lib/interceptor.js

@@ -254,6 +254,14 @@ Interceptor.prototype.match = function match(options, body, hostNameOnly) {
     return false
   }
 
+  if (
+    this.scope.scopeOptions &&
+    this.scope.scopeOptions.conditionally &&
+    !this.scope.scopeOptions.conditionally()
+  ) {
+    return false
+  }
+
   function reqheaderContains(header) {
     return _.has(options.headers, header)
   }

tests/test_intercept.js

@@ -8,6 +8,7 @@ const mikealRequest = require('request')
 const superagent = require('superagent')
 const needle = require('needle')
 const restify = require('restify-clients')
+const assertRejects = require('assert-rejects')
 const hyperquest = require('hyperquest')
 const got = require('got')
 const nock = require('..')
@@ -1228,6 +1229,36 @@ test('test request timeout option', t => {
   })
 })
 
+test('do not match when conditionally = false but should match after trying again when = true', async t => {
+  t.plan(2)
+  let enabled = false
+
+  const scope = nock('http://example.test', {
+    conditionally: function() {
+      return enabled
+    },
+  })
+    .get('/')
+    .reply(200)
+
+  // now the scope has been used, should fail on second try
+  await assertRejects(
+    got('http://example.test/'),
+    Error,
+    'Nock: No match for request'
+  )
+  t.throws(() => scope.done(), {
+    message: 'Mocks not yet satisfied',
+  })
+
+  enabled = true
+
+  const { statusCode } = await got('http://example.test/')
+
+  t.equal(statusCode, 200)
+  scope.done()
+})
+
 test('get correct filtering with scope and request headers filtering', t => {
   const responseText = 'OK!'
   const responseHeaders = { 'Content-Type': 'text/plain' }