test(NODE-7493): Enable source maps for accurate test debugging

[seanrmilligan]

Description

Summary of Changes

• Enables source map generation: test/tsconfig.json is updated to include "sourceMap": true in the compilerOptions, ensuring that TypeScript generates source maps when compiling test files.
• Activates native V8 source map support: All Mocha test configurations (.mocharc.js, test/manual/mocharc.js, test/mocha_lambda.js, test/mocha_mongodb.js) are modified to consistently pass the --enable-source-maps Node.js option. This directs the V8 engine to use available source maps for more accurate stack traces. The node-option now always includes enable-source-maps, regardless of the Node.js major version.
• Adds a source map verification test: A new unit test, test/unit/sourcemap_demo.test.ts, is introduced to explicitly verify that V8's native stack traces correctly map back to the original TypeScript source line numbers.
• Updates bundled test scripts: The check:test-bundled and check:unit-bundled scripts in package.json are modified to include npm run build:runtime-barrel after their respective test commands.

Notes for Reviewers

The sourcemap_demo.test.ts utilizes a temporary bypass of source-map-support's Error.prepareStackTrace override. This allows the test to observe V8's native behavior with the --enable-source-maps flag in isolation, providing a direct confirmation that the V8 engine itself is correctly resolving stack trace line numbers to their TypeScript origins.

What is the motivation for this change?

This change improves the debugging experience for tests. By enabling source map generation and activating V8's native source map support, stack traces for errors occurring in tests will now correctly point to the original TypeScript source files and line numbers, rather than the transpiled JavaScript output.

Release Highlight

Release notes highlight

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Enables Node.js native source map support across the test runners so that stack traces from compiled TypeScript test files report original .ts line numbers. Adds a demonstration/verification test for the behavior.

Changes:

• Adds --enable-source-maps to the node-option array in all mocha config files.
• Enables sourceMap: true in test/tsconfig.json so emitted JS has source maps.
• Adds a new unit test that verifies V8 natively maps stack frames back to TS source lines.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
.mocharc.js	Adds enable-source-maps to node-options for default test runs.
test/mocha_mongodb.js	Adds enable-source-maps for integration test runs.
test/mocha_lambda.js	Adds enable-source-maps for lambda test runs.
test/manual/mocharc.js	Adds enable-source-maps for manual test runs.
test/tsconfig.json	Enables sourceMap emission for tests.
test/unit/sourcemap_demo.test.ts	New test verifying V8 reports TS line numbers in stack frames.
package.json	Appends build:runtime-barrel to bundled check scripts using ;.

[PavelSafronov]

One of the Acceptance Criteria is to verify hostMatchesWildcards debugging. This can be done manually (test locally, add the repro steps to the PR description, I'll verify on my side), or maybe we can update sourcemap.test.ts test to import and use hostMatchesWildcards and verify that the debugger experience is improved. Up to you how we verify this.

[PavelSafronov]

Love the idea of checking programmatically that the correct line is reported. But the current implementation is a bit flaky: we are hard-coding TS_SOURCE_LINE. What if instead we populate that value during test runtime by reading the test file?

[tadjik1]

thanks @seanrmilligan, the approach looks excellent, great idea to use native source maps! I've left few comments, please let me know what you think. in addition to that - there are some merge conflicts, can you please take a look?

[nbbeeken]

Screen.Recording.2026-06-04.at.10.53.51.AM.mov

The changes here don't fix the issue and removing the source-map-support package has added the problem to the integration tests

[nbbeeken]

I think we can solve this in two ways, one simple, one probably a large-ish undertaking.

• Just add the source-map-support import to a mocha "require"-ed file that the unit tests use and maybe even share it with the int tests to de-dupe. This is the only way I know that the sourcemaps will work with ts-node
• Remove ts-node, its no longer needed with the builtin support typescript in Node.js, if we go that direction then your "native" sourcemap flag that's being added here would work! but I fear that the tests and how they are formatted (like import paths and such) are not going to work without some heavy lifting
  • I would still say this is the right way to do things but schedule it in the future with proper estimation

[seanrmilligan]

Screen.Recording.2026-06-04.at.10.53.51.AM.mov
The changes here don't fix the issue and removing the source-map-support package has added the problem to the integration tests

Could you share the test that's exercising the path?

[seanrmilligan]

I think we can solve this in two ways, one simple, one probably a large-ish undertaking.

• Just add the source-map-support import to a mocha "require"-ed file that the unit tests use and maybe even share it with the int tests to de-dupe. This is the only way I know that the sourcemaps will work with ts-node

• Remove ts-node, its no longer needed with the builtin support typescript in Node.js, if we go that direction then your "native" sourcemap flag that's being added here would work! but I fear that the tests and how they are formatted (like import paths and such) are not going to work without some heavy lifting

  • I would still say this is the right way to do things but schedule it in the future with proper estimation

Re: second bullet

I looked into using native Node.js TypeScript debugging symbol support but it seemed infeasible.

• minor reason: The feature was added in v22 with a flag, v22.18 without a flag. We still support older versions of Node.js. We could overcome this by conditionally splitting how we treat the build by version in .mocharc.js and test/mocha_mongodb.js
• major reason: The disparate ways Node.js recognizes and handles CJS and ESM files has been smoothed over for us by the ts-node package. Backing out that package to embrace native support would require fixing things in quite a few places, like how imports/requires work. Some of those are lazy-loaded and to re-implement them would require more work than this bug is sized for.

[nbbeeken]

Yea agreed, to your minor point we don't go back to test older versions of Node within a major so any 22 testing is going to be after that feature release, but even if it was before that feature release the env var NODE_OPTIONS would be a way to enable the expiremental parsing wherever you need it.

But yea major point, the TS in the test files is not erasableSyntaxOnly and verbatimModuleSyntax compliant, if the work was done to get the tests building with those flags then you could use node's builtin support.

[nbbeeken]

Could you share the test that's exercising the path?

It's not a specific test, I'm just running npm run check:unit and I know there's something that eventually hits the cursor code at some point 😅 just because of it's centrality to the driver's API. This would reproduce on any test, you just have to reach a code comment somewhere in src

Looking at the video, its probably the second test under the "Collation" suite, whatever hasn't printed yet