Add makeStub testing util (#459)

Author: dskloetc

src/util/testing-utils.ts

@@ -508,4 +508,71 @@ export const mockWebSocketProvider = (provider: typeof WebSocketClassProvider):
   // Need to disable typing, the mock-socket impl does not implement the ws interface fully
   provider.set(MockWebSocket as any) // eslint-disable-line @typescript-eslint/no-explicit-any
 }
+
+// Wraps an object such that accessing properties that do not exist will throw
+// an error instead of returning undefined.
+//
+// This is useful during unit test creation, as it makes it clear which
+// properties are missing rather than giving an error later on that undefined
+// doesn't have some other property.
+//
+// Once a test is passing, you can remove the wrapping and the test will still
+// pass. But it might be useful to keep it for when the code under test is
+// changed later on.
+//
+// Example usage:
+//
+// In code under test:
+//
+//   function doThing(obj) {
+//     const baz = obj.foo.baz
+//     ...
+//   }
+//
+// In test code:
+//
+//   const obj = makeStub('obj', { foo: { bar: 1 } })
+//   doThing(obj)
+//
+// Throws (and logs, in case the error is caught by the code under test):
+// Error: Property 'obj.foo.baz' does not exist
+export function makeStub<T>(name: string, obj: T): T {
+  if (obj === null || typeof obj !== 'object') {
+    return obj
+  }
+  return new Proxy(obj, {
+    get: (target, prop) => {
+      const propName = `${name}.${String(prop)}`
+      if (!(prop in target) && !isStubPropAllowedUndefined(prop)) {
+        const message = `Property '${propName}' does not exist`
+        // eslint-disable-next-line no-console
+        console.error(message)
+        throw new Error(message)
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return makeStub(propName, (target as any)[prop])
+    },
+  }) as T
+}
+
+// Properties checked by jest which don't need to be defined:
+export const allowedUndefinedStubProps = [
+  '$$typeof',
+  'nodeType',
+  'tagName',
+  'hasAttribute',
+  '@@__IMMUTABLE_ITERABLE__@@',
+  '@@__IMMUTABLE_RECORD__@@',
+  'toJSON',
+  'asymmetricMatch',
+  'then',
+]
+
+const isStubPropAllowedUndefined = (prop: string | symbol) => {
+  if (typeof prop === 'symbol') {
+    return true
+  }
+  return allowedUndefinedStubProps.includes(prop as string)
+}
+
 /* c8 ignore stop */ // eslint-disable-line

test/util/testing-utils.test.ts

@@ -0,0 +1,120 @@
+import test from 'ava'
+import { allowedUndefinedStubProps, makeStub } from '../../src/util/testing-utils'
+
+test('make a stub', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    count: 5,
+  })
+
+  t.is(stub.name, 'stub-name')
+  t.is(stub.count, 5)
+})
+
+test('make a stub with nested fields', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    nested: {
+      count: 5,
+    },
+  })
+
+  t.is(stub.name, 'stub-name')
+  t.is(stub.nested.count, 5)
+})
+
+test('accessing an absent field should throw an error', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    nested: {
+      count: 5,
+    },
+  })
+
+  t.throws(
+    () => {
+      // @ts-expect-error intended
+      t.is(stub.count, undefined)
+    },
+    {
+      message: "Property 'stub.count' does not exist",
+    },
+  )
+})
+
+test('accessing a nested absent field should throw an error', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    nested: {
+      count: 5,
+    },
+  })
+
+  t.throws(
+    () => {
+      // @ts-expect-error intended
+      t.is(stub.nested.name, undefined)
+    },
+    {
+      message: "Property 'stub.nested.name' does not exist",
+    },
+  )
+})
+
+test('fields used by jest are allowed to be undefined', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    count: 5,
+  })
+
+  // @ts-expect-error intended
+  t.is(stub.nodeType, undefined)
+  // @ts-expect-error intended
+  t.is(stub.tagName, undefined)
+})
+
+test('Symbol props are allowed to be undefined', async (t) => {
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    count: 5,
+  })
+
+  // @ts-expect-error intended
+  t.is(stub[Symbol('my symbol')], undefined)
+})
+
+test('allowedUndefinedStubProps can be extended and restored', async (t) => {
+  const customProp = 'myCustomProp'
+
+  const stub = makeStub('stub', {
+    name: 'stub-name',
+    count: 5,
+  })
+
+  t.throws(
+    () => {
+      // @ts-expect-error intended
+      t.is(stub[customProp], undefined)
+    },
+    {
+      message: "Property 'stub.myCustomProp' does not exist",
+    },
+  )
+
+  allowedUndefinedStubProps.push('myCustomProp')
+
+  // @ts-expect-error intended
+  t.is(stub[customProp], undefined)
+
+  allowedUndefinedStubProps.pop()
+
+  t.throws(
+    () => {
+      // @ts-expect-error intended
+      t.is(stub[customProp], undefined)
+    },
+    {
+      message: "Property 'stub.myCustomProp' does not exist",
+    },
+  )
+})