测试API

测试 API 允许 Visual Studio Code 扩展发现工作区中的测试并发布结果。用户可以在测试资源管理器视图中、通过装饰和内部命令执行测试。借助这些新的 API，Visual Studio Code 支持比以前更丰富的输出和差异显示。

注意：测试 API 在 VS Code 版本 1.59 及更高版本中可用。

例子

VS Code 团队维护了两个测试提供程序：

• 示例测试扩展，它提供 Markdown 文件中的测试。
• selfhost测试扩展，我们用于在 VS Code 本身中运行测试。

发现测试

测试由 提供TestController，它需要全球唯一的 ID 和人类可读的标签来创建：

const controller = vscode.tests.createTestController(
  'helloWorldTests',
  'Hello World Tests'
);

要发布测试，请将TestItems 作为子项添加到控制器的items集合中。TestItems 是接口中测试 API 的基础TestItem，并且是一种通用类型，可以描述代码中存在的测试用例、套件或树项。反过来，他们也可以拥有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);
  }
  // ...
});

与诊断类似，它主要由扩展来控制何时发现测试。一个简单的扩展可能会监视整个工作区并在激活时解析所有文件中的所有测试。然而，对于大型工作空间来说，立即解析所有内容可能会很慢。相反，您可以做两件事：

1. 当文件在编辑器中打开时，通过观看 来主动发现文件的测试vscode.workspace.onDidOpenTextDocument。
2. 设置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很简单，没有空间容纳自定义数据。如果您需要将额外信息与 a 相关联TestItem，可以使用 a 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);

确保TestItem传递给所有TestController相关方法的实例将与最初从 中创建的实例相同createTestItem，因此您可以确定从地图获取项目testData将会起作用。

对于这个例子，我们只存储每个项目的类型：

enum ItemType {
  File,
  TestCase
}

const testData = new WeakMap<vscode.TestItem, ItemType>();

const getType = (testItem: vscode.TestItem) => testData.get(testItem)!;

运行测试

测试通过 s 执行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，您还可以configureHandler设置TestRunProfile。如果存在，VS Code 将具有 UI 来允许用户配置测试运行，并在执行此操作时调用处理程序。从这里，您可以打开文件、显示快速选择或执行适合您的测试框架的任何操作。

VS Code 有意以不同于调试或任务配置的方式处理测试配置。这些传统上是编辑器或以 IDE 为中心的功能，并在文件夹中的特殊文件中进行配置.vscode。然而，传统上测试是从命令行执行的，并且大多数测试框架都有现有的配置策略。因此，在 VS Code 中，我们避免重复配置，而是将其留给扩展来处理。

测试输出

除了传递到TestRun.failed或 的消息之外TestRun.errored，您还可以使用 附加通用输出run.appendOutput(str)。可以使用“测试：显示输出”以及通过 UI 中的各种按钮（例如“测试资源管理器”视图中的终端图标）在终端中显示此输出。

由于字符串是在终端中呈现的，因此您可以使用全套ANSI 代码，包括ansi-styles npm 包中可用的样式。请记住，因为它位于终端中，所以必须使用 CRLF ( \r\n) 换行，而不仅仅是 LF ( \n)，这可能是某些工具的默认输出。

测试标签

有时测试只能在某些配置下运行，或者根本不运行。对于这些用例，您可以使用测试标签。TestRunProfile可以选择有一个与其关联的标签，如果有，则只有具有该标签的测试才能在配置文件下运行。再次强调，如果没有符合条件的配置文件可供运行、调试或收集特定测试的覆盖范围，这些选项将不会显示在 UI 中。

// 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];
}

用户还可以在测试资源管理器 UI 中按标签进行过滤。

仅发布控制器

运行配置文件的存在是可选的。控制器可以在没有配置文件的情况下创建测试、调用createTestRun外部以及在运行中更新测试的状态。runHandler常见的用例是控制器从外部源（例如 CI 或摘要文件）加载结果。

在这种情况下，这些控制器通常应将可选name参数传递给createTestRun, 和false作为persist参数。传递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] Create a native TestController。

总结一下，一般步骤是：

1. 无需使用TestAdapter测试资源管理器 UI检索和注册TestHub，而是调用const controller = vscode.tests.createTestController(...)。

2. 不要testAdapter.tests在发现或重新发现测试时触发，而是创建测试并将其推送到 中controller.items，例如通过调用controller.items.replace通过调用创建的一组已发现的测试vscode.test.createTestItem。请注意，随着测试的更改，您可以更改测试项的属性并更新其子项，并且更改将自动反映在 VS Code 的 UI 中。

3. 要最初加载测试，而不是等待testAdapter.load()方法调用，请设置controller.resolveHandler = () => { /* discover tests */ }。在发现测试中查看有关测试发现如何工作的更多信息。

4. 要运行测试，您应该创建一个运行配置文件，其中包含调用const run = controller.createTestRun(request). 不要触发testStates事件，而是将TestItems 传递给 上的方法来run更新其状态。

额外贡献点

菜单testing/item/context 贡献点可用于将菜单项添加到测试资源管理器视图中的测试。将菜单项放入inline组中以使它们内联。所有其他菜单项组将显示在可使用鼠标右键单击访问的上下文菜单中。

菜单项的子句中提供了其他上下文键： 、和。对于更复杂的场景，您希望操作可以选择性地用于不同的测试项目，请考虑使用条件运算符。whentestIdcontrollerIdtestItemHasUriwhenin

如果您想在资源管理器中显示测试，可以将测试传递给命令vscode.commands.executeCommand('vscode.revealTestInExplorer', testItem)。