← Back to DevBytes
Testing August 14, 2026 7 min read

VS Code Testing Integration: Complete Guide

VS Code Testing Integration: Complete Guide

Visual Studio Code ships with a powerful, first-class Testing API that unifies how tests are discovered, run, debugged, and reported across any language ecosystem. Instead of juggling terminal output and editor windows, developers can stay inside VS Code and interact with their test suites through a dedicated Test Explorer, inline gutter decorations, and rich failure diagnostics. This guide walks through everything you need to know to leverage, configure, and extend VS Code's testing integration.

What Is VS Code Testing Integration?

VS Code Testing Integration is a built-in framework—introduced in VS Code 1.59 and stabilized shortly after—that provides a standardized UI and API for working with tests. It consists of three main pieces: the Test Explorer view, the Test Results panel, and the Testing Extension API. Language extensions (such as the Python, JavaScript/TypeScript, Java, and C++ extensions) implement the API to feed test data into VS Code, which then renders a unified experience regardless of the underlying test runner.

The core concepts include:

Why Testing Integration Matters

Before native testing support, developers relied on terminal output, external panels, or third-party extensions with inconsistent UX. Native integration matters because it:

Using the Built-in Test Explorer

Open the Testing view from the Activity Bar (the flask icon) or via the Command Palette with Testing: Focus on Testing View. The view displays a hierarchical tree of all tests discovered by installed extensions. Each node has inline actions for running and debugging, and you can use the toolbar to run all tests, run filtered tests, or re-run the last execution.

Key interactions include:

Configuring Test Profiles

Test profiles let you switch between run modes and configurations. For example, the Python extension exposes profiles for running pytest, unittest, and debugging. You can configure these in settings.json:

{
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": [
    "tests",
    "-k",
    "not slow"
  ],
  "python.testing.autoTestDiscoverOnSaveEnabled": true
}

For JavaScript and TypeScript projects using Jest, the Jest extension auto-discovers tests but you can fine-tune behavior:

{
  "jest.autoRun": {
    "watch": true,
    "onSave": "test-src-file"
  },
  "jest.testExplorer": {
    "enabled": true,
    "showInlineError": true
  }
}

Running and Debugging Tests

Once tests are discovered, running them is a single click. To debug, click the bug icon next to a test instead of the play icon. VS Code launches the test under the debugger, honoring breakpoints set in both test files and source files. For custom launch behavior, you can define a launch.json configuration. Here's an example for Node.js with Mocha:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Mocha Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
      "args": [
        "--reporter",
        "spec",
        "--timeout",
        "5000",
        "${workspaceFolder}/test/**/*.spec.js"
      ],
      "internalConsoleOptions": "openOnSessionStart",
      "skipFiles": ["/**"]
    }
  ]
}

For Python pytest debugging, the Python extension generates a temporary debug configuration automatically, but you can also define one explicitly:

{
  "name": "Debug pytest",
  "type": "debugpy",
  "request": "launch",
  "module": "pytest",
  "args": ["-x", "${file}"],
  "console": "integratedTerminal",
  "justMyCode": true
}

Continuous and Watch Mode Testing

Continuous testing re-runs relevant tests whenever files change. This is invaluable for tight feedback loops during development. Enable it per-profile by toggling the watch icon in the Testing view toolbar, or configure it globally:

{
  "testing.automaticallyOpenPeekView": "failureOnVisibleFiles",
  "testing.automaticallyOpenTestResults": "openOnTestStart",
  "testing.followRunningTest": true
}

For Jest, watch mode is built in. For pytest, use pytest-watch alongside the Python extension's auto-run on save setting:

pip install pytest-watch
ptw -- -x --testmon

Building a Custom Test Controller Extension

If you're working with a niche framework or an in-house test runner, you can build your own test controller using the vscode Testing API. Below is a minimal example that registers a controller, creates test items, and runs them.

const vscode = require('vscode');

function activate(context) {
  const controller = vscode.tests.createTestController(
    'myFrameworkTests',
    'My Framework Tests'
  );

  // Create a test profile for running tests
  controller.createRunProfile(
    'Run',
    vscode.TestRunProfileKind.Run,
    (request, token) => runTests(controller, request, token),
    true
  );

  // Create a test profile for debugging tests
  controller.createRunProfile(
    'Debug',
    vscode.TestRunProfileKind.Debug,
    (request, token => runTests(controller, request, token, true)),
    true
  );

  // Discover tests (simplified example)
  const fileUri = vscode.Uri.file('/project/tests/sample.test.js');
  const testItem = controller.createTestItem(
    'sample-test',
    'sample test',
    fileUri
  );
  testItem.range = new vscode.Range(0, 0, 10, 0);
  controller.items.add(testItem);

  context.subscriptions.push(controller);
}

async function runTests(controller, request, token, debug = false) {
  const run = controller.createTestRun(request);
  const queue = [];

  // Collect tests to run
  if (request.include) {
    request.include.forEach(test => queue.push(test));
  } else {
    controller.items.forEach(test => queue.push(test));
  }

  for (const test of queue) {
    if (token.isCancellationRequested) {
      run.skipped(test);
      continue;
    }
    run.started(test);
    try {
      const passed = await executeTest(test, debug);
      if (passed) {
        run.passed(test, 100);
      } else {
        const message = new vscode.TestMessage('Test failed: assertion mismatch');
        message.location = new vscode.Location(
          test.uri,
          new vscode.Position(2, 0)
        );
        run.failed(test, message);
      }
    } catch (err) {
      run.errored(test, new vscode.TestMessage(err.message));
    }
  }

  run.end();
}

async function executeTest(test, debug) {
  // Replace with actual test execution logic
  return true;
}

function deactivate() {}

module.exports = { activate, deactivate };

The package.json for this extension must declare the testing contribution:

{
  "name": "my-framework-test-provider",
  "version": "0.1.0",
  "engines": { "vscode": "^1.80.0" },
  "activationEvents": ["onLanguage:javascript"],
  "main": "./extension.js",
  "contributes": {
    "commands": [
      {
        "command": "myFramework.refreshTests",
        "title": "Refresh My Framework Tests"
      }
    ]
  },
  "dependencies": {}
}

Handling Test Discovery Dynamically

Real-world controllers usually discover tests by scanning files or querying the test runner. Use file system watchers to refresh discovery when files change:

const watcher = vscode.workspace.createFileSystemWatcher(
  '**/*.test.js'
);

watcher.onDidCreate(uri => refreshDiscovery(controller, uri));
watcher.onDidChange(uri => refreshDiscovery(controller, uri));
watcher.onDidDelete(uri => removeTestItem(controller, uri));

context.subscriptions.push(watcher);

async function refreshDiscovery(controller, uri) {
  const document = await vscode.workspace.openTextDocument(uri);
  const testItems = parseTestsFromDocument(document);
  testItems.forEach(item => controller.items.add(item));
}

function parseTestsFromDocument(document) {
  const items = [];
  const regex = /it\(['"`](.+?)['"`]/g;
  let match;
  while ((match = regex.exec(document.getText())) !== null) {
    const line = document.positionAt(match.index).line;
    const id = `${document.uri.toString()}#${match[1]}`;
    const item = controller.createTestItem(id, match[1], document.uri);
    item.range = new vscode.Range(line, 0, line, match[0].length);
    items.push(item);
  }
  return items;
}

Best Practices

Useful Settings Reference

{
  "testing.autoRun.mode": "allInSubtree",
  "testing.autoRun.delay": 1000,
  "testing.automaticallyOpenPeekView": "failureOnVisibleFiles",
  "testing.automaticallyOpenTestResults": "openOnTestStart",
  "testing.defaultGutterClickAction": "run",
  "testing.displayedItemCount": 100,
  "testing.followRunningTest": true,
  "testing.saveBeforeTest": true,
  "testing.showAllMessages": false
}

Troubleshooting Common Issues

Conclusion

VS Code's Testing Integration transforms the editor into a unified testing hub, eliminating the friction of switching between terminals, browser windows, and IDE panels. Whether you're consuming built-in support for popular frameworks like pytest, Jest, and JUnit, or building a custom controller for an in-house runner, the Testing API offers a consistent, debugger-aware, and highly responsive experience. By following the configuration patterns and best practices outlined in this guide—fast discovery, incremental progress reporting, accurate failure locations, and thoughtful auto-run settings—you can build a testing workflow that keeps developers in flow and surfaces regressions the moment they happen.

— Ad —

Google AdSense will appear here after approval

← Back to all articles