在VSCode中使用TypeScript运行Mocha测试失败的问题

Hey there, I’ve run into this exact frustrating issue with Mocha, TypeScript, and VSCode debugging—let’s break down what’s going on and how to fix it.

First, Let’s Recap Your Setup #

Your test code looks solid:

import { expect } from 'chai';
describe('test', () => {
  it('compiles', () => {
    expect(true).is.true;
  });
});

And your npm test script works because it uses both esm and ts-node/register to handle ESM imports and TypeScript compilation:

"test": "mocha -r esm -r ts-node/register test/**/Test*.ts"

The Debugging Headache #

Your VSCode launch config works once (after running npm run test), but after editing test code, you get TypeScript syntax errors about colons. Remove esm and you hit import { syntax errors instead. Here’s why this happens:

The core problem is a conflict between the legacy ts-node/register (built for CommonJS) and the esm module loader. When you run npm run test first, ts-node caches compiled JS files—but when you edit your TS code, the debug setup either loads stale cached files or tries to run raw TS with mismatched loader rules, causing those weird syntax errors.

Here Are the Fixes That Work #

1. Switch to ts-node’s ESM-Native Loader (Best Solution) #

Ditch the separate esm loader and use ts-node/esm instead—it’s built to handle ESM natively with TypeScript, eliminating the loader conflict entirely.

Update your VSCode launch config’s args section to this:

"args": [
  "--require", "ts-node/esm",
  "--timeout", "999999",
  "--colors",
  "${workspaceFolder}/test/**/Test*.ts"
],

To make this stick, add "type": "module" to your package.json to enforce ESM across your project, and tweak your tsconfig.json to support ESM:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES6"
  },
  "include": ["test/**/*"]
}

2. Clear ts-node Cache Before Each Debug Run (Quick Fix) #

If you need to keep using your original loader setup, add a pre-debug task to clear the ts-node cache so stale compiled files don’t cause issues after edits.

First, create a .vscode/tasks.json file:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Clear ts-node Cache",
      "type": "shell",
      "command": "rm -rf ./node_modules/.cache/ts-node"
    }
  ]
}

Then update your launch config to run this task before debugging:

{
  "type": "node",
  "request": "launch",
  "name": "Mocha Tests",
  "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
  "args": [
    "--require", "esm",
    "--require", "ts-node/register",
    "--timeout", "999999",
    "--colors",
    "${workspaceFolder}/test/**/Test*.ts"
  ],
  "preLaunchTask": "Clear ts-node Cache",
  "internalConsoleOptions": "openOnSessionStart"
}

3. Double-Check Your File Globs #

Quick sanity check: your npm script uses Test*.t.ts but your debug config uses Test*.ts—make sure these globs match, otherwise you might be loading uncompiled files accidentally.

Why This Works #

Using ts-node/esm aligns TypeScript compilation with ESM module handling from the start, so there’s no conflict when files change. Clearing the cache ensures you’re always running fresh compiled code, which fixes the stale file issue.

内容的提问来源于stack exchange，提问作者Mise