@znight/testing 0.0.0-stage → 0.1.0

package/src/define-metadata.ts

@@ -0,0 +1,255 @@
+import type {
+  ClassKey,
+  DependencyRef,
+  ExternalDefinition,
+  MethodInterception,
+  ProviderClass,
+  ProviderDefinition,
+  ProviderFactory,
+  Scope,
+  SourceLocation,
+  Token,
+  ZnightExtensionsMetadata,
+  ZnightMetadata,
+} from '@znight/core'
+
+import { describeToken, ErrorCode, isProviderDefinition, METADATA_VERSION, ZnightError } from '@znight/core'
+
+import { entriesOf } from './utils.ts'
+
+/** Options of {@link createMetadata}. */
+export interface CreateMetadataOptions {
+  readonly aliases?: Readonly<Record<Token, Token>>
+  /** Externals, as tokens or full definitions (`{ token, scope, providedBy }`). */
+  readonly externals?: readonly (Token | ExternalDefinition)[]
+  readonly extensions?: ZnightExtensionsMetadata
+  /** Default: a deterministic topological order (dependencies first, declaration order otherwise). */
+  readonly resolutionOrder?: readonly Token[]
+}
+
+/**
+ * Hand-written metadata with the exact shape the compiler generates (version, resolution order...),
+ * for tests that do not run the compiler (plugins, libraries, edge cases).
+ *
+ * ```ts
+ * const metadata = createMetadata({
+ *   'src/clock.ts#Clock': { scope: 'singleton', class: Clock, deps: [], factory: () => new Clock() },
+ * })
+ * ```
+ *
+ * @throws ZnightError ZNIGHT005 for a malformed provider definition.
+ */
+export function createMetadata(
+  providers: Readonly<Record<Token, ProviderDefinition>>,
+  options: CreateMetadataOptions = {},
+): ZnightMetadata {
+  if (providers === null || typeof providers !== 'object') {
+    throw new TypeError('[znight] createMetadata() expects a record of provider definitions')
+  }
+  for (const [token, definition] of Object.entries(providers)) {
+    if (!isProviderDefinition(definition)) {
+      throw new ZnightError(
+        ErrorCode.InvalidDecorator,
+        `Invalid provider definition for ${describeToken(token)}: expected { scope, deps, factory }`,
+      )
+    }
+  }
+  const externals = options.externals?.map(external =>
+    typeof external === 'string' ? ({ token: external } satisfies ExternalDefinition) : external,
+  )
+  return {
+    version: METADATA_VERSION,
+    providers,
+    resolutionOrder: options.resolutionOrder ?? topologicalOrder(providers),
+    ...(options.aliases === undefined ? {} : { aliases: options.aliases }),
+    ...(externals === undefined ? {} : { externals }),
+    ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
+  }
+}
+
+/** A provider class or a token, in {@link defineTestMetadata}. */
+export type TestKey = Token | ProviderClass | ClassKey
+
+/** A dependency in {@link defineTestMetadata}: like `DependencyRef`, with classes allowed in place of tokens. */
+export type TestDependency =
+  | TestKey
+  | { readonly token: TestKey; readonly optional: true }
+  | { readonly multi: readonly TestKey[] }
+  | { readonly lazy: TestKey }
+
+/** A provider in {@link defineTestMetadata}. */
+export interface TestProvider<T = unknown> {
+  /** Default: `test#<ClassName>` (see `tokenPrefix`). Required without `class`. */
+  readonly token?: Token
+  readonly class?: ProviderClass<T>
+  /** Default: `'singleton'`. */
+  readonly scope?: Scope
+  /** Constructor (or factory) dependencies, in parameter order. */
+  readonly deps?: readonly TestDependency[]
+  /** Default: `deps => new Class(...deps)`. Required without `class`. */
+  readonly factory?: ProviderFactory<T>
+  readonly async?: boolean
+  readonly interceptors?: Readonly<Record<string, MethodInterception>>
+  readonly dispose?: string
+  /** `@Named` qualifier. */
+  readonly name?: string
+  readonly primary?: boolean
+  readonly source?: SourceLocation
+}
+
+/** Input of {@link defineTestMetadata}. */
+export interface TestMetadataSpec {
+  /** Providers: classes (no dependency) or {@link TestProvider}s. */
+  readonly providers?: readonly (TestProvider | ProviderClass)[]
+  /** Alias → provider pairs (`[UserRepository, PgUserRepository]`), or a record of tokens. */
+  readonly aliases?: Iterable<readonly [TestKey, TestKey]> | Readonly<Record<Token, TestKey>>
+  readonly externals?: readonly (Token | ExternalDefinition)[]
+  /** Feature metadata (`http`, `messaging`, `config`), tokens written with {@link testToken}. */
+  readonly extensions?: ZnightExtensionsMetadata
+  readonly resolutionOrder?: readonly Token[]
+  /** Prefix of the tokens derived from class names. Default: `'test'` (`test#UserService`). */
+  readonly tokenPrefix?: string
+}
+
+const DEFAULT_PREFIX = 'test'
+
+/** The token {@link defineTestMetadata} derives from a class: `<prefix>#<ClassName>`. */
+export function testToken(cls: ProviderClass | ClassKey, prefix: string = DEFAULT_PREFIX): Token {
+  const name = typeof cls === 'function' ? (cls as { name?: unknown }).name : undefined
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError('[znight] testToken(): expected a named class')
+  }
+  return `${prefix}#${name}`
+}
+
+/**
+ * Class-first hand-written metadata: tokens are derived from class names (`test#UserService`),
+ * dependencies may be classes, factories default to `new Class(...deps)` and the resolution order
+ * is computed.
+ *
+ * ```ts
+ * const metadata = defineTestMetadata({
+ *   providers: [
+ *     PgUserRepository,
+ *     { class: UserService, deps: [PgUserRepository, '@znight/observability#Logger'] },
+ *   ],
+ *   aliases: [[UserRepository, PgUserRepository]],
+ *   externals: ['@znight/observability#Logger'],
+ * })
+ * ```
+ *
+ * @throws ZnightError ZNIGHT004 for duplicate tokens; TypeError for a provider without class nor
+ *   token/factory.
+ */
+export function defineTestMetadata(spec: TestMetadataSpec = {}): ZnightMetadata {
+  const prefix = spec.tokenPrefix ?? DEFAULT_PREFIX
+  const providers = (spec.providers ?? []).map(entry =>
+    typeof entry === 'function' ? ({ class: entry } satisfies TestProvider) : entry,
+  )
+  const classTokens = new Map<unknown, Token>()
+  const tokens = providers.map(provider => {
+    if (provider === null || typeof provider !== 'object') {
+      throw new TypeError(
+        '[znight] defineTestMetadata(): a provider must be a class or { class?, token?, deps?, factory? }',
+      )
+    }
+    const token = provider.token ?? (provider.class === undefined ? undefined : testToken(provider.class, prefix))
+    if (token === undefined) throw new TypeError('[znight] defineTestMetadata(): a provider needs a class or a token')
+    if (provider.class !== undefined && !classTokens.has(provider.class)) classTokens.set(provider.class, token)
+    return token
+  })
+  const toToken = (key: TestKey): Token => {
+    if (typeof key === 'string') return key
+    return classTokens.get(key) ?? testToken(key, prefix)
+  }
+
+  const definitions = new Map<Token, ProviderDefinition>()
+  providers.forEach((provider, position) => {
+    const token = tokens[position] as Token
+    if (definitions.has(token)) {
+      throw new ZnightError(
+        ErrorCode.DuplicateProvider,
+        `defineTestMetadata(): duplicate provider ${describeToken(token)}`,
+        {
+          hints: ['Give one of them an explicit token'],
+        },
+      )
+    }
+    definitions.set(token, toDefinition(token, provider, toToken))
+  })
+
+  let aliases: Record<Token, Token> | undefined
+  if (spec.aliases !== undefined) {
+    const pairs = entriesOf<TestKey, TestKey>(spec.aliases).map(([alias, target]): [Token, Token] => [
+      toToken(alias),
+      toToken(target),
+    ])
+    aliases = Object.fromEntries(pairs)
+  }
+  return createMetadata(Object.fromEntries(definitions), {
+    ...(aliases === undefined ? {} : { aliases }),
+    ...(spec.externals === undefined ? {} : { externals: spec.externals }),
+    ...(spec.extensions === undefined ? {} : { extensions: spec.extensions }),
+    ...(spec.resolutionOrder === undefined ? {} : { resolutionOrder: spec.resolutionOrder }),
+  })
+}
+
+function toDefinition(token: Token, provider: TestProvider, toToken: (key: TestKey) => Token): ProviderDefinition {
+  const cls = provider.class
+  let factory = provider.factory
+  if (factory === undefined) {
+    if (cls === undefined) throw new TypeError(`[znight] defineTestMetadata(): ${token} needs a class or a factory`)
+    const constructible = cls as unknown as new (...args: unknown[]) => unknown
+    factory = (deps: unknown[]) => new constructible(...deps)
+  }
+  const deps = (provider.deps ?? []).map(dep => toDependency(dep, toToken))
+  return {
+    scope: provider.scope ?? 'singleton',
+    deps,
+    factory,
+    ...(cls === undefined ? {} : { class: cls }),
+    ...(provider.async === undefined ? {} : { async: provider.async }),
+    ...(provider.interceptors === undefined ? {} : { interceptors: provider.interceptors }),
+    ...(provider.dispose === undefined ? {} : { dispose: provider.dispose }),
+    ...(provider.name === undefined ? {} : { name: provider.name }),
+    ...(provider.primary === undefined ? {} : { primary: provider.primary }),
+    ...(provider.source === undefined ? {} : { source: provider.source }),
+  }
+}
+
+function toDependency(dep: TestDependency, toToken: (key: TestKey) => Token): DependencyRef {
+  if (typeof dep === 'string' || typeof dep === 'function') return toToken(dep)
+  if (dep !== null && typeof dep === 'object') {
+    if ('multi' in dep && Array.isArray(dep.multi)) return { multi: dep.multi.map(toToken) }
+    if ('lazy' in dep && dep.lazy !== undefined) return { lazy: toToken(dep.lazy) }
+    if ('token' in dep && dep.optional === true) return { token: toToken(dep.token), optional: true }
+    if ('prototype' in dep) return toToken(dep as ClassKey)
+  }
+  throw new TypeError(`[znight] defineTestMetadata(): invalid dependency ${String(dep)}`)
+}
+
+/** Hard dependencies of a definition (lazy ones excluded: they never constrain the order). */
+function hardDependencies(definition: ProviderDefinition): Token[] {
+  const tokens: Token[] = []
+  for (const ref of definition.deps) {
+    if (typeof ref === 'string') tokens.push(ref)
+    else if ('multi' in ref) tokens.push(...ref.multi)
+    else if ('token' in ref) tokens.push(ref.token)
+  }
+  return tokens
+}
+
+/** Deterministic topological order (dependencies first). Cycles are left for the container to report. */
+function topologicalOrder(providers: Readonly<Record<Token, ProviderDefinition>>): Token[] {
+  const order: Token[] = []
+  const state = new Map<Token, 'visiting' | 'done'>()
+  const visit = (token: Token): void => {
+    if (state.has(token) || !Object.hasOwn(providers, token)) return
+    state.set(token, 'visiting')
+    for (const dep of hardDependencies(providers[token] as ProviderDefinition)) visit(dep)
+    state.set(token, 'done')
+    order.push(token)
+  }
+  for (const token of Object.keys(providers)) visit(token)
+  return order
+}

package/src/extensions.ts

@@ -0,0 +1,109 @@
+/**
+ * Structural readers of the feature metadata (`metadata.extensions`). `@znight/testing` depends on
+ * no feature package: it reads the documented shapes (architecture §9) defensively and ignores
+ * malformed entries.
+ */
+import type { Token, ZnightMetadata } from '@znight/core'
+
+/** A configuration class (`metadata.extensions.config.configs[]`), as far as tests need it. */
+export interface ConfigClassInfo {
+  readonly token: Token
+  readonly prefix: string | undefined
+  readonly fields: readonly ConfigFieldInfo[]
+}
+
+/** A field of a configuration class. */
+export interface ConfigFieldInfo {
+  readonly property: string
+  readonly env: string | undefined
+  /** Config type (`'string'`, `'number'`, `'url'`...), `undefined` when absent from the metadata. */
+  readonly type: string | undefined
+  /** Whether the field declares a default value (`@Default`; initializers are not in the metadata). */
+  readonly hasDefault: boolean
+  readonly default: unknown
+  readonly required: boolean
+}
+
+type Loose = Readonly<Record<string, unknown>>
+
+function isRecord(value: unknown): value is Loose {
+  return value !== null && typeof value === 'object'
+}
+
+function arrayOf(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function extension(metadata: ZnightMetadata, name: string): Loose | undefined {
+  if (!isRecord(metadata)) return undefined
+  const extensions: unknown = metadata.extensions
+  if (!isRecord(extensions)) return undefined
+  const value = extensions[name]
+  return isRecord(value) ? value : undefined
+}
+
+function tokensOf(value: unknown): Token[] {
+  return arrayOf(value).filter((token): token is Token => typeof token === 'string')
+}
+
+/** Configuration classes declared by `@znight/config` (`extensions.config.configs`), by token. */
+export function readConfigClasses(metadata: ZnightMetadata): Map<Token, ConfigClassInfo> {
+  const result = new Map<Token, ConfigClassInfo>()
+  for (const entry of arrayOf(extension(metadata, 'config')?.['configs'])) {
+    if (!isRecord(entry) || typeof entry['token'] !== 'string') continue
+    const fields: ConfigFieldInfo[] = []
+    for (const field of arrayOf(entry['fields'])) {
+      if (!isRecord(field) || typeof field['property'] !== 'string') continue
+      fields.push({
+        property: field['property'],
+        env: typeof field['env'] === 'string' ? field['env'] : undefined,
+        type: typeof field['type'] === 'string' ? field['type'] : undefined,
+        hasDefault: Object.hasOwn(field, 'default') && field['default'] !== undefined,
+        default: field['default'],
+        required: field['required'] === true,
+      })
+    }
+    const prefix = entry['prefix']
+    result.set(entry['token'], {
+      token: entry['token'],
+      prefix: typeof prefix === 'string' && prefix !== '' ? prefix : undefined,
+      fields,
+    })
+  }
+  return result
+}
+
+/**
+ * Tokens an HTTP application needs at boot: controllers (`extensions.http.controllers[].token`) and
+ * the guards and interceptors they and their routes reference.
+ */
+export function readHttpRoots(metadata: ZnightMetadata): Token[] {
+  const roots: Token[] = []
+  for (const controller of arrayOf(extension(metadata, 'http')?.['controllers'])) {
+    if (!isRecord(controller)) continue
+    if (typeof controller['token'] === 'string') roots.push(controller['token'])
+    roots.push(...tokensOf(controller['guards']), ...tokensOf(controller['interceptors']))
+    for (const route of arrayOf(controller['routes'])) {
+      if (isRecord(route)) roots.push(...tokensOf(route['guards']), ...tokensOf(route['interceptors']))
+    }
+  }
+  return roots
+}
+
+/** Message consumers (`extensions.messaging.consumers[].token`). */
+export function readMessagingRoots(metadata: ZnightMetadata): Token[] {
+  const roots: Token[] = []
+  for (const consumer of arrayOf(extension(metadata, 'messaging')?.['consumers'])) {
+    if (isRecord(consumer) && typeof consumer['token'] === 'string') roots.push(consumer['token'])
+  }
+  return roots
+}
+
+/** Hosts of scheduled jobs (`extensions.schedule.jobs[].token`), disabled jobs included (they can be triggered). */
+export function readScheduleRoots(metadata: ZnightMetadata): Token[] {
+  const roots: Token[] = []
+  for (const job of arrayOf(extension(metadata, 'schedule')?.['jobs'])) {
+    if (isRecord(job) && typeof job['token'] === 'string') roots.push(job['token'])
+  }
+  return roots
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * `@znight/testing`: unit tests with auto-mocked dependencies (`TestBed`), end-to-end tests of a
+ * started application (`TestApp`), deep auto-mocks and a Jest-compatible spy that cooperate with
+ * Vitest, Jest and `bun:test`.
+ */
+export type { ConfigProperties, ConfigValues } from './config.ts'
+export type { MockRegistry } from './mock-registry.ts'
+export type {
+  AnyFunction,
+  DeepMock,
+  DeepMockFunction,
+  Mocked,
+  MockedMember,
+  MockFnFactory,
+  MockFnOption,
+  MockFunction,
+  MockResult,
+  MockState,
+  UntypedFunction,
+} from './types.ts'
+
+export {
+  type CreateMetadataOptions,
+  createMetadata,
+  defineTestMetadata,
+  type TestDependency,
+  type TestKey,
+  type TestMetadataSpec,
+  type TestProvider,
+  testToken,
+} from './define-metadata.ts'
+export { type CreateMockOptions, clearMock, createMock, isMock, resetMock } from './mock.ts'
+export { detectMockFn, type MockFnSource, type ResolvedMockFn, resolveMockFn, setDefaultMockFn } from './mock-fn.ts'
+export {
+  type OverrideDefinitionEntry,
+  type OverrideEntry,
+  type OverrideFactoryOptions,
+  override,
+  overrideFactory,
+} from './overrides.ts'
+export { createSpy, isBuiltinSpy } from './spy.ts'
+export {
+  HTTP_PLUGIN_NAME,
+  type HttpInjector,
+  type HttpInjectResult,
+  type HttpStreamInjector,
+  type InjectRequest,
+  type InjectResponse,
+  type InjectSseResponse,
+  type InjectStreamRequest,
+  type InjectStreamResponse,
+  type PluginInitRoots,
+  type SetCookieInfo,
+  type SseMessage,
+  TestApp,
+  type TestAppOptions,
+} from './test-app.ts'
+export { type AopMode, TestBed, type TestBedOptions, type TestBedResult } from './testbed.ts'

package/src/metadata-index.ts

@@ -0,0 +1,161 @@
+import type { ExternalDefinition, ProviderClass, ProviderDefinition, Token, ZnightMetadata } from '@znight/core'
+
+import { describeToken, displayName, ErrorCode, METADATA_VERSION, ZnightError } from '@znight/core'
+
+/**
+ * Read-only index over compiled metadata: provider definitions, aliases, externals and the key
+ * lookups shared by `TestBed`, `mocks.get()` and the testing helpers (class, token, alias or display
+ * name → canonical token). Internal.
+ */
+export class MetadataIndex {
+  readonly metadata: ZnightMetadata
+  readonly #providers = new Map<Token, ProviderDefinition>()
+  readonly #aliases = new Map<Token, Token>()
+  readonly #externals = new Map<Token, ExternalDefinition>()
+
+  constructor(metadata: ZnightMetadata) {
+    assertMetadata(metadata)
+    this.metadata = metadata
+    for (const [token, definition] of Object.entries(metadata.providers)) this.#providers.set(token, definition)
+    for (const [alias, target] of Object.entries(metadata.aliases ?? {})) this.#aliases.set(alias, target)
+    for (const external of metadata.externals ?? []) {
+      if (typeof external?.token === 'string') this.#externals.set(external.token, external)
+    }
+  }
+
+  /** Every provider token, in declaration order. */
+  providerTokens(): IterableIterator<Token> {
+    return this.#providers.keys()
+  }
+
+  definition(token: Token): ProviderDefinition | undefined {
+    return this.#providers.get(token)
+  }
+
+  isProvider(token: Token): boolean {
+    return this.#providers.has(token)
+  }
+
+  external(token: Token): ExternalDefinition | undefined {
+    return this.#externals.get(token)
+  }
+
+  /** Whether `token` is a provider, an alias or an external of the metadata. */
+  isKnown(token: Token): boolean {
+    return this.#providers.has(token) || this.#aliases.has(token) || this.#externals.has(token)
+  }
+
+  /** Provider, alias and external tokens. */
+  knownTokens(): Set<Token> {
+    return new Set([...this.#providers.keys(), ...this.#aliases.keys(), ...this.#externals.keys()])
+  }
+
+  /** The class of a provider, when it is a class provider. */
+  classOf(token: Token): ProviderClass | undefined {
+    return this.#providers.get(token)?.class
+  }
+
+  /** Follows aliases (cycle-guarded) until a provider token; returns `token` itself otherwise. */
+  canonical(token: Token): Token {
+    let current = token
+    const seen = new Set<Token>()
+    while (!this.#providers.has(current) && this.#aliases.has(current) && !seen.has(current)) {
+      seen.add(current)
+      current = this.#aliases.get(current) as Token
+    }
+    return current
+  }
+
+  /** Alias entries (alias → target), for filtering and display. */
+  aliases(): IterableIterator<[Token, Token]> {
+    return this.#aliases.entries()
+  }
+
+  /**
+   * Finds the canonical token designated by `key` among `universe`:
+   * - a string: a token of `universe`, an alias resolving into it, or a unique display name
+   *   (`'UserService'`) of a token or alias;
+   * - a class: the token whose provider class is `key`, else the unique token whose class extends
+   *   it, else a unique display name equal to the class name (externals, interfaces).
+   *
+   * @throws ZnightError ZNIGHT008 when a display name is ambiguous.
+   */
+  find(key: unknown, universe: ReadonlySet<Token>): Token | undefined {
+    if (typeof key === 'string') {
+      if (universe.has(key)) return key
+      const canonical = this.canonical(key)
+      if (universe.has(canonical)) return canonical
+      return this.#findByName(key, universe, undefined)
+    }
+    if (typeof key !== 'function') return undefined
+    const cls = key as ProviderClass
+    const exact = [...universe].filter(token => this.classOf(token) === cls)
+    if (exact.length > 0) return exact[0]
+    const derived = [...universe].filter(token => extendsClass(this.classOf(token), cls))
+    if (derived.length === 1) return derived[0]
+    if (derived.length > 1) throw ambiguousError(cls.name, derived)
+    const name = cls.name
+    return typeof name === 'string' && name !== '' ? this.#findByName(name, universe, cls) : undefined
+  }
+
+  #findByName(name: string, universe: ReadonlySet<Token>, cls: ProviderClass | undefined): Token | undefined {
+    // an alias and its provider designate the same thing: matches are compared by canonical token
+    const matches = new Set<Token>()
+    const add = (token: Token): void => {
+      const canonical = this.canonical(token)
+      if (universe.has(canonical)) matches.add(canonical)
+      else if (universe.has(token)) matches.add(token)
+    }
+    for (const token of universe) if (displayName(token) === name) add(token)
+    for (const [alias] of this.#aliases) if (displayName(alias) === name) add(alias)
+    const candidates = [...matches].filter(token => {
+      if (cls === undefined) return true
+      const own = this.classOf(token)
+      return own === undefined || own === cls || extendsClass(own, cls)
+    })
+    if (candidates.length === 1) return candidates[0]
+    if (candidates.length > 1) throw ambiguousError(name, candidates)
+    return undefined
+  }
+}
+
+function extendsClass(candidate: ProviderClass | undefined, base: ProviderClass): boolean {
+  if (candidate === undefined || candidate === base) return false
+  const prototype: unknown = base.prototype
+  return typeof prototype === 'object' && prototype !== null && candidate.prototype instanceof base
+}
+
+function ambiguousError(name: string, tokens: readonly Token[]): ZnightError {
+  return new ZnightError(
+    ErrorCode.AmbiguousInjection,
+    `"${name}" is ambiguous: it matches ${tokens.map(describeToken).join(', ')}`,
+    { hints: ['Use the full token (or the class) instead of the display name'] },
+  )
+}
+
+function assertMetadata(metadata: ZnightMetadata): void {
+  if (
+    metadata === null ||
+    typeof metadata !== 'object' ||
+    metadata.providers === null ||
+    typeof metadata.providers !== 'object'
+  ) {
+    throw new ZnightError(
+      ErrorCode.MissingProvider,
+      'No compiled metadata: expected the generated __ZNIGHT_METADATA__',
+      {
+        hints: [
+          'Pass { metadata: __ZNIGHT_METADATA__ } imported from src/.znight/container.generated.ts',
+          'Generate it before running tests: `znight generate`, the Bun preload `@znight/compiler/bun` or the Vite plugin under Vitest',
+        ],
+      },
+    )
+  }
+  if (metadata.version !== METADATA_VERSION) {
+    throw new ZnightError(
+      ErrorCode.VersionMismatch,
+      `Unsupported metadata version ${String(metadata.version)} (expected ${METADATA_VERSION})`,
+      { hints: ['Regenerate the metadata with the @znight/compiler version matching @znight/testing'] },
+    )
+  }
+}

package/src/mock-fn.ts

@@ -0,0 +1,83 @@
+import type { MockFnFactory, MockFnOption } from './types.ts'
+
+import { createRequire } from 'node:module'
+
+import { createSpy } from './spy.ts'
+
+/** Where the spy factory used by mocks comes from. */
+export type MockFnSource = 'custom' | 'vitest' | 'jest' | 'bun' | 'builtin'
+
+/** A spy factory and its origin (see {@link resolveMockFn}). */
+export interface ResolvedMockFn {
+  readonly source: MockFnSource
+  readonly create: MockFnFactory
+}
+
+const BUILTIN: ResolvedMockFn = Object.freeze({ source: 'builtin', create: createSpy as MockFnFactory })
+
+let defaultOption: MockFnOption = 'auto'
+/** `mock` of `bun:test`: `undefined` until probed, `null` when unavailable. */
+let bunMock: MockFnFactory | null | undefined
+
+function assertOption(option: unknown, where: string): asserts option is MockFnOption {
+  if (typeof option === 'function' || option === 'auto' || option === 'builtin') return
+  throw new TypeError(`[znight] ${where}: mockFn must be 'auto', 'builtin' or a function such as vi.fn`)
+}
+
+/**
+ * Sets the spy factory used when `mockFn` is not passed explicitly (e.g. in a Vitest setup file:
+ * `setDefaultMockFn(vi.fn)`). Without argument, restores auto-detection.
+ */
+export function setDefaultMockFn(option: MockFnOption = 'auto'): void {
+  assertOption(option, 'setDefaultMockFn()')
+  defaultOption = option
+}
+
+/**
+ * Resolves a {@link MockFnOption} (default: the option set with {@link setDefaultMockFn}, `'auto'`
+ * initially) to a spy factory.
+ */
+export function resolveMockFn(option?: MockFnOption): ResolvedMockFn {
+  const effective = option ?? defaultOption
+  assertOption(effective, 'resolveMockFn()')
+  if (typeof effective === 'function') return { source: 'custom', create: effective }
+  if (effective === 'builtin') return BUILTIN
+  return detectMockFn()
+}
+
+/**
+ * Auto-detects the spy factory of the running test framework: Vitest (`globalThis.vi.fn`, with
+ * `globals: true`), Jest (`globalThis.jest.fn`), `bun:test` (`mock`, loaded only when running on
+ * Bun), otherwise the built-in spy ({@link createSpy}).
+ */
+export function detectMockFn(): ResolvedMockFn {
+  const scope = globalThis as { vi?: { fn?: unknown }; jest?: { fn?: unknown } }
+  const vitest = scope.vi?.fn
+  if (typeof vitest === 'function') return { source: 'vitest', create: vitest as MockFnFactory }
+  const jest = scope.jest?.fn
+  if (typeof jest === 'function') return { source: 'jest', create: jest as MockFnFactory }
+  const bun = loadBunMock()
+  if (bun !== undefined) return { source: 'bun', create: bun }
+  return BUILTIN
+}
+
+/** Whether the code runs on Bun. */
+export function isBunRuntime(): boolean {
+  return typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined'
+}
+
+function loadBunMock(): MockFnFactory | undefined {
+  bunMock ??= isBunRuntime() ? requireBunMock() : null
+  return bunMock ?? undefined
+}
+
+function requireBunMock(): MockFnFactory | null {
+  try {
+    // non-literal specifier: bundlers and Vite never try to resolve `bun:test`
+    const specifier = ['bun', 'test'].join(':')
+    const bunTest = createRequire(import.meta.url)(specifier) as { mock?: unknown }
+    return typeof bunTest.mock === 'function' ? (bunTest.mock as MockFnFactory) : null
+  } catch {
+    return null
+  }
+}