{"id":14252,"library":"vscode-test-adapter-api","title":"VS Code Test Adapter API","description":"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.","status":"maintenance","version":"1.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/hbenl/vscode-test-adapter-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install vscode-test-adapter-api","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-test-adapter-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-test-adapter-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for any VS Code extension; provides core APIs like EventEmitter and ExtensionContext.","package":"vscode","optional":false},{"reason":"Common utility library for boilerplate tasks like logging and streamlined adapter registration with Test Explorer UI.","package":"vscode-test-adapter-util","optional":true}],"imports":[{"note":"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.","wrong":"const { TestHub } = require('vscode-test-adapter-api');","symbol":"TestHub, testExplorerExtensionId","correct":"import { TestHub, testExplorerExtensionId } from 'vscode-test-adapter-api';"},{"note":"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.","wrong":"import TestAdapter from 'vscode-test-adapter-api';","symbol":"TestAdapter","correct":"import { TestAdapter } from 'vscode-test-adapter-api';"},{"note":"These are specific TypeScript interface types defining the structure of events emitted by the test adapter. Always use named imports for these types.","wrong":"import * as TestEvents from 'vscode-test-adapter-api';","symbol":"TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestEvent","correct":"import { TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestEvent } from 'vscode-test-adapter-api';"}],"quickstart":{"code":"import * as vscode from 'vscode';\nimport { TestHub, testExplorerExtensionId, TestAdapter, TestLoadStartedEvent, TestLoadFinishedEvent, TestRunStartedEvent, TestSuiteEvent, TestEvent, RetireEvent } from 'vscode-test-adapter-api';\nimport { TestAdapterRegistrar } from 'vscode-test-adapter-util';\n\n// A minimal example of a TestAdapter implementation\nclass MyTestAdapter implements TestAdapter {\n    private readonly testsEmitter = new vscode.EventEmitter<TestLoadStartedEvent | TestLoadFinishedEvent>();\n    private readonly testStatesEmitter = new vscode.EventEmitter<TestRunStartedEvent | TestRunFinishedEvent | TestSuiteEvent | TestEvent>();\n    private readonly retireEmitter = new vscode.EventEmitter<RetireEvent>();\n\n    // Required constructor by TestAdapterRegistrar\n    constructor(public readonly workspaceFolder: vscode.WorkspaceFolder) { }\n\n    get tests(): vscode.Event<TestLoadStartedEvent | TestLoadFinishedEvent> { return this.testsEmitter.event; }\n    get testStates(): vscode.Event<TestRunStartedEvent | TestRunFinishedEvent | TestSuiteEvent | TestEvent> { return this.testStatesEmitter.event; }\n    get retire(): vscode.Event<RetireEvent> { return this.retireEmitter.event; }\n\n    async load(): Promise<void> {\n        this.testsEmitter.fire({ type: 'started' });\n        // Simulate loading tests\n        await new Promise(resolve => setTimeout(resolve, 500));\n        console.log(`Loading tests for ${this.workspaceFolder.name}`);\n        // In a real adapter, you'd parse test files and build a test suite structure.\n        this.testsEmitter.fire({ type: 'finished', suite: { id: 'root', label: 'My Tests', type: 'suite', children: [] } });\n        this.retireEmitter.fire({}); // Mark tests as retired after loading\n    }\n\n    async run(tests: string[]): Promise<void> {\n        this.testStatesEmitter.fire({ type: 'started', tests });\n        console.log(`Running tests: ${tests.join(', ')}`);\n        await new Promise(resolve => setTimeout(resolve, 1000));\n        this.testStatesEmitter.fire({ type: 'finished' });\n    }\n\n    async debug(tests: string[]): Promise<void> { /* Implement debug logic */ }\n    cancel(): void { /* Implement cancellation logic */ }\n\n    dispose(): void {\n        this.testsEmitter.dispose();\n        this.testStatesEmitter.dispose();\n        this.retireEmitter.dispose();\n        console.log(`Disposed adapter for ${this.workspaceFolder.name}`);\n    }\n}\n\nexport function activate(context: vscode.ExtensionContext) {\n\n    const testExplorerExtension = vscode.extensions.getExtension<TestHub>(testExplorerExtensionId);\n\n    if (testExplorerExtension) {\n        const testHub = testExplorerExtension.exports;\n        context.subscriptions.push(new TestAdapterRegistrar(\n            testHub,\n            workspaceFolder => new MyTestAdapter(workspaceFolder)\n        ));\n        console.log('Test Adapter registered successfully.');\n    } else {\n        console.warn('VS Code Test Explorer extension not found, Test Adapter will not be registered.');\n    }\n}\n\nexport function deactivate() { \n    console.log('Extension deactivated.');\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Test 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Core 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.9.0':60 'abstract':89 'adapt':4,10,21,109,118 'api':5,11,17,72,77,130 'away':90 'code':2,27,53,68,140 'common':112 'compat':148 'complex':91 'conjunct':104 'current':56 'defin':32 'deprec':133 'develop':19 'direct':49 'effect':64 'experi':142 'explor':29,84,97,122 'extens':30,86,124 'favor':135 'foundat':15 'framework':48 'howev':61 'integr':23 'interact':93 'interfac':34 'introduc':73 'javascript':149 'like':114 'load':39 'log':115 'maintain':146 'nativ':70,138 'necessari':37 'often':101 'packag':12 'primarili':79 'provid':13 'registr':119 'reli':127 'remain':145 'report':42 'result':44 'run':40 'stabl':57 'streamlin':117 'supersed':65 'task':113 'test':3,9,20,28,43,47,71,83,96,108,121,141 'though':143 'type':36 'typescript':16,150 'ui':54,85,98,123 'use':80,102 'util':110 'v1.59':75 'various':46 'version':58 'vs':1,26,52,67,139 'vscode':8,107 'vscode-test-adapter-api':7 'vscode-test-adapter-util':106 'within':50","created_at":"2026-04-20T01:58:44.121496+00:00","updated_at":"2026-04-20T01:58:44.121496+00:00","problems":[{"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`).","cause":"The 'vscode' module, containing core VS Code APIs like EventEmitter, is not properly imported or its types are missing.","error":"Cannot find name 'vscode'. Did you mean 'code'?"},{"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.","cause":"Your custom test adapter class (e.g., `MyTestAdapter`) does not fully implement all required properties or methods of the `TestAdapter` interface.","error":"Argument of type 'MyTestAdapter' is not assignable to parameter of type 'TestAdapter'. Property 'tests' is missing in type 'MyTestAdapter' but required in type 'TestAdapter'."},{"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.","cause":"The `testExplorerExtension` might be `undefined` (extension not installed/activated) or its `exports` property is being accessed incorrectly or before the extension has fully activated.","error":"Property 'exports' does not exist on type 'Extension<any>'."},{"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.","cause":"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.","error":"TypeError: testHub.registerTestAdapter is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/hbenl/vscode-test-adapter-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vscode-test-adapter-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}