Testing API

Testing API を使用すると、Visual Studio Code 拡張機能はワークスペース内のテストを検出して結果を公開できるようになります。ユーザーは、テストエクスプローラービュー、装飾（デコレーション）、コマンド内からテストを実行できます。これらの新しい API により、Visual Studio Code は以前よりも高度な出力表示や差分表示をサポートします。

注: Testing API は VS Code バージョン 1.59 以降で利用可能です。

例

VS Code チームが管理している 2 つのテストプロバイダーがあります。

Markdown ファイル内のテストを提供するサンプルテスト拡張機能。
VS Code 自体のテストを実行するために使用しているセルフホストテスト拡張機能。

テストの検出

テストは 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);
  }
  // ...
});

Diagnostics（診断）と同様に、テストをいつ検出するかは主に拡張機能側の制御に委ねられています。単純な拡張機能であれば、ワークスペース全体を監視し、アクティブ化時にすべてのファイル内のすべてのテストを解析するかもしれません。しかし、すべてを即座に解析するのは大規模なワークスペースでは時間がかかる可能性があります。代わりに、次の 2 つの方法が可能です。

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 を通じて実行されます。各プロファイルは、run（実行）、debug（デバッグ）、coverage（カバレッジ）という特定の実行 kind に属します。ほとんどのテスト拡張機能では、これらのグループごとに最大でも 1 つのプロファイルを持ちますが、複数を持つことも可能です。例えば、拡張機能が複数のプラットフォームでテストを実行する場合、プラットフォームと 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 はユーザーがテスト実行を構成するための UI を表示し、ユーザーがそうしたときにハンドラーを呼び出します。ここからファイルを開いたり、Quick Pick を表示したり、テストフレームワークに適したあらゆる操作を行うことができます。

VS Code は、テストの構成をデバッグやタスクの構成とは意図的に異なる方法で処理します。これらは伝統的にエディターや IDE 中心機能であり、.vscode フォルダー内の特別なファイルで構成されます。しかし、テストは伝統的にコマンドラインから実行されており、ほとんどのテストフレームワークには既存の構成戦略があります。そのため、VS Code では構成の重複を避け、代わりに拡張機能側で処理するようにしています。

テスト出力

TestRun.failed や TestRun.errored に渡されるメッセージに加えて、run.appendOutput(str) を使用して汎用的な出力を追加できます。この出力は、Test: Show Output を使用してターミナルに表示したり、テストエクスプローラービューのターミナルアイコンなど、UI 上のさまざまなボタンを通じて表示したりできます。

文字列はターミナルでレンダリングされるため、ansi-styles npm パッケージで使用可能なスタイルを含む、一連の ANSI コードをフルセットで使用できます。ターミナル内であるため、一部のツールからのデフォルト出力である可能性がある LF (\n) だけでなく、CRLF (\r\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 に対してファイルカバレッジを複数回追加でき、その場合、新しい情報が古い情報に置き換わります。

ユーザーがカバレッジを含むファイルを開くか、Test Coverage ビューでファイルが展開されると、VS Code はそのファイルに関する詳細情報を要求します。これは、TestRunProfile 上で、TestRun、FileCoverage、および CancellationToken を受け取る拡張機能定義の loadDetailedCoverage メソッドを呼び出すことで行われます。テスト実行とファイルカバレッジのインスタンスは 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 オブジェクトの配列を返す Promise を返すことが期待されています。どちらのオブジェクトにも、ソースファイル内で見つけることができる 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 にはオプションでタグを関連付けることができ、その場合、そのタグを持つテストのみがプロファイル下で実行可能です。繰り返しになりますが、特定のテストを実行、デバッグ、またはカバレッジ収集するための適切なプロファイルがない場合、それらのオプションは 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 でタグによってフィルタリングすることもできます。

公開専用コントローラー

実行プロファイルの存在は任意です。コントローラーはテストを作成し、runHandler の外で createTestRun を呼び出し、プロファイルを持たずに実行中のテスト状態を更新することができます。これの一般的なユースケースは、CI や要約ファイルなどの外部ソースから結果を読み込むコントローラーです。

この場合、これらのコントローラーは通常、createTestRun にオプションの name 引数を渡し、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();
});

Test Explorer UI からの移行

既存の拡張機能で Test Explorer UI を使用している場合は、追加機能と効率性のためにネイティブ環境への移行をお勧めします。Test Adapter サンプルの移行例をその Git 履歴にまとめています。[1] Create a native TestController から始めて、コミット名を選択することで各ステップを確認できます。

要約すると、一般的な手順は次の通りです。

Test Explorer UI の TestHub に TestAdapter を取得して登録する代わりに、const controller = vscode.tests.createTestController(...) を呼び出します。
テストを検出または再検出する際に testAdapter.tests を発行するのではなく、controller.items にテストを作成してプッシュします。例えば、vscode.test.createTestItem を呼び出して作成された検出済みテストの配列で controller.items.replace を呼び出します。テストが変更されると、テストアイテムのプロパティをミューテートして子を更新でき、変更は VS Code の UI に自動的に反映されることに注意してください。
テストを最初に読み込むには、testAdapter.load() メソッドの呼び出しを待つのではなく、controller.resolveHandler = () => { /* discover tests */ } を設定します。テスト検出の仕組みについての詳細は「テストの検出」を参照してください。
テストを実行するには、const run = controller.createTestRun(request) を呼び出すハンドラー関数を持つ実行プロファイルを作成します。testStates イベントを発行するのではなく、run 上のメソッドに TestItem を渡してその状態を更新します。

その他のコントリビューションポイント

testing/item/context メニューコントリビューションポイントを使用して、テストエクスプローラービュー内のテストにメニューアイテムを追加できます。メニューアイテムを inline グループに配置するとインライン表示されます。他のすべてのメニューアイテムグループは、マウスの右クリックでアクセス可能なコンテキストメニューに表示されます。

メニューアイテムの when 句では、追加のコンテキストキー（testId、controllerId、testItemHasUri）が利用可能です。アクションを特定のテストアイテムに対してオプションで利用可能にしたいような、より複雑な when シナリオでは、in 条件演算子の使用を検討してください。

エクスプローラーでテストを表示したい場合は、vscode.commands.executeCommand('vscode.revealTestInExplorer', testItem) コマンドにそのテストを渡すことができます。

4/8/2026