How to configure source maps when using Jest within Visual Studio Code debugger

When using Visual Studio Code (VS Code) for Jest testing, configuring source maps is an essential step, as it enables you to debug directly against the source code rather than the compiled code. Below are the steps to configure source maps:

1. Install Required Extensions

First, ensure that you have installed the VS Code extensions related to Jest, such as the official Jest extension. These extensions typically simplify the integration and usage of Jest.

2. Create the Jest Configuration File

Create a Jest configuration file (if it doesn't exist) in the project root directory, such as jest.config.js. In this configuration file, ensure that sourceMap is enabled. While this is typically enabled by default, it's best to verify.

javascript
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  // Ensure sourceMap is enabled
  globals: {
    'ts-jest': {
      diagnostics: false,
      tsconfig: 'tsconfig.json'
    }
  }
};

3. Configure VS Code's Debugging Settings

Next, configure the debugging settings in VS Code. Create or edit the launch.json file in the .vscode folder of your project. This file instructs VS Code on how to launch the debugger and run Jest tests.

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Jest Tests",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": ["--runInBand", "--config=jest.config.js"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "disableOptimisticBPs": true,
      "windows": {
        "program": "${workspaceFolder}/node_modules/jest/bin/jest.js"
      },
      "sourceMaps": true,
      "smartStep": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

4. Ensure TypeScript Configuration is Correct

If your project uses TypeScript, ensure that sourceMap is enabled in your tsconfig.json. This ensures that the TypeScript compiler generates JavaScript code with source maps attached.

json
{
  "compilerOptions": {
    "sourceMap": true,
    // Other configurations...
  }
}

5. Start Debugging

After configuring all these settings, you can set breakpoints in VS Code and start debugging by selecting the 'Debug Jest Tests' configuration from the debug panel. Now, when Jest tests hit a breakpoint, VS Code will be able to use source maps to correctly map to the TypeScript source code.

Example Explanation:

Suppose you have set a breakpoint in a function that calculates the sum of two numbers, defined as follows:

typescript
function add(a: number, b: number): number {
  return a + b;
}

test('adds 1 + 2 to equal 3', () => {
  expect(add(1, 2)).toBe(3);
});

Set a breakpoint on the return statement of the add function. After launching the test debugging with the above configuration, VS Code will correctly pause at the breakpoint location in the TypeScript file, rather than in the compiled JavaScript file.

By following these steps, you can effectively debug at the source code level using Jest in VS Code, significantly improving development and debugging efficiency.