vscode插件开发之 - TestController

 TesController概要介绍

 TestController 组件是用于实现自定义测试框架和集成测试结果的。它允许开发者定义自己的测试运行器，以支持在VSCode中运行和展示测试。以下是一些使用 TestController 组件的主要场景：

自定义测试框架：如果你正在开发或使用一个非标准的测试框架，你可以使用 TestController 来集成这个框架的测试结果。

语言特定的测试：对于某些语言或框架，VSCode可能没有内置的测试支持。使用 TestController，你可以为这些语言或框架添加测试支持。

集成外部测试工具：如果你需要在VSCode中展示由外部测试工具生成的测试结果，TestController 可以用来映射这些结果到VSCode的测试UI。

测试结果可视化：通过 TestController，你可以控制测试结果如何在VSCode的测试面板中展示，包括测试的通过、失败、跳过等状态。

如何开发一款自定义的测试框架插件

  要开发一款基于vscode的自定义测试框架非常简单，有三个步骤。以读取markdown中的代码，执行测试为例子来看看如何自定义测试框架插件

步骤一：解析文档中内容，并将结果添加到testcontroller的testItem对象

  下面的代码中，对给定的文档内容通过正则表达式进行match，获取到markdown文件中的测试name，experssion,expected内容，并将parse出来的内容用于构建TestItem。下图图一假设是文本上的代码内容，下图图二是parse出来的Test对象内容。

function loadTestsFromDocument(testController: vscode.TestController, document: vscode.TextDocument) {const tests = parseTests(document.getText());for (const test of tests) {const testItem = testController.createTestItem(test.name, test.expression + "=" + test.expected);testController.items.add(testItem);}
}interface Test {name: string;expression: string;expected: number;
}function parseTests(text: string): Test[] {const testRegex = /^(\d+ \+ \d+) = (\d+) \/\/ (.+)$/gm;const tests: Test[] = [];let match;while ((match = testRegex.exec(text)) !== null) {tests.push({name: match[3],expression: match[1],expected: parseInt(match[2])});}return tests;
}

  上述代码中，TestController.createTestItem 方法用于创建一个新的 TestItem，它代表一个测试用例。以下是 createTestItem 方法的一些关键参数和它们的说明：输入参数：
id (string): 测试用例的唯一标识符。这里是用Test.name作为id
label (string): 测试用例的显示名称，通常在UI中展示给用户。这里是组装成的label信息，后面要通过解析label信息来执行测试。testItem.label=test.expression + "=" + test.expected
uri (vscode.Uri): 表示测试用例所属文件的位置。通常使用当前编辑器的文档URI。
range (vscode.Range): 测试用例在文件中的位置范围。这有助于用户快速定位到测试用例的代码。
children (TestItem[], optional): 如果这个测试用例是一个容器，比如一个测试套件，你可以在这里提供子测试用例的数组。
tags (string[], optional): 一组标签，可以用来对测试用例进行分类或标记。

步骤二：自定义测试执行逻辑

  下面定义了一个简单的runTest逻辑，通过解析testItem.label信息，判断expected和actual的值是否相等来判断测试执行结果。

async function runTest(testItem: vscode.TestItem) {const expression = testItem.label.split('=')[0].trim();const expected = parseInt(testItem.label.split('=')[1].trim());const actual = eval(expression);const result = actual === expected;if (result) {testItem.busy = false;return `${testItem.label}: PASSED`;} else {testItem.busy = false;return `${testItem.label}: FAILED`;}
}

步骤三：注册命令执行测试

  定义好前面的内容后，就可以注册命令，将testController.items的内容转换成数组，在逐个执行runTest方法，并把执行结果通过showInfomationMessage显示出来。

        vscode.commands.registerCommand('markdownTestController.runTests', async () => {const tests = Array.from(testController.items)const results: string[] = [];for (const [, testItem] of tests) {vscode.window.showInformationMessage(JSON.stringify(testItem));const resultMessage = await runTest(testItem);results.push(resultMessage);}if (results.length > 0) {vscode.window.showInformationMessage(results.join('\n'));} else {vscode.window.showInformationMessage('No tests executed.');}});
}

  编写好脚本后，就可以执行了，在markdown文件中准备了一个数学计算，然后执行命令，可以看到message中显示执行结果，另外，为了调试，这里还显示testItem对象的值。

  除了自定义测试执行逻辑，实际在开发vscode测试相关类插件时，还可以调用第三方已有的测试工具执行测试，代码的例子是调用jest执行测试的例子。

  上面只定义了一个简单的runTest逻辑，在实际项目中，更多的是集成第三方测试执行插件，例如集成jest，在runTest方法里面只需通过“child_process.exec(`npx jest -t "${testItem.label}" --json`”来执行对应的测试即可。下面的使用vscode的testcontroller等组件，集成test来执行测试的例子。所有代码如下所示：

import * as vscode from 'vscode';
import * as child_process from 'child_process';export function activate(context: vscode.ExtensionContext) {const testController = vscode.tests.createTestController('jestTestController', 'Jest Tests');context.subscriptions.push(testController);context.subscriptions.push(vscode.commands.registerCommand('extension.runJestTests', async () => {await runAllTests(testController);}));async function runAllTests(testController: vscode.TestController) {const testItems: vscode.TestItem[] = [];testController.items.forEach(testItem => testItems.push(testItem));const request = new vscode.TestRunRequest(testItems);const run = testController.createTestRun(request);let allTestsPassed = true;const testResults: { [key: string]: boolean } = {};for (const test of testItems) {run.started(test);const result = await runJestTest(test);testResults[test.id] = result;if (result) {run.passed(test);} else {run.failed(test, new vscode.TestMessage('Test failed'));allTestsPassed = false;}}run.end();if (allTestsPassed) {vscode.window.showInformationMessage('All tests passed.');} else {vscode.window.showInformationMessage('Some tests failed. Check test results for details.');}}context.subscriptions.push(vscode.workspace.onDidOpenTextDocument(doc => {if (doc.languageId === 'typescript' || doc.languageId === 'javascript') {loadTestsFromDocument(testController, doc);}}));vscode.workspace.textDocuments.forEach(doc => {if (doc.languageId === 'typescript' || doc.languageId === 'javascript') {loadTestsFromDocument(testController, doc);}});
}function loadTestsFromDocument(testController: vscode.TestController, document: vscode.TextDocument) {const tests = parseTests(document.getText());for (const test of tests) {const testItem = testController.createTestItem(test.name, test.name, document.uri);testController.items.add(testItem);}
}interface Test {name: string;
}function parseTests(text: string): Test[] {const testRegex = /test\(['"](.+)['"]/g;const tests: Test[] = [];let match;while ((match = testRegex.exec(text)) !== null) {tests.push({name: match[1]});}return tests;
}async function runJestTest(testItem: vscode.TestItem): Promise<boolean> {return new Promise((resolve) => {const options = {cwd: vscode.workspace.workspaceFolders ? vscode.workspace.workspaceFolders[0].uri.fsPath : undefined,};child_process.exec(`npx jest -t "${testItem.label}" --json`, options, (err, stdout, stderr) => {if (err) {console.error(stderr);vscode.window.showErrorMessage(`Test failed to run: ${stderr}`);resolve(false);} else {try {const result = JSON.parse(stdout);vscode.window.showInformationMessage(`${testItem.label}: ${result.numFailedTests === 0 ? 'Passed' : 'Failed'}`);resolve(result.numFailedTests === 0);} catch (parseError) {console.error(`Failed to parse test result: ${parseError}`);vscode.window.showErrorMessage(`Failed to parse test result: ${parseError}`);resolve(false);}}});});
}export function deactivate() { }

   为了验证上面的插件是否工作，需要再准备一个包含jest测试的项目，该项目包含一个简单sum函数，以及用jest框架测试add函数的测试脚本。

import { add } from './adder';test('first', () => {expect(add(1, 2)).toBe(4);
});test('second', () => {expect(add(0, 0)).toBe(0);
});

    运行插件，可以看到执行了两个测试，其中一个成功，一个失败，说明成功调用jest执行了测试，并获取到了测试结果。结果如下图所示：

   以上就是vscode插件开发TestController组件的使用介绍，在实际项目，例如playwright-vscode插件就会使用这些组件，完成对ui测试的执行。后续的博客将从源码层面来解析playwright-vscode插件实现原理。