Registry / testing / vscode-test-adapter-api

vscode-test-adapter-api

JSON →
library1.9.0jsnpmunverified

The `vscode-test-adapter-api` package provides the foundational TypeScript API for developing test adapters that integrate with the VS Code Test Explorer extension. It defines the interfaces and types necessary for loading, running, and reporting test results from various test frameworks directly within the VS Code UI. The current stable version is 1.9.0, however, it is effectively superseded by VS Code's native Testing API introduced in v1.59. This API was primarily used for the `Test Explorer UI` extension. While it abstracts away complexities of interacting with the Test Explorer UI, it's often used in conjunction with `vscode-test-adapter-util` for common tasks like logging and streamlined adapter registration. The `Test Explorer UI` extension itself, which relies on this API, is now deprecated in favor of the native VS Code testing experience, though it remains maintained for compatibility.

npm install vscode-test-adapter-api
INSTALL
IMPORT
SIG · VSCODE-TEST-ADAPTE
V
vscode-test-adapter-api
testingjavascriptv1.9.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TestHub, testExplorerExtensionId
import { TestHub, testExplorerExtensionId } from 'vscode-test-adapter-api';
const { TestHub } = require('vscode-test-adapter-api');
These are crucial for obtaining and interacting with the Test Explorer UI's hub. Primarily used in TypeScript-based VS Code extensions that target the deprecated Test Explorer UI.
TestAdapter
import { TestAdapter } from 'vscode-test-adapter-api';
import TestAdapter from 'vscode-test-adapter-api';
This interface defines the contract that your test adapter class must implement to integrate with the Test Explorer UI. It is a named export, not a default one.
TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestEvent
import { TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestEvent } from 'vscode-test-adapter-api';
import * as TestEvents from 'vscode-test-adapter-api';
These are specific TypeScript interface types defining the structure of events emitted by the test adapter. Always use named imports for these types.

This quickstart demonstrates how to activate a VS Code extension, locate the `Test Explorer UI` extension, and register a basic test adapter using `TestAdapterRegistrar` from `vscode-test-adapter-util`. It includes a minimal `MyTestAdapter` class demonstrating essential event emission and the `dispose` method.

import * as vscode from 'vscode'; import { TestHub, testExplorerExtensionId, TestAdapter, TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestSuiteEvent, TestEvent, RetireEvent } from 'vscode-test-adapter-api'; import { TestAdapterRegistrar } from 'vscode-test-adapter-util'; // A minimal example of a TestAdapter implementation class MyTestAdapter implements TestAdapter { private readonly testsEmitter = new vscode.EventEmitter<TestLoadStartedEvent | TestLoadFinishedEvent>(); private readonly testStatesEmitter = new vscode.EventEmitter<TestRunStartedEvent | TestRunFinishedEvent | TestSuiteEvent | TestEvent>(); private readonly retireEmitter = new vscode.EventEmitter<RetireEvent>(); // Required constructor by TestAdapterRegistrar constructor(public readonly workspaceFolder: vscode.WorkspaceFolder) { } get tests(): vscode.Event<TestLoadStartedEvent | TestLoadFinishedEvent> { return this.testsEmitter.event; } get testStates(): vscode.Event<TestRunStartedEvent | TestRunFinishedEvent | TestSuiteEvent | TestEvent> { return this.testStatesEmitter.event; } get retire(): vscode.Event<RetireEvent> { return this.retireEmitter.event; } async load(): Promise<void> { this.testsEmitter.fire({ type: 'started' }); // Simulate loading tests await new Promise(resolve => setTimeout(resolve, 500)); console.log(`Loading tests for ${this.workspaceFolder.name}`); // In a real adapter, you'd parse test files and build a test suite structure. this.testsEmitter.fire({ type: 'finished', suite: { id: 'root', label: 'My Tests', type: 'suite', children: [] } }); this.retireEmitter.fire({}); // Mark tests as retired after loading } async run(tests: string[]): Promise<void> { this.testStatesEmitter.fire({ type: 'started', tests }); console.log(`Running tests: ${tests.join(', ')}`); await new Promise(resolve => setTimeout(resolve, 1000)); this.testStatesEmitter.fire({ type: 'finished' }); } async debug(tests: string[]): Promise<void> { /* Implement debug logic */ } cancel(): void { /* Implement cancellation logic */ } dispose(): void { this.testsEmitter.dispose(); this.testStatesEmitter.dispose(); this.retireEmitter.dispose(); console.log(`Disposed adapter for ${this.workspaceFolder.name}`); } } export function activate(context: vscode.ExtensionContext) { const testExplorerExtension = vscode.extensions.getExtension<TestHub>(testExplorerExtensionId); if (testExplorerExtension) { const testHub = testExplorerExtension.exports; context.subscriptions.push(new TestAdapterRegistrar( testHub, workspaceFolder => new MyTestAdapter(workspaceFolder) )); console.log('Test Adapter registered successfully.'); } else { console.warn('VS Code Test Explorer extension not found, Test Adapter will not be registered.'); } } export function deactivate() { console.log('Extension deactivated.'); }
Debug
Known issues
deprecatedThe `Test Explorer UI` extension and its `vscode-test-adapter-api` are officially deprecated in favor of VS Code's native Testing API (available since v1.59). While maintained, no new major features will be added. New testing extensions should use the native API directly.
fix
For new extensions, use `vscode.tests.createTestController()` and related native VS Code Testing APIs. For existing extensions, consider migrating to the native API for richer features and better efficiency.
affects: >=1.0.0
breakingVersion 2.0.0 introduced significant changes to several core `TestAdapter` methods and event interfaces, primarily by adding `testRunId` and `loadId` parameters for better correlation and cancellation of individual test runs/loads. Methods like `load()`, `cancel()`, and `debug()` now expect additional `Id` arguments.
fix
Update `TestAdapter` implementation to conform to the new method signatures and event types as specified in the v2 API documentation. `vscode-test-adapter-util` was also updated to reflect these changes.
affects: >=2.0.0
gotchaTest Adapters must implement and correctly call their `dispose()` method when the extension is deactivated or a workspace folder is removed. Failure to do so can lead to resource leaks and unexpected behavior in the VS Code Test Explorer. If using `TestAdapterRegistrar`, ensure its instance is added to `context.subscriptions`.
fix
Ensure your `TestAdapter` implementation includes a `dispose()` method that cleans up all resources (e.g., event emitters, file watchers). If `TestAdapterRegistrar` is used, add `context.subscriptions.push(registrarInstance)` in your `activate()` function.
affects: >=1.0.0
gotchaCore event classes like `vscode.EventEmitter` and `vscode.Event` (used for `tests`, `testStates`, `retire` properties) must be imported directly from the `vscode` module, not `vscode-test-adapter-api`. This module is implicitly available in a VS Code extension context.
fix
Always include `import * as vscode from 'vscode';` in your extension files where these classes are used. Ensure `@types/vscode` is installed for TypeScript projects.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find name 'vscode'. Did you mean 'code'?
The 'vscode' module, containing core VS Code APIs like EventEmitter, is not properly imported or its types are missing.
fix
Add `import * as vscode from 'vscode';` to the top of your TypeScript file. Ensure `@types/vscode` is installed as a dev dependency (`npm install --save-dev @types/vscode`).
Argument of type 'MyTestAdapter' is not assignable to parameter of type 'TestAdapter'. Property 'tests' is missing in type 'MyTestAdapter' but required in type 'TestAdapter'.
Your custom test adapter class (e.g., `MyTestAdapter`) does not fully implement all required properties or methods of the `TestAdapter` interface.
fix
Review the `TestAdapter` interface (from `vscode-test-adapter-api`) and ensure your class implements all its properties (`tests`, `testStates`, `retire`) and methods (`load`, `run`, `cancel`, `debug`), including their correct return types and parameters.
Property 'exports' does not exist on type 'Extension<any>'.
The `testExplorerExtension` might be `undefined` (extension not installed/activated) or its `exports` property is being accessed incorrectly or before the extension has fully activated.
fix
Always check if `testExplorerExtension` is defined before accessing its `exports`: `if (testExplorerExtension) { const testHub = testExplorerExtension.exports; ... }`. Ensure the Test Explorer UI extension (`hbenl.vscode-test-explorer`) is installed.
TypeError: testHub.registerTestAdapter is not a function
The `testHub` object obtained from `testExplorerExtension.exports` is either `undefined` or does not expose the `registerTestAdapter` method, potentially due to the Test Explorer UI extension not being fully ready or an incorrect cast.
fix
Verify that `testExplorerExtension` is correctly retrieved and that `testExplorerExtension.exports` is indeed cast to `TestHub`. Ensure the Test Explorer UI extension is enabled and up-to-date. If using `vscode-test-adapter-util`, use `TestAdapterRegistrar` as shown in the quickstart.
Upgrade
Version history
1.9.0latest on npm
Audit
Dependencies
vscoderequiredPeer dependency for any VS Code extension; provides core APIs like EventEmitter and ExtensionContext.
vscode-test-adapter-utiloptionalCommon utility library for boilerplate tasks like logging and streamlined adapter registration with Test Explorer UI.
Agent activity
11 hits · last 30 days
node
10
Resources
vscode-test-adapter-api — npm install vscode-test-adapter-api · libregistry