[danieljbruce]

Description

Adds runtime-agnostic createProxyquire and proxyquire helpers to google-test-utils.

Impact

Releasing createProxyquire in google-test-utils avoids extra YAML flags across stacked PRs.

Changes

• Per test: remove --proxyquire-shim from common, bigquery, datastore, and dns #9643 (comment), extracts just the createProxyquire and proxyquire implementation in core/test-utils (google-test-utils) into a standalone PR.
• We want to merge and release google-test-utils (core/test-utils) with createProxyquire first so that the rest of the stacked PRs (test: remove --proxyquire-shim from common, bigquery, datastore, and dns #9643, test: remove --proxyquire-shim from logging and pubsub packages #9644, test: remove --proxyquire-shim from bigtable, spanner, and storage #9645, chore: remove proxyquire-bun-shim.cjs and runner flags #9646) can consume the published google-test-utils package and do not need the extra --filter "./core/test-utils" --ignore-scripts, pnpm --dir core/test-utils run compile, ensureWorkspacePackagesLinked(), and run prepare --if-present flags in the .yaml files (cloudbuild.yaml and .github/actions/pnpm-lockfile-check/action.yaml).
• core/test-utils/src/proxyquire.ts: Adds createProxyquire, proxyquire, Proxyquire, and ProxyquireStubs built on Module.prototype.require and require.cache with automatic caller path resolution (Error.prepareStackTrace) for Node.js and Bun (JS_RUNTIME=bun).
• core/test-utils/src/index.ts: Exports createProxyquire, proxyquire, Proxyquire, and ProxyquireStubs.
• core/test-utils/test/proxyquire.test.ts: Adds unit tests covering direct/transitive @global stubbing, @noCallThru / noCallThru() / callThru(), noPreserveCache() / preserveCache(), null stub MODULE_NOT_FOUND handling, and bare module stubs.

Testing

• Executed pnpm --dir core/test-utils test 5x on Node.js and JS_RUNTIME=bun MOCHA_PARALLEL=false bun --bun run --cwd core/test-utils test 5x on Bun ($\ge 95%$ confidence, 25/25 unit tests passing).
• Verified strict lint and TypeScript checks pass via node ./bin/linter.mjs --strict and ci/run_conditional_tests.sh --strict.

Alternatives

• Including createProxyquire directly inside test: remove --proxyquire-shim from common, bigquery, datastore, and dns #9643 alongside the common, bigquery, datastore, and google-cloud-dns migrations was considered, but because .npmrc sets link-workspace-packages=false and enable-pre-post-scripts=true, doing so before releasing google-test-utils requires extra --filter "./core/test-utils" --ignore-scripts and workspace-linking flags across the YAML files in the stack.
• Not merging this PR would leave those temporary YAML workarounds in the stack PRs.

[danieljbruce]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a runtime-agnostic proxyquire utility in core/test-utils to support module stubbing in both Node.js and Bun environments, accompanied by comprehensive unit tests. A critical issue was identified in the ES6 Proxy's getOwnPropertyDescriptor trap, where unconditionally forcing configurable: true on all descriptors violates proxy invariants and can trigger a TypeError when proxying functions or objects with non-configurable properties. It is recommended to return the target's descriptor as-is if it exists, and only force configurability when falling back to the real object's descriptor.

[gemini-code-assist]

In ES6 Proxies, the getOwnPropertyDescriptor trap must respect strict invariants. Specifically, if a property exists on the target object (stub) and is non-configurable, the trap must not return it as configurable. Forcing configurable: true on all descriptors will cause a TypeError when proxying functions (which have non-configurable properties like prototype or length) or objects with other non-configurable properties.

Conversely, if a property is non-configurable on the real object but does not exist on the target object, it must be reported as configurable to avoid another invariant violation.

To satisfy both invariants, we should return the target's descriptor as-is if it exists, and only force configurable: true when falling back to the descriptor from the real object.

                    getOwnPropertyDescriptor(target, prop) {
                      const targetDesc = Reflect.getOwnPropertyDescriptor(target, prop);
                      if (targetDesc) {
                        return targetDesc;
                      }
                      const realDesc = Reflect.getOwnPropertyDescriptor(real, prop);
                      if (realDesc) {
                        return {...realDesc, configurable: true};
                      }
                      return undefined;
                    },

[danieljbruce]

[Generated] Addressed in 214fe91: updated getOwnPropertyDescriptor to return targetDesc directly when the property exists on target (stub), and only force configurable: true when falling back to realDesc. Also added a unit test covering non-configurable stub properties (such as function prototype and configurable: false data descriptors).

[gemini-code-assist]

Code Review

This pull request introduces a custom, runtime-agnostic implementation of proxyquire to support module stubbing in both Node.js and Bun environments, along with corresponding unit tests. While the implementation is comprehensive, two critical issues were identified: a potential runtime TypeError in the Proxy's getOwnPropertyDescriptor trap when handling non-configurable properties, and a bug in the cache cleanup logic that incorrectly deletes the module under test from the cache even when cache preservation is enabled.

[gemini-code-assist]

There is a potential runtime TypeError when wrapping stubs in a Proxy if the stub has non-configurable properties, or if we try to redefine non-configurable properties from the real module on the proxy.

According to the ES6 Proxy invariants, the getOwnPropertyDescriptor trap must not report a property as configurable if it is non-configurable on the target object (the stub). Currently, the code unconditionally forces configurable: true on all descriptors, which will throw a TypeError if the property already exists on the stub as non-configurable.

To safely satisfy the Proxy invariants, we should only force configurable: true on descriptors retrieved from the real module when they do not exist on the stub (target) object.

                    getOwnPropertyDescriptor(target, prop) {
                      const targetDesc = Reflect.getOwnPropertyDescriptor(target, prop);
                      if (targetDesc) {
                        return targetDesc;
                      }
                      const realDesc = Reflect.getOwnPropertyDescriptor(real, prop);
                      return realDesc ? {...realDesc, configurable: true} : undefined;
                    },

[danieljbruce]

[Generated] Addressed in 214fe91: getOwnPropertyDescriptor now returns Reflect.getOwnPropertyDescriptor(target, prop) as-is when defined on target and only forces configurable: true on descriptors read from real.

[gemini-code-assist]

There is a bug in the cache cleanup logic when opts.keepCache is true (the default) and the module under test (sut) was not previously in the cache.

Currently, cache[sut] is deleted in the finally block regardless of whether it was originally in the cache or not. If sut was not in the cache before the proxyquire call, its saved value m is undefined. Therefore, the restore loop does not restore it, and the newly loaded sut module is permanently deleted from the cache. This violates the expected behavior of keepCache: true (where the loaded module should remain in the cache for subsequent requires).

To fix this, we should only delete cache[sut] if !opts.keepCache or if we have a saved module to restore for it.

      const savedMap = new Map(saved);
      for (const id of global ? Object.keys(cache) : [sut]) {
        if (!id.endsWith('.node')) {
          const original = savedMap.get(id);
          if (!opts.keepCache || id !== sut || original !== undefined) {
            delete cache[id];
          }
        }
      }
      for (const [id, m] of saved) {
        if (m && (opts.keepCache || id !== sut)) cache[id] = m;
      }

[danieljbruce]

[Generated] Addressed in 214fe91: updated the finally cache cleanup block to only delete cache[sut] when !opts.keepCache or when a pre-existing original cached module is being restored from saved, and added unit test assertions verifying modCache[sutFile] under both noPreserveCache() and preserveCache().

[danieljbruce]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a runtime-agnostic proxyquire utility in core/test-utils to support stubbing dependencies in both Node.js and Bun environments, along with a comprehensive unit test suite. The review feedback points out critical issues when running in ESM or Bun environments where file:// URLs may be returned by stack traces or passed as caller arguments. To address this, the reviewer suggests importing and using fileURLToPath to normalize these URLs in both getCallerFile and resolveModule, preventing incorrect caller detection, options leakage, and path resolution failures.

[gemini-code-assist]

In environments like Bun or Node.js ESM, frame.getFileName() can return a file:// URL. If file is a file:// URL and __filename is an absolute path, the comparison file !== __filename will incorrectly evaluate to true for proxyquire.ts itself. This causes getCallerFile() to return proxyquire.ts instead of the actual caller.

This has two major consequences:

1. Relative Path Resolution Failure: Relative paths for the SUT will be resolved relative to proxyquire.ts instead of the calling test file.
2. Options Leakage: Since options (like noCallThru) are keyed by the caller's filename, returning proxyquire.ts for all callers means all test files will share the same options bucket, leading to unexpected side effects across tests.

Normalizing the URL to an absolute path using fileURLToPath resolves this issue.

function getCallerFile(): string | undefined {
  const origPrepare = Error.prepareStackTrace;
  try {
    const err = new Error();
    Error.prepareStackTrace = (_, stack) => stack;
    const stack = err.stack as unknown as NodeJS.CallSite[] | undefined;
    if (Array.isArray(stack)) {
      for (const frame of stack) {
        let file = frame.getFileName?.();
        if (file) {
          if (file.startsWith('file://')) {
            try {
              file = fileURLToPath(file);
            } catch {
              // ignore
            }
          }
          if (
            file !== __filename &&
            !file.startsWith('node:') &&
            !file.startsWith('internal/')
          ) {
            return file;
          }
        }
      }
    }
  } finally {
    Error.prepareStackTrace = origPrepare;
  }
  return undefined;
}

[danieljbruce]

[Generated] Addressed in 2925587: normalized file via fileURLToPath(file) in getCallerFile() when file.startsWith('file://') before comparing against __filename.

[gemini-code-assist]

If a user passes import.meta.url (which is a file:// URL) as the caller argument to createProxyquire, resolveModule will fail to find it in require.cache and will pass the URL to path.dirname, leading to incorrect path resolution. Normalizing the filename string using fileURLToPath ensures robust compatibility with ESM callers.

function resolveModule(target: NodeModule | string | undefined): NodeModule {
  if (target && typeof target === 'object') {
    return target;
  }
  let filename =
    typeof target === 'string' ? target : (getCallerFile() ?? __filename);
  if (filename.startsWith('file://')) {
    try {
      filename = fileURLToPath(filename);
    } catch {
      // ignore
    }
  }
  const cached = require.cache[filename];
  if (cached) {
    return cached;
  }
  const fallback = new mod(filename);
  fallback.filename = filename;
  fallback.paths = mod._nodeModulePaths(path.dirname(filename));
  return fallback;
}

[danieljbruce]

[Generated] Addressed in 2925587: normalized filename via fileURLToPath(filename) in resolveModule() when filename.startsWith('file://'), and added a unit test in test/proxyquire.test.ts verifying createProxyquire(pathToFileURL(sutFile).href).