Use Case

As a... Node.js Driver Developer
I want... to execute the driver's test suite within a constrained "Clean Room" environment that simulates non-Node.js runtimes (e.g., Browser, Edge).
So that... I can verify that the codebase is environment-agnostic and prevent the accidental re-introduction of Node-specific globals (like Buffer or process) in future PRs.

User Experience

• Developers can run a specific command (e.g., npm run check:sandbox) which executes the integration test suite.

• If the driver code uses a forbidden global (e.g., Buffer.from(...)), the test runner must fail explicitly with a ReferenceError, pinpointing the violation.

• The system allows for an "Iterative Subtraction" workflow: developers can temporarily allow specific globals in the configuration to keep the build green while refactoring is in progress.

Impact:

• This is an internal tooling improvement to enable the "Pluggable I/O" feature. It blocks the ability to confidently release the driver for Edge environments.

Dependencies

• Upstream: None.

• Downstream: This ticket is the prerequisite for all refactoring tickets (e.g., "Replace Buffer with Uint8Array"). We cannot verify those fixes without this harness.

Risks/Unknowns

• Performance: On-the-fly TypeScript transpilation (ts.transpileModule) inside the test runner may significantly slow down test execution compared to standard ts-node. Caching strategies might be needed.

• 3rd Party Dependencies: Runtime dependencies (like bson) might crash in the sandbox if they rely on globals. We may need to update their code.

• Tooling Compatibility: Ensuring mocha, chai, and sinon (which run in the Host) function correctly when assertions are triggered from within the Guest (Sandbox) context.

Acceptance Criteria

Implementation Requirements

• Custom Runner: Develop a Node.js script (e.g., test/tools/sandbox_runner.js) that orchestrates the test execution.

• Context Isolation: Utilize vm.createContext to instantiate a V8 context.
  • Initial State: The context should accept a configuration map to inject/hide globals.
  • Default: It must support standard Web APIs (console, setTimeout, URL) and Mocha interfaces (describe, it).

• Proxy Require: Implement a custom require function to intercept imports.
  • Rule 1: node_modules must "escape" (use Host require) to ensure test tooling works.
  • Rule 2: Local source files (src/{}/.ts, test//.ts) must be intercepted, transpiled, and executed inside the Sandbox.

• Transpilation: Integrate typescript compiler API to transpile intercepted files in-memory before execution.

• CI Integration: Create an Evergreen workflow that executes this runner.

Testing Requirements

• The runner must be capable of running the existing Integration tests suite (even if we have to allow-list all globals initially to get it running).

Documentation Requirements

• Add a section to test/readme.md explaining:
  • How to run the sandbox tests.
  • How the "Iterative Subtraction" strategy works (how to enable/disable globals in the runner config).

Follow Up Requirements

• Individual tickets for removing the globals that are currently allow-listed (e.g., "Refactor: Remove global.Buffer dependency") already filled.