feat: add context.query() to nock back (#2553)

README.md

@@ -1497,6 +1497,45 @@ To set the mode call `nockBack.setMode(mode)` or run the tests with the `NOCK_BA
 
 - lockdown: use recorded nocks, disables all http calls even when not nocked, doesn't record
 
+### Verifying recorded fixtures
+
+Although you can certainly open the recorded JSON fixtures to manually verify requests recorded by nockBack - it's sometimes useful to put those expectations in your tests.
+
+The `context.query` function can be used to return all of the interceptors that were recored in a given fixture.
+
+By itself, this functions as a negative expectation - you can verify that certain calls do NOT happen in the fixture. Since `assertScopesFinished` can verify there are no _extra_ calls in a fixture - pairing the two methods allows you to verify the exact set of HTTP interactions recorded in the fixture. This is especially useful when re-recording for instance, a service that synchronizes via several HTTP calls to an external API.
+
+**NB**: The list of fixtures is only available when reading. It will only be populated for nocks that are played back from fixtures.
+
+#### Example
+
+```js
+it('#synchronize - synchronize with the external API', async localState => {
+  const { nockDone, context } = await back('http-interaction.json')
+
+  const syncronizer = new Synchronizer(localState)
+
+  sycnronizer.syncronize()
+
+  nockDone()
+
+  context.assertScopesFinished()
+
+  expect(context.query()).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        method: 'POST',
+        path: '/create/thing',
+      }),
+      expect.objectContaining({
+        method: 'POST',
+        path: 'create/thing',
+      }),
+    ]),
+  )
+})
+```
+
 ## Common issues
 
 **"No match for response" when using got with error responses**

lib/back.js

@@ -240,6 +240,23 @@ function load(fixture, options) {
     assertScopesFinished: function () {
       assertScopes(this.scopes, fixture)
     },
+    query: function () {
+      const nested = this.scopes.map(scope =>
+        scope.interceptors.map(interceptor => ({
+          method: interceptor.method,
+          uri: interceptor.uri,
+          basePath: interceptor.basePath,
+          path: interceptor.path,
+          queries: interceptor.queries,
+          counter: interceptor.counter,
+          body: interceptor.body,
+          statusCode: interceptor.statusCode,
+          optional: interceptor.optional,
+        })),
+      )
+
+      return [].concat.apply([], nested)
+    },
   }
 
   if (fixture && fixtureExists(fixture)) {

tests/test_back.js

@@ -147,6 +147,24 @@ describe('Nock Back', () => {
     })
   })
 
+  it('`query` returns all of the interceptors recorded to the cassette', done => {
+    nockBack('good_request.json').then(({ nockDone, context }) => {
+      const interceptor = context.query()
+      nockDone()
+      expect(interceptor.length).to.equal(1)
+      expect(interceptor[0].method).to.equal('GET')
+      expect(interceptor[0].uri).to.equal('/')
+      expect(interceptor[0].basePath).to.equal('http://www.example.test:80')
+      expect(interceptor[0].path).to.equal('/')
+      expect(interceptor[0].queries).to.be.null()
+      expect(interceptor[0].counter).to.equal(1)
+      expect(interceptor[0]).to.have.property('body')
+      expect(interceptor[0].statusCode).to.equal(200)
+      expect(interceptor[0].optional).to.equal(false)
+      done()
+    })
+  })
+
   describe('wild mode', () => {
     beforeEach(() => {
       nockBack.setMode('wild')

types/index.d.ts

@@ -267,10 +267,23 @@ declare namespace nock {
     }>
   }
 
+  interface InterceptorSurface {
+    method: string
+    uri: string
+    basePath: string
+    path: string
+    queries?: string
+    counter: number
+    body: string
+    statusCode: number
+    optional: boolean
+  }
+
   interface BackContext {
     isLoaded: boolean
     scopes: Scope[]
     assertScopesFinished(): void
+    query: InterceptorSurface[]
   }
 
   interface BackOptions {