{"id":15390,"date":"2024-04-12T00:00:00","date_gmt":"2024-04-12T07:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/ise\/?p=15390"},"modified":"2024-11-03T23:45:32","modified_gmt":"2024-11-04T07:45:32","slug":"testing-vscode-extensions-with-typescript","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/ise\/testing-vscode-extensions-with-typescript\/","title":{"rendered":"Testing VSCode Extensions with TypeScript"},"content":{"rendered":"

Introduction<\/h2>\n

Many of the popular Visual Studio (VS) Code extensions like prettier<\/a> or docker<\/a> lack any true unit tests, which can be run without the vscode<\/code> dependency.\nIn fact, in taking a look at many other extensions and samples, nearly all are missing true unit tests.\nAccording to the VS Code Testing Extensions documentation<\/a>, the way VS Code recommends running and debugging tests for extensions is solely through integration tests that utilize a special test instance of VS Code, the Extension Development Host.\nExtensions can then use this instance of VS Code to write integration and some form of “unit” tests in this environment.\nHowever, true unit tests are required for an extension, which should be runnable without a VS Code instance, VS Code provides no resources or guidance in this case.\nThis poses a problem when it is necessary to create production quality code that adheres to strict engineering fundamentals, which require unit tests covering the majority of all components (>90% if possible).\nThis blog will explore potential solutions to this issue and how teams can write sufficient unit tests for their VS Code extensions.<\/p>\n

Potential Solutions<\/h2>\n

Under normal circumstances, relying on a dependency should certainly not be a problem for unit testing; the dependency can be mocked using a number of different frameworks.\nHowever, in this case, the vscode<\/code> dependency does not exist as a normal dependency and is not listed in the dependencies<\/code> member of the package.json<\/code>, but rather the engines<\/code> field<\/a>.\nThus, if the vscode<\/code> Application Programming Interface (API) is mocked as shown below using normal TypeScript Unit Tests with the Jest Framework<\/a>, a Cannot find module 'vscode' from 'src\/tests\/test1.ts'<\/code> error will appear on the import<\/code> statement:<\/p>\n

\/\/ src\/tests\/commands\/command1.test.ts\r\nimport * as vscode from 'vscode';\r\n...\r\n\/\/ mock a part of the vscode API used\r\nvscode.window.showInformationMessage = jest.fn()<\/code><\/pre>\n
To address the above issue of mocking the vscode<\/code> API while it not being a normal node dependency, there are at least two viable solutions.<\/p>\n
Option 1: Wrap the VS Code API<\/h3>\n
Option 1 is to wrap all methods of the vscode<\/code> API with different classes, as follows:<\/p>\n
\/\/ src\/vscode\/windowApi.ts\r\nimport * as vscode from 'vscode';\r\n\r\nexport class WindowAPI {\r\n  ...\r\n  showInformationMessage(message: string): void {\r\n    vscode.window.showInformationMessage(message);\r\n  }\r\n  ...\r\n}<\/code><\/pre>\n
These wrapper classes can then be injected into other classes as needed:<\/p>\n
\/\/ src\/commands\/command1.ts\r\n\r\nexport class Command1 {\r\n  constructor(windowApi: WindowAPI, ...) {\r\n\r\n  }\r\n  ...\r\n  run() {\r\n    ...\r\n    this.windowApi.showInformationMessage('Hello World!');\r\n  }\r\n  ...\r\n}<\/code><\/pre>\n
Then when unit testing, these wrapper classes can be mocked, injected into the constructor of the unit of code under test, and tests can run without issue since the unit under test depends on the abstraction layer above the vscode<\/code> API, and not the vscode<\/code> API itself.<\/p>\n
Unfortunately, this means that all calls to the vscode<\/code> API must be wrapped in new classes and it would not be possible to unit test them since they’d still depend on calls to the vscode<\/code> API.\nCare must also be taken to wrap the methods as closely as possible as to not lose or change functionality.<\/p>\n
Option 2: Use Jest Manual Mocks<\/h3>\n
Option 2 involves taking advantage of Jest Manual Mocks<\/a> to mock the utilized vscode<\/code> API.\nFollowing the JavaScript process outlined in this blog post<\/a>, the same can be done in TypeScript. All the basic mocks of each part of the vscode<\/code> API used in the source code can be created and placed in the __mocks__\/vscode.ts<\/code> file:<\/p>\n
\/\/ __mocks__\/vscode.ts\r\nconst mockWindow = {\r\n  showInformationMessage: jest.fn(),\r\n  ...\r\n};\r\n...\r\nconst vscode = {\r\n  window: mockWindow,\r\n  ...\r\n}\r\n\r\nmodule.exports = vscode;<\/code><\/pre>\n
In the test code, these mocks can then be overridden to provide specific functionality to that test case:<\/p>\n
\/\/ src\/tests\/commands\/command1.test.ts\r\n...\r\nvscode.Uri.parse = jest.fn().mockReturnValue(mockUri);\r\n...<\/code><\/pre>\n
Assertions can also be made against particular mocked items as required:<\/p>\n
\/\/ src\/test\/command1.test.ts\r\n...\r\nexpect(vscode.Uri.parse).toBeCalled();\r\nexpect(vscode.window.showInformationMessage).toBeCalledWith('Hello World!');\r\n...<\/code><\/pre>\n
NOTE: make sure mocks are cleared after each test by using jest.clearAllMocks()<\/code> in an afterEach<\/code> block:<\/p>\n
afterEach(() => {\r\n  jest.clearAllMocks();\r\n});<\/code><\/pre>\n<\/blockquote>\n
One issue using this method arises when a class inherits from a vscode<\/code> class.\nBecause the vscode<\/code> API is manually mocked, the base class constructor and members will not exist.\nA workaround is then needed to test these concrete classes.<\/p>\n
For instance, the following excerpt from Microsoft’s vscode source code<\/a> shows a concrete class that extends a vscode<\/code> class.<\/p>\n
\/*---------------------------------------------------------------------------------------------\r\n *  Copyright (c) Microsoft Corporation. All rights reserved.\r\n *  Licensed under the MIT License. See License.txt in the project root for license information.\r\n *--------------------------------------------------------------------------------------------*\/\r\nimport * as vscode from 'vscode';\r\n\r\nexport class UriEventHandler extends vscode.EventEmitter<vscode.Uri> implements vscode.UriHandler {\r\n  public handleUri(uri: vscode.Uri) {\r\n    this.fire(uri);\r\n  }\r\n}<\/code><\/pre>\n
In order to test this class and assert on the this.fire(uri)<\/code> method in the tests, an EventEmitter<\/code> “mock” implementation would need to be added to the rest of the mocks:<\/p>\n
\/\/ __mocks__\/vscode.ts\r\n\r\n\/\/ Because we extend the EventEmitter Class we have to create this \"mocked\" EventEmitter Class\r\nclass EventEmitter {\r\n  event = jest.fn();\r\n  fire: () => void = jest.fn();\r\n  dispose: () => void = jest.fn();\r\n}\r\n\r\n...\r\n\r\nconst vscode = {\r\n  EventEmitter,\r\n  ...\r\n}\r\n\r\nmodule.exports = vscode;<\/code><\/pre>\n
Other VS Code Testing Solutions<\/h3>\n
Even though VS Code provides guidance for integration testing using their special instance of VS Code, in some cases this is not enough to perform sufficient integration tests.\nFor example, when it is necessary to get<\/em> (rather than set<\/em>) some data, like a custom context or the content of an information message, from the vscode<\/code> API.\nHowever, both of these cases are not possible, as there are no vscode<\/code> API methods to get<\/em> this data.\nIn these cases, it is not possible to complete sufficient integration tests as the ability to verify certain results that come from the vscode<\/code> API is missing.\nA potential workaround found was to use an end-to-end (e2e) user-interface (UI) testing framework, such as vscode-extension-tester<\/a>, to achieve the test coverage desired.<\/p>\n
The example below uses the vscode-extension-tester<\/code> to open an extension’s treeview, check the content, and click a treeview item – all things that cannot be done solely via integration tests in the special VS Code instance.<\/p>\n
  import { ActivityBar, VSBrowser, WebDriver, ModalDialog, SideBarView, By } from 'vscode-extension-tester';\r\n\r\n  ...\r\n\r\n  \/\/ Opens extension's custom side bar view\r\n  sideBarView = await (await new ActivityBar().getViewControl('MyExtension'))?.openView();\r\n  \/\/ get access to the Treeview Section named 'General'\r\n  const treeview = await sideBarView!.getContent().getSection('General');\r\n  const title = await treeview.getTitle();\r\n  assert.strictEqual(title, 'General');\r\n  \/\/ Click treeview item that opens Google\r\n  await driver.wait(async () => await treeview.openItem('General', 'Google'), 2000);\r\n  const dialog = new ModalDialog();\r\n  const message = await dialog.getMessage();\r\n  assert.strictEqual(message, 'Do you want Code to open the external website?');\r\n  const details = await dialog.getDetails();\r\n  assert.strictEqual(details, 'https:\/\/www.bing.com\/');\r\n  await dialog.pushButton('Cancel');<\/code><\/pre>\n
Final Thoughts<\/h2>\n
Testing extensions for VS Code poses a lot of challenges.\nThere are not many resources on the topic and often the testing approach VS Code recommends (utilizing the Extension Development Host) falls short of the testing requirements needed for a production-quality extension.\nThis blog post can hopefully help fill in some of the gaps and provided a good starting point for thoroughly testing VS Code extensions.<\/p>\n
Related Resources<\/h2>\n