测试API
测试API允许Visual Studio Code扩展在工作区中发现测试并发布结果。用户可以在测试资源管理器视图中、从装饰器内以及命令内部执行测试。通过这些新的API，Visual Studio Code支持比以前更丰富的输出和差异显示。
注意: 测试API在VS Code版本1.59及以上版本中可用。
示例
VS Code 团队维护了两个测试提供者：
- 示例测试扩展，它在Markdown文件中提供测试。
- 我们用于在VS Code本身中运行测试的selfhost测试扩展。
发现测试
测试由TestController提供，它需要一个全局唯一的ID和人类可读的标签来创建：
const controller = vscode.tests.createTestController(
'helloWorldTests',
'Hello World Tests'
);
要发布测试，您可以将TestItem作为子项添加到控制器的items集合中。TestItem是TestItem接口中测试API的基础，并且是一种通用类型，可以描述代码中存在的测试用例、套件或树项。它们本身也可以有children，形成一个层次结构。例如，以下是示例测试扩展如何创建测试的简化版本：
parseMarkdown(content, {
onTest: (range, numberA, mathOperator, numberB, expectedValue) => {
// If this is a top-level test, add it to its parent's children. If not,
// add it to the controller's top level items.
const collection = parent ? parent.children : controller.items;
// Create a new ID that's unique among the parent's children:
const id = [numberA, mathOperator, numberB, expectedValue].join(' ');
// Finally, create the test item:
const test = controller.createTestItem(id, data.getLabel(), item.uri);
test.range = range;
collection.add(test);
}
// ...
});
与诊断类似，扩展主要控制何时发现测试。一个简单的扩展可能会监视整个工作区，并在激活时解析所有文件中的所有测试。然而，对于大型工作区，立即解析所有内容可能会很慢。相反，你可以做两件事：
- 当文件在编辑器中打开时，通过监听
vscode.workspace.onDidOpenTextDocument，主动发现文件的测试。 - 设置
item.canResolveChildren = true并设置controller.resolveHandler。如果用户采取操作要求发现测试，例如通过展开测试资源管理器中的项目，则会调用resolveHandler。
以下是在一个延迟解析文件的扩展中，这个策略可能看起来的样子：
// First, create the `resolveHandler`. This may initially be called with
// "undefined" to ask for all tests in the workspace to be discovered, usually
// when the user opens the Test Explorer for the first time.
controller.resolveHandler = async test => {
if (!test) {
await discoverAllFilesInWorkspace();
} else {
await parseTestsInFileContents(test);
}
};
// When text documents are open, parse tests in them.
vscode.workspace.onDidOpenTextDocument(parseTestsInDocument);
// We could also listen to document changes to re-parse unsaved changes:
vscode.workspace.onDidChangeTextDocument(e => parseTestsInDocument(e.document));
// In this function, we'll get the file TestItem if we've already found it,
// otherwise we'll create it with `canResolveChildren = true` to indicate it
// can be passed to the `controller.resolveHandler` to gets its children.
function getOrCreateFile(uri: vscode.Uri) {
const existing = controller.items.get(uri.toString());
if (existing) {
return existing;
}
const file = controller.createTestItem(uri.toString(), uri.path.split('/').pop()!, uri);
file.canResolveChildren = true;
return file;
}
function parseTestsInDocument(e: vscode.TextDocument) {
if (e.uri.scheme === 'file' && e.uri.path.endsWith('.md')) {
parseTestsInFileContents(getOrCreateFile(e.uri), e.getText());
}
}
async function parseTestsInFileContents(file: vscode.TestItem, contents?: string) {
// If a document is open, VS Code already knows its contents. If this is being
// called from the resolveHandler when a document isn't open, we'll need to
// read them from disk ourselves.
if (contents === undefined) {
const rawContent = await vscode.workspace.fs.readFile(file.uri);
contents = new TextDecoder().decode(rawContent);
}
// some custom logic to fill in test.children from the contents...
}
discoverAllFilesInWorkspace 的实现可以使用 VS Code 现有的文件监视功能来构建。当调用 resolveHandler 时，您应该继续监视更改，以便测试资源管理器中的数据保持最新。
async function discoverAllFilesInWorkspace() {
if (!vscode.workspace.workspaceFolders) {
return []; // handle the case of no open folders
}
return Promise.all(
vscode.workspace.workspaceFolders.map(async workspaceFolder => {
const pattern = new vscode.RelativePattern(workspaceFolder, '**/*.md');
const watcher = vscode.workspace.createFileSystemWatcher(pattern);
// When files are created, make sure there's a corresponding "file" node in the tree
watcher.onDidCreate(uri => getOrCreateFile(uri));
// When files change, re-parse them. Note that you could optimize this so
// that you only re-parse children that have been resolved in the past.
watcher.onDidChange(uri => parseTestsInFileContents(getOrCreateFile(uri)));
// And, finally, delete TestItems for removed files. This is simple, since
// we use the URI as the TestItem's ID.
watcher.onDidDelete(uri => controller.items.delete(uri.toString()));
for (const file of await vscode.workspace.findFiles(pattern)) {
getOrCreateFile(file);
}
return watcher;
})
);
}
TestItem 接口很简单，没有空间用于自定义数据。如果你需要将额外信息与 TestItem 关联，你可以使用 WeakMap：
const testData = new WeakMap<vscode.TestItem, MyCustomData>();
// to associate data:
const item = controller.createTestItem(id, label);
testData.set(item, new MyCustomData());
// to get it back later:
const myData = testData.get(item);
保证传递给所有TestController相关方法的TestItem实例与最初从createTestItem创建的实例相同，因此您可以确信从testData映射中获取项目将有效。
对于这个例子，我们只存储每个项目的类型：
enum ItemType {
File,
TestCase
}
const testData = new WeakMap<vscode.TestItem, ItemType>();
const getType = (testItem: vscode.TestItem) => testData.get(testItem)!;
运行测试
测试通过TestRunProfile执行。每个配置文件属于特定的执行kind：运行、调试或覆盖。大多数测试扩展在每个组中最多有一个配置文件，但允许更多。例如，如果您的扩展在多个平台上运行测试，您可以为每个平台和kind的组合拥有一个配置文件。每个配置文件都有一个runHandler，当请求该类型的运行时，会调用它。
function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
// todo
}
const runProfile = controller.createRunProfile(
'Run',
vscode.TestRunProfileKind.Run,
(request, token) => {
runHandler(false, request, token);
}
);
const debugProfile = controller.createRunProfile(
'Debug',
vscode.TestRunProfileKind.Debug,
(request, token) => {
runHandler(true, request, token);
}
);
runHandler 应该至少调用一次 controller.createTestRun，并传递原始请求。请求中包含要在测试运行中include的测试（如果用户要求运行所有测试，则省略此部分），以及可能要从运行中exclude的测试。扩展应使用生成的TestRun对象来更新运行中涉及的测试状态。例如：
async function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
const run = controller.createTestRun(request);
const queue: vscode.TestItem[] = [];
// Loop through all included tests, or all known tests, and add them to our queue
if (request.include) {
request.include.forEach(test => queue.push(test));
} else {
controller.items.forEach(test => queue.push(test));
}
// For every test that was queued, try to run it. Call run.passed() or run.failed().
// The `TestMessage` can contain extra information, like a failing location or
// a diff output. But here we'll just give it a textual message.
while (queue.length > 0 && !token.isCancellationRequested) {
const test = queue.pop()!;
// Skip tests the user asked to exclude
if (request.exclude?.includes(test)) {
continue;
}
switch (getType(test)) {
case ItemType.File:
// If we're running a file and don't know what it contains yet, parse it now
if (test.children.size === 0) {
await parseTestsInFileContents(test);
}
break;
case ItemType.TestCase:
// Otherwise, just run the test case. Note that we don't need to manually
// set the state of parent tests; they'll be set automatically.
const start = Date.now();
try {
await assertTestPasses(test);
run.passed(test, Date.now() - start);
} catch (e) {
run.failed(test, new vscode.TestMessage(e.message), Date.now() - start);
}
break;
}
test.children.forEach(test => queue.push(test));
}
// Make sure to end the run after all tests have been executed:
run.end();
}
除了runHandler之外，你还可以在TestRunProfile上设置一个configureHandler。如果存在，VS Code 将提供用户界面，允许用户配置测试运行，并在他们这样做时调用处理程序。从这里，你可以打开文件，显示快速选择，或为你的测试框架做任何合适的事情。
VS Code 有意以不同于调试或任务配置的方式处理测试配置。这些传统上是编辑器或 IDE 为中心的功能，并在
.vscode文件夹中的特殊文件中进行配置。然而，测试传统上是从命令行执行的，大多数测试框架都有现有的配置策略。因此，在 VS Code 中，我们避免配置的重复，而是将其留给扩展来处理。
测试输出
除了传递给TestRun.failed或TestRun.errored的消息外，您还可以使用run.appendOutput(str)附加通用输出。此输出可以通过测试：显示输出在终端中显示，并通过UI中的各种按钮（如测试资源管理器视图中的终端图标）显示。
因为字符串是在终端中渲染的，你可以使用全套的ANSI代码，包括在ansi-styles npm包中可用的样式。请记住，因为它在终端中，行必须使用CRLF（\r\n）换行，而不仅仅是LF（\n），这可能是某些工具的默认输出。
测试覆盖率
测试覆盖率通过run.addCoverage()方法与TestRun关联。通常这应该由TestRunProfileKind.Coverage配置文件的runHandler完成，但在任何测试运行期间都可以调用它。addCoverage方法接受一个FileCoverage对象，该对象是该文件中覆盖率数据的摘要：
async function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
// ...
for await (const file of readCoverageOutput()) {
run.addCoverage(new vscode.FileCoverage(file.uri, file.statementCoverage));
}
}
FileCoverage 包含每个文件中语句、分支和声明的总体覆盖和未覆盖计数。根据您的运行时和覆盖格式，您可能会看到语句覆盖被称为行覆盖，或者声明覆盖被称为函数或方法覆盖。您可以多次为单个URI添加文件覆盖，在这种情况下，新信息将替换旧信息。
一旦用户打开一个包含覆盖率的文件或在测试覆盖率视图中展开一个文件，VS Code 会请求该文件的更多信息。它通过在TestRunProfile上调用扩展定义的loadDetailedCoverage方法来实现这一点，该方法带有TestRun、FileCoverage和一个CancellationToken。请注意，测试运行和文件覆盖率实例与run.addCoverage中使用的实例相同，这对于关联数据非常有用。例如，您可以创建一个FileCoverage对象到您自己数据的映射：
const coverageData = new WeakMap<vscode.FileCoverage, MyCoverageDetails>();
profile.loadDetailedCoverage = (testRun, fileCoverage, token) => {
return coverageData.get(fileCoverage).load(token);
};
async function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
// ...
for await (const file of readCoverageOutput()) {
const coverage = new vscode.FileCoverage(file.uri, file.statementCoverage);
coverageData.set(coverage, file);
run.addCoverage(coverage);
}
}
或者，您可以使用包含该数据的实现来子类化 FileCoverage：
class MyFileCoverage extends vscode.FileCoverage {
// ...
}
profile.loadDetailedCoverage = async (testRun, fileCoverage, token) => {
return fileCoverage instanceof MyFileCoverage ? await fileCoverage.load() : [];
};
async function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
// ...
for await (const file of readCoverageOutput()) {
// 'file' is MyFileCoverage:
run.addCoverage(file);
}
}
loadDetailedCoverage 预期返回一个承诺，该承诺解析为一个包含 DeclarationCoverage 和/或 StatementCoverage 对象的数组。这两个对象都包含一个 Position 或 Range，表示它们在源文件中的位置。DeclarationCoverage 对象包含被声明事物的名称（如函数或方法名称）以及该声明被进入或调用的次数。语句包括它们被执行的次数，以及零个或多个相关的分支。有关更多信息，请参阅 vscode.d.ts 中的类型定义。
在许多情况下，您可能会在测试运行后留下持久性文件。最佳实践是将此类覆盖率输出放在系统的临时目录中（您可以通过require('os').tmpdir()获取），但您也可以通过监听VS Code的信号来主动清理这些文件，当它不再需要保留测试运行时：
import { promises as fs } from 'fs';
async function runHandler(
shouldDebug: boolean,
request: vscode.TestRunRequest,
token: vscode.CancellationToken
) {
// ...
run.onDidDispose(async () => {
await fs.rm(coverageOutputDirectory, { recursive: true, force: true });
});
}
测试标签
有时测试只能在特定配置下运行，或者根本无法运行。对于这些用例，您可以使用测试标签。TestRunProfile可以选择性地与一个标签关联，如果它们有关联，只有具有该标签的测试才能在配置文件下运行。再次强调，如果没有符合条件的配置文件来运行、调试或收集特定测试的覆盖率，这些选项将不会在用户界面中显示。
// Create a new tag with an ID of "runnable"
const runnableTag = new TestTag('runnable');
// Assign it to a profile. Now this profile can only execute tests with that tag.
runProfile.tag = runnableTag;
// Add the "runnable" tag to all applicable tests.
for (const test of getAllRunnableTests()) {
test.tags = [...test.tags, runnableTag];
}
用户还可以在测试资源管理器界面中通过标签进行筛选。
仅发布控制器
运行配置文件的存在是可选的。控制器可以在没有配置文件的情况下创建测试，在runHandler之外调用createTestRun，并在运行中更新测试的状态。这种情况的常见用例是从外部源（如CI或摘要文件）加载结果的控制器。
在这种情况下，这些控制器通常应将可选的name参数传递给createTestRun，并将persist参数设置为false。在这里传递false指示VS Code不要保留测试结果，就像在编辑器中运行一样，因为这些结果可以从外部源重新加载。
const controller = vscode.tests.createTestController(
'myCoverageFileTests',
'Coverage File Tests'
);
vscode.commands.registerCommand('myExtension.loadTestResultFile', async file => {
const info = await readFile(file);
// set the controller items to those read from the file:
controller.items.replace(readTestsFromInfo(info));
// create your own custom test run, then you can immediately set the state of
// items in the run and end it to publish results:
const run = controller.createTestRun(
new vscode.TestRunRequest(),
path.basename(file),
false
);
for (const result of info) {
if (result.passed) {
run.passed(result.item);
} else {
run.failed(result.item, new vscode.TestMessage(result.message));
}
}
run.end();
});
从测试资源管理器UI迁移
如果您有一个使用测试资源管理器UI的现有扩展，我们建议您迁移到原生体验以获得更多功能和效率。我们已经在一个仓库中整理了一个测试适配器示例的迁移示例，您可以在其Git历史中查看。您可以通过选择提交名称来查看每个步骤，从[1] 创建一个原生TestController开始。
总的来说，一般步骤如下：
-
而不是检索并注册一个
TestAdapter到测试资源管理器UI的TestHub，调用const controller = vscode.tests.createTestController(...)。 -
与其在发现或重新发现测试时触发
testAdapter.tests，不如创建并将测试推入controller.items，例如通过调用controller.items.replace并传入一个由调用vscode.test.createTestItem创建的已发现测试数组。请注意，随着测试的变化，您可以更改测试项上的属性并更新其子项，这些更改将自动反映在VS Code的用户界面中。 -
要初始加载测试，而不是等待
testAdapter.load()方法调用，设置controller.resolveHandler = () => { /* 发现测试 */ }。有关测试发现如何工作的更多信息，请参阅发现测试。 -
要运行测试，您应该创建一个运行配置文件，其中包含一个调用
const run = controller.createTestRun(request)的处理函数。不要触发testStates事件，而是将TestItem传递给run上的方法以更新它们的状态。
额外的贡献点
testing/item/context 菜单贡献点 可用于在测试资源管理器视图中向测试添加菜单项。将菜单项放置在 inline 组中以使其内联显示。所有其他菜单项组将显示在可通过鼠标右键访问的上下文菜单中。
在菜单项的when子句中，可以使用额外的上下文键：testId、controllerId和testItemHasUri。对于更复杂的when场景，如果您希望操作可以根据不同的测试项选择性可用，请考虑使用in条件运算符。
如果你想在资源管理器中显示一个测试，你可以将测试传递给命令 vscode.commands.executeCommand('vscode.revealTestInExplorer', testItem)。