TypeScriptCompilerのベースラインとテストの仕組み

OXCなんかで、TypeScriptのテストケースを参照して、カバレッジを取ってることは知ってた。

けど、

• ./tests/baselines/reference/にある.errors.txtはどう読み解くのが正解なのか？
• TSC自体はどのAPIを使ってテストしているのか？

みたいなことが、なんとな〜くしかわかってなかった。

今回はそれを明らかにしたい。

./tests/baselines/reference配下においてあるものをベースラインと呼んでる。

https://github.com/microsoft/TypeScript/blob/main/CONTRIBUTING.md#managing-the-baselines

テストの足回り

• TypeScriptのリポジトリでnpm runすると、npm run testが存在することがわかる
• npm run testは、hereby runtests-parallelを実行する
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/Herebyfile.mjs#L822
• doRunTestsParallel()という別のタスクが呼ばれてる
• これは、依存してるタスクを解決してから、runConsoleTests(testRunner, "min", runInParallel)を呼ぶ
• 依存タスクとは、tests()というタスクとgenerateLibs()というタスク
• tests()タスクは、テストランナーをビルドするもの
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/Herebyfile.mjs#L534
• ./src/testRunner配下にあるのがその一式で、ビルドされるとrun.jsというファイルになるらしい
• そのrun.jsを使って、テストコマンドがchild_process.spawn()されてく

実際にはもう少し色々な準備があるけど、だいたいこんな感じか。

./src/testRunner/runner.tsで呼んでるstartTestEnvironment()がエントリーポイントらしい。

startTestEnvironment()

• https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/runner.ts#L277
  • テスト実行を並列化するためのあれこれはさておき
  • ここにあるbeginTests()が呼ばれる
• beginTest()は、runTests(runners)が実体
• runnersは、事前にテストの設定から導出されるもので、RunnerBaseクラスの配列になってる
• RunnerBaseは、./src/harness/runnerbase.tsで定義されてる
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/runnerbase.ts#L22
• コンパイラのテストとして、RunnerBaseをextendしてるCompilerBaselineRunnerというやつが、2種類用意される
  • runners.push(new CompilerBaselineRunner(CompilerTestType.Conformance))
  • runners.push(new CompilerBaselineRunner(CompilerTestType.Regressions))
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/runner.ts#L210-L212
• runTests(runners)でそれぞれを実行していく
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/runner.ts#L25
• まずはrunner.enumerateTestFiles()でテストケースの列挙
  • テストケース名、衝突しそうやなって思ってたけど、ここで重複チェックをやってた
• それぞれrunner.initializeTests()していく
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/runner.ts#L42

つぎはCompilerBaselineRunnerの詳細へ。

CompilerBaselineRunner

• コンパイラー関連では、2種類用意されてた
  • CompilerTestType.Conformanceはtests/cases/conformanceに対応
  • CompilerTestType.Regressionsはtests/cases/compilerに対応
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L34
• enumerateTestFiles()
  • それぞれのディレクトリから、.tsx?ファイルを取ってきてリストを返すだけ
• initializeTests()
  • テストファイルそれぞれに対して、checkTestCodeOutput(vpath.normalizeSeparators(file), CompilerTest.getConfigurations(file))
• CompilerTest.getConfigurations(file)
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L261
  • どういうファイル（ソースコード）に対して、どういう設定でコンパイルするかを調べる
• const settings = TestCaseParser.extractCompilerSettings(content)
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1288
  • テストファイルそれぞれを解析して、コンパイラの設定を抽出する
  • 各テストファイルは行頭に// @lib: esnextや// @filename foo.tsみたいなコメントが書いてある
• const configurations = getFileBasedTestConfigurations(settings, CompilerTest.varyBy)
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1221
  • テストのコメントは、基本的には@key: valueだが、たまに@key: value1,value2みたいなのがあり、これがバリエーション
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/tests/cases/compiler/exportEmptyObjectBindingPattern.ts
• ソース文字列と設定がわかったので、checkTestCodeOutput()
  • バリエーションに応じて、または単発のrunSuite(fileName, test)
  • これ自体がmochaのdescribe()内で呼ばれる
• runSuite(fileName, test, configuration?)
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L88
  • payload = TestCaseParser.makeUnitsFromTest(test.content, test.file)して
  • それをnew CompilerTest(fileName, payload, configuration)
  • CompilerTestクラスの様々なメソッドでもって、mochaのit()を呼んでいく
• makeUnitsFromTest()
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1308
  • @filenameコメントがあったら分割してモジュールっぽく扱う
  • FilenameとかfileNameとか、表記揺れしてるのがずっと気になってたけど、ここでtoLowerCase()されてた
  • 愚直にファイルを改行で割って、1行ずつ精査していってた・・・
  • シンボリックリンクまで処理してるけどそんなことあるんや
• runSuite()でテストしてることは6種類
  • エラー報告: compilerTest.verifyDiagnostics()
  • モジュール解決: compilerTest.verifyModuleResolution()
  • ソースマップの中身: compilerTest.verifySourceMapRecord()
  • JSへの変換結果: compilerTest.verifyJavaScriptOutput()
  • ソースマップ: compilerTest.verifySourceMapOutput()
  • 型とシンボル: compilerTest.verifyTypesAndSymbols()

このverifyDiagnostics()が一番知りたかったやつ。CompilerTestをみてく。

CompilerTest

• https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L128
• constructor()の時点で、this.result = Compiler.compileFiles()してて、それを後から参照してる
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L249
• verifyDiagnostics()も、this.result.diagnosticsを渡して、Compiler.doErrorBaseline()というものでチェックしてるだけ

Compilerはただのnamespaceだった。

Compiler#compileFiles()

• https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L377
• いろいろやってるが、compiler.compileFiles()が実体っぽい
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L433
• compiler.compileFiles()
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/compilerImpl.ts#L244
  • createProgram()とか、getPreEmitDiagnostics()とか、見慣れたAPIがいろいろ使われてる
• コンパイル結果は、CompilationResultクラスにして返す
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/compilerImpl.ts#L55
  • getPreEmitDiagnostics()で取得したdiagnostics: Diagnostic[]が渡されてる
• getPreEmitDiagnostics()には、さまざまなエラーが含まれてる
  • getSyntacticDiagnostics()とgetSemanticDiagnostics()ももちろん入ってる

Compiler#doErrorBaseline()

• CompilationResultに渡しておいたdiagnosticsを渡して実行する
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/testRunner/compilerRunner.ts#L271
• https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L715
  • Baseline.runBaseline(baselinePath.replace(/\.tsx?$/, ".errors.txt"), !errors || (errors.length === 0) ? null : getErrorBaseline(inputFiles, errors, pretty))
• 第1引数のパスはテストケース名なので、拡張子を.errors.txtに変えて、./tests/baselines/referenceにあるスナップショットへのパス
• 第2引数は、取得したDiagnosticを文字列に整形したもの
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L540
  • かなり頑張って整形してる・・・
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L578
  • まずサマリがあり、そのあとにファイルごとの詳細が並ぶ
  • "!!! " + ts.diagnosticCategoryName(error) + " TS" + error.code + ": " + sみたいなテンプレの産地はここ
  • こうしてできあがったのが、あの.errors.txtというわけ

このBaselineもただのnamespaceだった。

Baseline#runBaseline()

• https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1559
• ついさっき取得したDiagnostic[]を文字列化したものをactualとして、expectと比較を行い、その結果を記録する
• compareToBaseline()
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1482
  • compareと言ってるものの、特に比較はしていなそう
  • 意味深なTODOコメントが残ってたけど、issueはclosedだった: https://github.com/microsoft/TypeScript/issues/18217
  • readFile()してexpectな文字列を取得してるのみ
• writeComparison()
  • https://github.com/microsoft/TypeScript/blob/dd1e258ba56f1b511879372c857fb625de3dec4a/src/harness/harnessIO.ts#L1505
  • 実際に比較して、差分があったらthrowしてるのはこっち
  • はじめての場合は<no content>というプレースホルダーになってる

スナップショットと差分があったらthrowするというだけ。

まとめ

• TSCのテストは、src/testRunnerとsrc/harnessでがっつり実装されてる
• 内部的にはmochaを使ってがんばってる
• コンパイラーに関しては2パターンをテスト
  • tests/cases/compiler: Regressions
  • tests/cases/conformance: Conformance
• 内容は、tests/baselines/referenceにある各種ファイルとのスナップショットテスト
  • .errors.txtだけでなく、.symbolsや.typesのほか、emitされた.jsなど
• .errors.txtは、Diagnostic[]を文字列化したもの
  • テストケースは@filenameコメントで複数ファイルから構成されることもある
  • その場合も全ファイル分をまとめたスナップショットになる
  • どのファイルでどのエラーが出たか、ちゃんとわかるようになってる

だいたい予想してた通りでよかった。