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插件实现原理。