Registry /
testing / vscode-test-adapter-api
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
muslnode 18–226 runs
build_error
glibcnode 18–226 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.');
}
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.
fixAdd `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.
fixReview 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.
fixAlways 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.
fixVerify 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.
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.