@znight/testing 0.0.0-stage → 0.1.1

package/src/mock-registry.ts

@@ -0,0 +1,118 @@
+import type { ClassKey, Token, TypedToken } from '@znight/core'
+import type { MetadataIndex } from './metadata-index.ts'
+import type { DeepMock, Mocked } from './types.ts'
+
+import { describeToken, displayName, ErrorCode, ZnightError } from '@znight/core'
+
+import { clearMock, resetMock } from './mock.ts'
+import { describeKey } from './utils.ts'
+
+/**
+ * The auto-mocks of a `TestBed`, looked up by class, token, alias or display name.
+ *
+ * ```ts
+ * const { instance, mocks } = await TestBed.create(UserService, { metadata })
+ * mocks.get(UserRepository).findById.mockResolvedValue(user) // typed
+ * mocks.get('Logger').info // untyped deep mock
+ * ```
+ */
+export interface MockRegistry {
+  /**
+   * The auto-mock injected for `key`: a class (typed result), a token, an alias (interface, base
+   * class) or a unique display name (`'UserRepository'`).
+   *
+   * @throws ZnightError ZNIGHT001 when no auto-mock matches (the message says why: provided value,
+   *   configuration class, optional dependency...), ZNIGHT008 when a display name is ambiguous.
+   */
+  get<T>(key: ClassKey<T>): Mocked<T>
+  get<T = never>(key: TypedToken<T>): [T] extends [never] ? DeepMock : Mocked<T>
+  /** Whether an auto-mock matches `key`. */
+  has(key: ClassKey | Token): boolean
+  /** Tokens of the auto-mocked dependencies, in injection order. */
+  tokens(): Token[]
+  /** `mockClear()` on every spy of every auto-mock (recorded calls are forgotten). */
+  clearAll(): void
+  /** Resets every auto-mock to its initial state (calls and programmed behaviours are forgotten). */
+  resetAll(): void
+}
+
+/** Why a dependency was not auto-mocked (used in error messages). */
+export type InjectionKind = 'provided' | 'override' | 'config' | 'optional' | 'interceptor' | 'real'
+
+const REASONS: Readonly<Record<InjectionKind, string>> = {
+  provided: 'its value was passed with `provide`',
+  override: 'it was replaced with `overrides`',
+  config: 'it is a configuration class (a real instance is injected; set values with `config`)',
+  optional: 'it is an optional dependency (`undefined` is injected unless provided)',
+  interceptor: 'it is an interceptor (not applied unless `aop: "real"`)',
+  real: 'it was built for real (aop: "real")',
+}
+
+/** Default {@link MockRegistry} implementation (internal). */
+export class TestMocks implements MockRegistry {
+  readonly #mocks: ReadonlyMap<Token, object>
+  readonly #others: ReadonlyMap<Token, InjectionKind>
+  readonly #index: MetadataIndex
+  readonly #owner: Token
+
+  constructor(
+    mocks: ReadonlyMap<Token, object>,
+    others: ReadonlyMap<Token, InjectionKind>,
+    index: MetadataIndex,
+    owner: Token,
+  ) {
+    this.#mocks = mocks
+    this.#others = others
+    this.#index = index
+    this.#owner = owner
+  }
+
+  get<T>(key: ClassKey<T>): Mocked<T>
+  get<T = never>(key: TypedToken<T>): [T] extends [never] ? DeepMock : Mocked<T>
+  get(key: unknown): unknown {
+    const token = this.#index.find(key, new Set(this.#mocks.keys()))
+    if (token !== undefined) return this.#mocks.get(token)
+    throw this.#notMockedError(key)
+  }
+
+  has(key: ClassKey | Token): boolean {
+    return this.#index.find(key, new Set(this.#mocks.keys())) !== undefined
+  }
+
+  tokens(): Token[] {
+    return [...this.#mocks.keys()]
+  }
+
+  clearAll(): void {
+    for (const mock of this.#mocks.values()) clearMock(mock)
+  }
+
+  resetAll(): void {
+    for (const mock of this.#mocks.values()) resetMock(mock)
+  }
+
+  #notMockedError(key: unknown): ZnightError {
+    const owner = displayName(this.#owner)
+    let other: Token | undefined
+    try {
+      other = this.#index.find(key, new Set(this.#others.keys()))
+    } catch {
+      other = undefined
+    }
+    if (other !== undefined) {
+      const kind = this.#others.get(other) as InjectionKind
+      return new ZnightError(ErrorCode.MissingProvider, `${describeToken(other)} is not mocked: ${REASONS[kind]}`)
+    }
+    const mocked = [...this.#mocks.keys()].map(displayName)
+    return new ZnightError(
+      ErrorCode.MissingProvider,
+      `No mock for ${describeKey(key)}: it is not a direct dependency of ${owner}`,
+      {
+        hints: [
+          mocked.length === 0 ? `${owner} has no auto-mocked dependency` : `Auto-mocked: ${mocked.join(', ')}`,
+          'TestBed only mocks direct dependencies; regenerate the metadata if the constructor changed',
+        ],
+      },
+    )
+  }
+}

package/src/mock.ts

@@ -0,0 +1,270 @@
+import type { ClassKey } from '@znight/core'
+import type { AnyFunction, DeepMock, Mocked, MockFnFactory, MockFnOption } from './types.ts'
+
+import { resolveMockFn } from './mock-fn.ts'
+
+/** Options of {@link createMock}. */
+export interface CreateMockOptions {
+  /**
+   * Name of the mock, used to name its spies in assertion messages (`UserRepository.findById`).
+   * Default: the class name, or `mock`.
+   */
+  readonly name?: string
+  /**
+   * When `true`, calling an unconfigured method returns a deep mock (the same one for every call)
+   * instead of `undefined`, so fluent APIs work: `db.select().from('users')`. Default: `false`.
+   */
+  readonly deep?: boolean
+  /** Spy implementation. Default: auto-detected (see `MockFnOption`). */
+  readonly mockFn?: MockFnOption
+}
+
+/** Shared state of a mock and every spy created under it. */
+interface MockTree {
+  readonly create: MockFnFactory
+  readonly deep: boolean
+  readonly spies: SpyRecord[]
+}
+
+interface SpyRecord {
+  readonly spy: SpyLike
+  readonly implementation: AnyFunction | undefined
+}
+
+interface SpyLike {
+  (...args: unknown[]): unknown
+  mockName?: (name: string) => unknown
+  mockClear?: () => unknown
+  mockReset?: () => unknown
+  mockImplementation?: (implementation: AnyFunction) => unknown
+}
+
+/**
+ * Property names never auto-mocked (they read as `undefined` unless set explicitly). Libraries probe
+ * them to detect promises (`then`), JSON values (`toJSON`), asymmetric matchers (`asymmetricMatch`),
+ * React elements (`$$typeof`), DOM nodes (`nodeType`, `tagName`), ES module namespaces
+ * (`__esModule`) or mock functions (`_isMockFunction`). Names starting with `@@` (Immutable.js
+ * sentinels) are reserved too. Symbol-keyed properties are never auto-mocked.
+ */
+const RESERVED: ReadonlySet<string> = new Set([
+  'then',
+  'toJSON',
+  'asymmetricMatch',
+  '$$typeof',
+  'nodeType',
+  'tagName',
+  '__esModule',
+  '_isMockFunction',
+])
+
+const TREE: unique symbol = Symbol('znight.mock')
+
+const mocks = new WeakSet<object>()
+
+function isReserved(key: string): boolean {
+  return RESERVED.has(key) || key.startsWith('@@')
+}
+
+/**
+ * Creates a deep auto-mock.
+ *
+ * - Every property read returns a spy (`MockFunction`), created on first access and then stable.
+ *   Spies are deep too: `mock.pool.query.mockResolvedValue(rows)`.
+ * - Unconfigured spies return `undefined` (or a deep mock with `{ deep: true }`).
+ * - The mock is **not thenable** and inert for serialisers: `then`, `toJSON`, `asymmetricMatch`,
+ *   `$$typeof`, `Symbol.toPrimitive`... read as `undefined`, so `await mock`, `JSON.stringify(mock)`
+ *   and `expect(...).toEqual(mock)` behave.
+ * - Assigned properties win: `mock.enabled = false`.
+ * - With a class, the mock inherits its prototype (`instanceof` works) and getters read as
+ *   `undefined` instead of a (truthy) spy.
+ * - Functions of `partial` become spies with that implementation; other values are set as is.
+ *
+ * ```ts
+ * const repository = createMock(UserRepository, { findById: async id => ({ id }) })
+ * const logger = createMock<Logger>()
+ * logger.info('hello')
+ * expect(logger.info).toHaveBeenCalledWith('hello')
+ * ```
+ */
+export function createMock<T>(cls: ClassKey<T>, partial?: Partial<T>, options?: CreateMockOptions): Mocked<T>
+export function createMock<T = never>(
+  partial?: Partial<T>,
+  options?: CreateMockOptions,
+): [T] extends [never] ? DeepMock : Mocked<T>
+export function createMock(first?: unknown, second?: unknown, third?: unknown): unknown {
+  if (typeof first === 'function') {
+    return mockObject(first as ClassKey<unknown>, second as object | undefined, third as CreateMockOptions | undefined)
+  }
+  return mockObject(undefined, first as object | undefined, second as CreateMockOptions | undefined)
+}
+
+/** {@link createMock} with an optional class (internal). */
+export function mockObject(
+  cls: ClassKey<unknown> | undefined,
+  partial: object | undefined,
+  options: CreateMockOptions = {},
+): object {
+  if (partial !== undefined && (partial === null || typeof partial !== 'object')) {
+    throw new TypeError('[znight] createMock(): the partial implementation must be an object')
+  }
+  const tree: MockTree = {
+    create: resolveMockFn(options.mockFn).create,
+    deep: options.deep === true,
+    spies: [],
+  }
+  const className = typeof cls === 'function' ? (cls as { name?: unknown }).name : undefined
+  const name = options.name ?? (typeof className === 'string' && className !== '' ? className : 'mock')
+  return createNode(name, tree, cls, partial)
+}
+
+/** Whether `value` is a mock (or one of its spies) created by {@link createMock}. */
+export function isMock(value: unknown): boolean {
+  return value !== null && (typeof value === 'object' || typeof value === 'function') && mocks.has(value)
+}
+
+/** Forgets the calls recorded by every spy of `mock` (`mockClear()`); implementations are kept. */
+export function clearMock(mock: object): void {
+  for (const { spy } of treeOf(mock, 'clearMock').spies) spy.mockClear?.()
+}
+
+/**
+ * Resets every spy of `mock` to its initial state: recorded calls and programmed implementations
+ * are forgotten, implementations given to {@link createMock} (and deep returns) are restored.
+ */
+export function resetMock(mock: object): void {
+  for (const { spy, implementation } of treeOf(mock, 'resetMock').spies) {
+    spy.mockReset?.()
+    if (implementation !== undefined) spy.mockImplementation?.(implementation)
+  }
+}
+
+function treeOf(mock: object, where: string): MockTree {
+  const tree = isMock(mock) ? (mock as { [TREE]?: MockTree })[TREE] : undefined
+  if (tree === undefined) throw new TypeError(`[znight] ${where}(): expected a mock created by createMock()`)
+  return tree
+}
+
+/** An object mock (the root of a mock, or the value returned by a deep spy). */
+function createNode(
+  name: string,
+  tree: MockTree,
+  cls: ClassKey<unknown> | undefined,
+  partial: object | undefined,
+): object {
+  const target: Record<PropertyKey, unknown> = Object.create(
+    typeof cls === 'function' && isObjectLike(cls.prototype) ? (cls.prototype as object) : Object.prototype,
+  )
+  const accessors = typeof cls === 'function' ? accessorKeys(cls.prototype) : undefined
+  const children = new Map<string, unknown>()
+  if (partial !== undefined) {
+    for (const key of Reflect.ownKeys(partial)) {
+      const value = (partial as Record<PropertyKey, unknown>)[key]
+      if (typeof key === 'string' && typeof value === 'function') {
+        children.set(key, createSpyNode(`${name}.${key}`, tree, value as AnyFunction))
+      } else {
+        defineValue(target, key, value)
+      }
+    }
+  }
+  const proxy: object = new Proxy(target, {
+    get(object, key, receiver): unknown {
+      if (typeof key === 'symbol') {
+        if (key === TREE) return tree
+        return Object.hasOwn(object, key) ? object[key] : undefined
+      }
+      if (Object.hasOwn(object, key)) return object[key]
+      if (key === 'constructor') return Reflect.get(object, key, receiver)
+      if (isReserved(key)) return undefined
+      if (Object.hasOwn(Object.prototype, key)) return Reflect.get(Object.prototype, key, receiver)
+      if (accessors?.has(key) === true) return undefined
+      let child = children.get(key)
+      if (child === undefined) {
+        child = createSpyNode(`${name}.${key}`, tree, undefined)
+        children.set(key, child)
+      }
+      return child
+    },
+    set(object, key, value): boolean {
+      defineValue(object, key, value)
+      return true
+    },
+    deleteProperty(object, key): boolean {
+      if (typeof key === 'string') children.delete(key)
+      return Reflect.deleteProperty(object, key)
+    },
+  })
+  mocks.add(proxy)
+  return proxy
+}
+
+/** A spy whose unknown properties are deep spies (`spy.nested.method`). */
+function createSpyNode(path: string, tree: MockTree, implementation: AnyFunction | undefined): SpyLike {
+  const effective = implementation ?? (tree.deep ? deepReturn(path, tree) : undefined)
+  const spy = tree.create(effective) as SpyLike
+  if (typeof spy !== 'function') {
+    throw new TypeError(`[znight] The mockFn factory returned ${typeof spy} instead of a function`)
+  }
+  if (typeof spy.mockName === 'function') spy.mockName(path)
+  makeDeep(spy, path, tree)
+  tree.spies.push({ spy, implementation: effective })
+  mocks.add(spy)
+  return spy
+}
+
+/** The implementation of a deep spy: returns the same deep mock on every call. */
+function deepReturn(path: string, tree: MockTree): AnyFunction {
+  let result: object | undefined
+  return () => {
+    result ??= createNode(`${path}()`, tree, undefined, undefined)
+    return result
+  }
+}
+
+/**
+ * Inserts a proxy between `spy` and its prototype: reading a property the spy does not have (own or
+ * inherited) creates a child spy. The spy itself stays a genuine spy of its framework, which
+ * `bun:test`'s `expect` requires (it rejects proxies).
+ */
+function makeDeep(spy: SpyLike, path: string, tree: MockTree): void {
+  const original: unknown = Object.getPrototypeOf(spy)
+  if (!isObjectLike(original)) return
+  const children = new Map<string, SpyLike>()
+  const prototype = new Proxy(original as object, {
+    get(object, key, receiver): unknown {
+      if (typeof key === 'symbol' || key in object || isReserved(key)) return Reflect.get(object, key, receiver)
+      let child = children.get(key)
+      if (child === undefined) {
+        child = createSpyNode(`${path}.${key}`, tree, undefined)
+        children.set(key, child)
+      }
+      return child
+    },
+  })
+  try {
+    Object.setPrototypeOf(spy, prototype)
+  } catch {
+    // a frozen or exotic spy: it keeps working, without deep members
+  }
+}
+
+function defineValue(object: object, key: PropertyKey, value: unknown): void {
+  Object.defineProperty(object, key, { value, writable: true, enumerable: true, configurable: true })
+}
+
+/** Names of the accessors (getters/setters) declared along a prototype chain, `Object.prototype` excluded. */
+function accessorKeys(prototype: unknown): ReadonlySet<string> {
+  const keys = new Set<string>()
+  let current: unknown = prototype
+  while (isObjectLike(current) && current !== Object.prototype && current !== Function.prototype) {
+    for (const key of Object.getOwnPropertyNames(current)) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key)
+      if (descriptor !== undefined && (descriptor.get !== undefined || descriptor.set !== undefined)) keys.add(key)
+    }
+    current = Object.getPrototypeOf(current)
+  }
+  return keys
+}
+
+function isObjectLike(value: unknown): value is object {
+  return value !== null && (typeof value === 'object' || typeof value === 'function')
+}

package/src/overrides.ts

@@ -0,0 +1,54 @@
+import type { DependencyRef, ProviderDefinition, ProviderFactory, ProviderKey, Scope } from '@znight/core'
+
+/** A typed `[key, value]` entry for `overrides` / `providers` / `provide`. */
+export type OverrideEntry<T = unknown> = readonly [ProviderKey<T>, T]
+
+/** A `[key, definition]` entry replacing a provider with a factory. */
+export type OverrideDefinitionEntry<T = unknown> = readonly [ProviderKey<T>, ProviderDefinition<T>]
+
+/**
+ * A type-checked override: the value must match the type designated by the class or typed token.
+ *
+ * ```ts
+ * await TestApp.create({ metadata, overrides: [override(UserRepository, new InMemoryUserRepository())] })
+ * ```
+ */
+export function override<T>(key: ProviderKey<T>, value: NoInfer<T>): OverrideEntry<T> {
+  return [key, value]
+}
+
+/** Options of {@link overrideFactory}. */
+export interface OverrideFactoryOptions {
+  /** Tokens resolved and passed to the factory, in order. Default: none. */
+  readonly deps?: readonly DependencyRef[]
+  /** Default: `'singleton'`. */
+  readonly scope?: Scope
+  /** Set when the factory returns a promise (singletons only). */
+  readonly async?: boolean
+  /** Method called when the instance is disposed. */
+  readonly dispose?: string
+}
+
+/**
+ * Replaces a provider with a factory whose dependencies are resolved by the container (or, in
+ * `TestBed`, like the target's dependencies).
+ *
+ * ```ts
+ * overrideFactory(UserRepository, ([db]) => new InMemoryUserRepository(db), { deps: ['src/db.ts#Database'] })
+ * ```
+ */
+export function overrideFactory<T>(
+  key: ProviderKey<T>,
+  factory: ProviderFactory<NoInfer<T>>,
+  options: OverrideFactoryOptions = {},
+): OverrideDefinitionEntry<T> {
+  if (typeof factory !== 'function') throw new TypeError('[znight] overrideFactory() expects a factory function')
+  const definition: ProviderDefinition<T> = {
+    scope: options.scope ?? 'singleton',
+    deps: options.deps ?? [],
+    factory,
+    ...(options.async === undefined ? {} : { async: options.async }),
+    ...(options.dispose === undefined ? {} : { dispose: options.dispose }),
+  }
+  return [key, definition]
+}

package/src/spy.ts

@@ -0,0 +1,246 @@
+import type { AnyFunction, MockFunction, UntypedFunction } from './types.ts'
+
+type Implementation = (this: unknown, ...args: unknown[]) => unknown
+
+interface MutableResult {
+  type: 'return' | 'throw' | 'incomplete'
+  value: unknown
+}
+
+interface MutableState {
+  readonly calls: unknown[][]
+  readonly results: MutableResult[]
+  readonly instances: unknown[]
+  readonly contexts: unknown[]
+  readonly invocationCallOrder: number[]
+  readonly lastCall: unknown[] | undefined
+}
+
+interface SpyInternals {
+  name: string
+  implementation: Implementation | undefined
+  readonly initial: Implementation | undefined
+  readonly once: Implementation[]
+  readonly state: MutableState
+}
+
+const DEFAULT_NAME = 'spy'
+
+/** Global call counter shared by every built-in spy (`mock.invocationCallOrder`). */
+let callOrder = 0
+
+const internalsBySpy = new WeakMap<object, SpyInternals>()
+
+function internalsOf(spy: unknown): SpyInternals {
+  const internals = typeof spy === 'function' ? internalsBySpy.get(spy) : undefined
+  if (internals === undefined) throw new TypeError('[znight] Not a spy created by createSpy()')
+  return internals
+}
+
+function createState(): MutableState {
+  const calls: unknown[][] = []
+  return {
+    calls,
+    results: [],
+    instances: [],
+    contexts: [],
+    invocationCallOrder: [],
+    get lastCall(): unknown[] | undefined {
+      return calls[calls.length - 1]
+    },
+  }
+}
+
+function clearState(state: MutableState): void {
+  state.calls.length = 0
+  state.results.length = 0
+  state.instances.length = 0
+  state.contexts.length = 0
+  state.invocationCallOrder.length = 0
+}
+
+function isObjectLike(value: unknown): boolean {
+  return value !== null && (typeof value === 'object' || typeof value === 'function')
+}
+
+function invoke(internals: SpyInternals, self: unknown, args: unknown[], isNew: boolean): unknown {
+  const state = internals.state
+  state.calls.push(args)
+  state.contexts.push(self)
+  state.instances.push(self)
+  state.invocationCallOrder.push(++callOrder)
+  const result: MutableResult = { type: 'incomplete', value: undefined }
+  state.results.push(result)
+  const implementation = internals.once.shift() ?? internals.implementation
+  try {
+    const value = implementation === undefined ? undefined : implementation.apply(self, args)
+    const returned = isNew && !isObjectLike(value) ? self : value
+    result.type = 'return'
+    result.value = returned
+    return returned
+  } catch (error) {
+    result.type = 'throw'
+    result.value = error
+    throw error
+  }
+}
+
+function returning(value: unknown): Implementation {
+  return () => value
+}
+
+function resolving(value: unknown): Implementation {
+  return () => Promise.resolve(value)
+}
+
+function rejecting(error: unknown): Implementation {
+  return () => Promise.reject(error)
+}
+
+function returnThis(this: unknown): unknown {
+  return this
+}
+
+/** Methods shared by every built-in spy (the prototype of the spy functions). */
+const spyPrototype: object = Object.create(Function.prototype, {
+  _isMockFunction: { value: true },
+  mock: {
+    get(this: unknown): MutableState {
+      return internalsOf(this).state
+    },
+  },
+  mockImplementation: {
+    value(this: unknown, implementation: Implementation): unknown {
+      internalsOf(this).implementation = implementation
+      return this
+    },
+  },
+  mockImplementationOnce: {
+    value(this: unknown, implementation: Implementation): unknown {
+      internalsOf(this).once.push(implementation)
+      return this
+    },
+  },
+  mockReturnValue: {
+    value(this: unknown, value: unknown): unknown {
+      internalsOf(this).implementation = returning(value)
+      return this
+    },
+  },
+  mockReturnValueOnce: {
+    value(this: unknown, value: unknown): unknown {
+      internalsOf(this).once.push(returning(value))
+      return this
+    },
+  },
+  mockResolvedValue: {
+    value(this: unknown, value: unknown): unknown {
+      internalsOf(this).implementation = resolving(value)
+      return this
+    },
+  },
+  mockResolvedValueOnce: {
+    value(this: unknown, value: unknown): unknown {
+      internalsOf(this).once.push(resolving(value))
+      return this
+    },
+  },
+  mockRejectedValue: {
+    value(this: unknown, error: unknown): unknown {
+      internalsOf(this).implementation = rejecting(error)
+      return this
+    },
+  },
+  mockRejectedValueOnce: {
+    value(this: unknown, error: unknown): unknown {
+      internalsOf(this).once.push(rejecting(error))
+      return this
+    },
+  },
+  mockReturnThis: {
+    value(this: unknown): unknown {
+      internalsOf(this).implementation = returnThis
+      return this
+    },
+  },
+  mockName: {
+    value(this: unknown, name: string): unknown {
+      internalsOf(this).name = String(name)
+      return this
+    },
+  },
+  getMockName: {
+    value(this: unknown): string {
+      return internalsOf(this).name
+    },
+  },
+  getMockImplementation: {
+    value(this: unknown): Implementation | undefined {
+      return internalsOf(this).implementation
+    },
+  },
+  mockClear: {
+    value(this: unknown): unknown {
+      clearState(internalsOf(this).state)
+      return this
+    },
+  },
+  mockReset: {
+    value(this: unknown): unknown {
+      const internals = internalsOf(this)
+      clearState(internals.state)
+      internals.once.length = 0
+      internals.implementation = internals.initial
+      return this
+    },
+  },
+  mockRestore: {
+    value(this: unknown): void {
+      const internals = internalsOf(this)
+      clearState(internals.state)
+      internals.once.length = 0
+      internals.implementation = internals.initial
+    },
+  },
+})
+
+/**
+ * Creates the built-in, dependency-free, Jest-compatible spy. It records `mock.calls`,
+ * `mock.results`, `mock.instances`, `mock.contexts`, `mock.invocationCallOrder` and `mock.lastCall`,
+ * supports `mockReturnValue(Once)`, `mockResolvedValue(Once)`, `mockRejectedValue(Once)`,
+ * `mockImplementation(Once)`, `mockReturnThis`, `mockName`, `mockClear`, `mockReset` and
+ * `mockRestore`, and is recognised by Jest's and Vitest's `expect` (`_isMockFunction`).
+ *
+ * `mockReset()` restores the implementation given to `createSpy()` (Vitest semantics).
+ *
+ * ```ts
+ * const find = createSpy((id: string) => ({ id }))
+ * find.mockReturnValueOnce({ id: 'x' })
+ * find('1')
+ * find.mock.calls // [['1']]
+ * ```
+ */
+export function createSpy<F extends AnyFunction = UntypedFunction>(implementation?: F): MockFunction<F> {
+  if (implementation !== undefined && typeof implementation !== 'function') {
+    throw new TypeError('[znight] createSpy() expects a function implementation')
+  }
+  const initial = implementation as Implementation | undefined
+  const internals: SpyInternals = {
+    name: DEFAULT_NAME,
+    implementation: initial,
+    initial,
+    once: [],
+    state: createState(),
+  }
+  const spy = function (this: unknown, ...args: unknown[]): unknown {
+    return invoke(internals, this, args, new.target !== undefined)
+  }
+  Object.setPrototypeOf(spy, spyPrototype)
+  internalsBySpy.set(spy, internals)
+  return spy as unknown as MockFunction<F>
+}
+
+/** Whether `value` is a spy created by {@link createSpy}. */
+export function isBuiltinSpy(value: unknown): boolean {
+  return typeof value === 'function' && internalsBySpy.has(value)
+}