Jestを読む
nus3リポジトリ
ディレクトリ構造
// 1階層目のディレクトリ
.
├── benchmarks
├── docs
├── e2e
├── examples
├── packages
├── scripts
└── website
以下がmonorepoの対象。
nus3動作確認
jestパッケージ自体はmonorepo配下で管理されている
なのでjestの実装を変更して(例えばconsole.logの追加など)、動作確認をする場合は以下の作業をする
# リポジトリのルートで変更分をビルド
yarn watch
# 適当なテストケースを実行
# yarn jest -- {任意に作成したテストファイルのパス}
yarn jest -- packages/jest-util/src/__tests__/nus3.test.ts
もしくはmonorepoでjest自体は直接リポジトリ内のパッケージを見ているのでexamples配下のテストを実行することでも動作確認ができる。
examples/getting-started配下でyarn testを実行するなど
nus3packages
jestを実行すると、monorepoで管理されたpackages配下のパッケージが実行されるので、依存するパッケージを出てくる順番でみてみる
パッケージの実行順
実際にテストを実行している部分を、パッケージごとにみてみる
jestを実行した時に、呼ばれるパッケージ
nus32024/04/09まで読んでみてのイメージ
- テストファイルと、その対象のファイル、そのほか依存しているモジュールに対してbabelでトランスパイルし、requireしておく
- テストファイルの中で定義されたテストコードを実行する
- テストコードはtry catchの中で実行し、実行したテストコードがerrorをthrowしたら、その呼び出しもとでテストは落ちたと判定するように
- テスト結果を格納する
nus3
jest
jestのbinは"./bin/jest.js"に実装されている
"./bin/jest.js"ではjest-cliをrequire
nus3
jest-cli
'jest-cli/bin/jest'では、jest-cli/src/run.tsのrun()が実行されている
nus3このrun()の中で実際にテストを実行している部分は@jest/coreのrunCLI()っぽい
nus3
@jest/core
runCLI()
runCLI()の_run10000()のコールバック引数でテスト結果を変数に入れてそう
nus3同じファイル上に_run10000()が実装されている
このonCompleteが結果を変数に入れるコールバックで、runWithoutWatch()の第4引数にそのまま渡されている
nus3このonCompleteが引数として渡されたrunWithoutWatch()では、runJest()にそのまま渡している
関数名からjestを実行してそうだぞ
nus3runJest()は同一パッケージ(@jest/core)内でexportされている関数
nus3runJest()に渡されたonCompleteはprocessResults()で実行される
以下はprocessResults()でonCompleteが実行されている箇所
動作確認してみると、ここではprocessResults()の第一引数として渡されたrunResultsをonCompleteの第一引数に渡している
ということでテスト結果はprocessResults()の第一引数であるresults
このresultsはawait scheduler.scheduleTests(allTests, testWatcher);の返り値である
nus3scheduler.scheduleTestsのschedulerはcreateTestSchedulerで生成される
このschedulerはTestSchedulerクラスのインスタンス
TestSchedulerクラスの中にscheduleTestsメソッドが定義されている
scheduleTestsはaggregatedResultsという変数を return してる
return される`aggregateResults`の中身
{
numFailedTestSuites: 0,
numFailedTests: 0,
numPassedTestSuites: 1,
numPassedTests: 1,
numPendingTestSuites: 0,
numPendingTests: 0,
numRuntimeErrorTestSuites: 0,
numTodoTests: 0,
numTotalTestSuites: 1,
numTotalTests: 1,
openHandles: [],
snapshot: {
added: 0,
didUpdate: false,
failure: false,
filesAdded: 0,
filesRemoved: 0,
filesRemovedList: [],
filesUnmatched: 0,
filesUpdated: 0,
matched: 0,
total: 0,
unchecked: 0,
uncheckedKeysByFile: [],
unmatched: 0,
updated: 0
},
startTime: 1711858222218,
success: true,
testResults: [
{
leaks: false,
numFailingTests: 0,
numPassingTests: 1,
numPendingTests: 0,
numTodoTests: 0,
openHandles: [],
perfStats: [Object],
skipped: false,
snapshot: [Object],
testFilePath: '${HOME}/jest/packages/jest-util/src/__tests__/nus3.test.ts',
testResults: [Array],
console: undefined,
displayName: undefined,
failureMessage: null,
testExecError: undefined,
coverage: undefined
}
],
wasInterrupted: false
}
をみるとtestResultsプロパティの中にテスト結果が格納されている。
このtestResultsの中にあるtestResultsプロパティを見ると次のようになっている。
`testResults`の中にある`testResults`プロパティの中身
[
{
"ancestorTitles": ["nus1"],
"duration": 3,
"failing": false,
"failureDetails": [],
"failureMessages": [],
"fullName": "nus1 nus1 testcase1",
"invocations": 1,
"location": null,
"numPassingAsserts": 1,
"retryReasons": [],
"startAt": 1711858647818,
"status": "passed",
"title": "nus1 testcase1"
}
]
最初のtestResultsがおそらくファイルごとの結果を配列で格納しており、その中のtestResultsがファイルの中にあるテストケースごとの結果を配列で格納している
nus3aggregateResultsはcreateAggregatedResultsの返り値
createAggregatedResultsではテスト結果の初期値を生成してそう
からのテスト結果を生成するのはmakeEmptyAggregatedTestResultが作ってそう
makeEmptyAggregatedTestResultをみるとAggregatedResult型のオブジェクトを生成し、初期値を入れてる
このmakeEmptyAggregatedTestResultは@jest/test-resultパッケージの持ち物
TestScheduler.scheduleTestsの中で定義されているonResult
この関数の中でaddResult()を呼ぶことでAggregatedResultにテスト結果を記してそう
実際に@jest/test-resultが提供するaddResult()では、テスト結果を引数に受け取り AggregatedResult にテスト結果を追加している
addResultの引数に渡すテスト結果は onResult の引数に渡されるものでもある。実際にonResultがTestScheduler.scheduleTestsの中で呼ばれているのは以下の 2 箇所
単純なテストファイルを手元で実行してみるとtestRunner.supportsEventEmittersが true の場合の以下の処理が実行されていた
nus3testRunner.on()は実装されているパッケージがjest-runnerなので、そっちに記載する
nus3
@jest/test-result
makeEmptyAggregatedTestResult()
テスト結果の初期値入りオブジェクトを生成する関数。
TestScheduler.scheduleTestsの中で使用される
nus3
addResult()
テスト結果を受け取りAggregatedResultにその結果を追加する
nus3
jest-runner
TestRunner.on
TestScheduler.scheduleTestsの中でテストが実行されていそうな以下の部分で使われている
定義されている場所は以下
nus3TestRunner.onではTestRunnerのプライベートメソッドであるthis.#eventEmitter.onを実行してる
this.#eventEmitterはemitteryというパッケージを require している
このemitteryは非同期でイベントの listner や emit がシンプルにできるライブラリっぽい
TestRunner.onでは第一引数で指定したイベント名の listner を登録しており、this.#eventEmitter.emitで登録したイベントを実行してると推測
nus3テスト結果が書き写されるイベント名はtest-file-successの時で、このイベントをemitしているのは手元で動作確認すると、yarn jest -- packages/jest-util/src/__tests__/nus3.test.tsのように対象のテストファイルを指定して実行する場合、#createInBandTestRun()の中でemitしている。
nus3this.#eventEmitter.emit('test-file-success', [test, result])で emit の際に渡される result はrunTestの返り値である
jest-runnter パッケージの中にrunTestは定義されていて、runTestInternalの返り値が result に格納されている
runTestInternalも同一ファイルに定義されている
nus3runTestInternalの返り値である result はtestFrameworkの返り値である
このtestFrameworkはtransformer.requireAndTranspileModuleの返り値
transformer.requireAndTranspileModuleの定義は@jest/transformで定義されている
examples/getting-started のテストを実行した際のrequireAndTranspileModuleの第一引数は以下だった
${HOME}/jest/packages/jest-runner/build/index.js
${HOME}/jest/packages/jest-environment-node/build/index.js
${HOME}/jest/packages/jest-circus/build/runner.js
requireAndTranspileModuleの処理の中で出てくるaddHookはモジュールを require 時に特定のコードを変換する処理を挟めるライブラリっぽい
nus3requireAndTranspileModuleの第一引数に渡した path のファイルを require してる認識で良さそ
testFrameworkはtransformer.requireAndTranspileModuleの第一引数に渡すモジュールを require してそう
testFrameworkの値はrequireAndTranspileModuleの第一引数の値が${HOME}/jest/packages/jest-circus/build/runner.jsの時
ということで result の値はjest/packages/jest-circus/build/runner.jsのモジュールが実行した返り値
nus3
jest-circus
実際にテストを実行して結果を出力してそうなパッケージ
nus3テスト結果を返すtestFramework()の実態はpackages/jest-circus/src/runner.tsにある。
このモジュールはpackages/jest-circus/src/legacy-code-todo-rewrite/jestAdapter.tsが export するモジュールを使っている
対象のテストファイルのパスを引数に渡して、esm か cjs かをruntime.unstable_shouldLoadAsEsm(path)で判断してる
unstable_shouldLoadAsEsm()はjest-runtimeで定義されており、wasmファイルでなければ実態はResolver.unstable_shouldLoadAsEsm()である
Resolver.unstable_shouldLoadAsEsm()は./shouldLoadAsEsmでexportされており
実態はcachedShouldLoadAsEsm
cachedShouldLoadAsEsmの中でshouldLoadAsEsmが実行されており、runtime.unstable_shouldLoadAsEsm(path)ではファイルの拡張子か package.json の type を見て esm か cjs かを判定している
esm か cjs か判定して、テストファイルを require か import する
nus3runtime.requireModuleについてはjest-runtimeパッケージに実装があるので以下に記載する
最終的に、テストファイルとテスト対象のファイル(さらにその依存も含め)をbabelでトランスパイルしてそう
nus3対象の CJS ファイルを babel でトランスパイルしつつ、読み込み、その後runAndTransformResultsToJestFormat()を実行し、結果を格納してる
runAndTransformResultsToJestFormat()の実装は以下
で、run()を実行している
run()の実装は以下
test は以下の分岐で実行されてそう。関数で言うと_runTest
_runTestの実装は以下
_runTestの中で_callCircusTestが実行されている
_callCircusTestの実装は以下
_callCircusTestではcallAsyncCircusFnが呼ばれており、その実装箇所は以下
このcallAsyncCircusFnではtest変数にあるfnの中身は以下のようになっている
function () {
expect(sum(1, 2)).toBe(3);
}
try catch の中で、このfnを実行することでテストが落ちているかどうかを判定している。またこの実行を Promise で行い、何かしら error を throw するようであれば reject する
呼び出し元では reject されるようであればそれを catch し、テストが落ちたと判定してる
nus3TODO: なぜfn.call(testContext)が実行できるのか
これはテストコードのみでsum()はどこにも定義されていないはず
引数で渡されているtestContextの空オブジェクトのようだし
fn.callで呼ばれていることでfnが定義されている大元のtestからだと、テスト対象のモジュールにもアクセスできるのか？
nus3
jest-runtime
jest-circusが定義する jestAdapter に渡される runtime 部分の実装がある
nus3
requireModule
今回、動作確認をしているのはexamples/getting-started/sum.test.jsで CJS だし、ESM はそもそも jest だと ESM 対応が experimental なので CJS のやつを見る
requireModuleは以下に定義されている
requireModuleには引数が 4 つあるが、使われているのは from のみで、from は該当のテストのパス
以下で、manual モックの場合に、require の対象のパスを manual モックのパスに変更してたりする？
modulePathはthis._resolveCjsModule(from, moduleName)の返り値
this._resolveCjsModule(from, moduleName)では、moduleName が指定されない限りは、fromの値を返す
moduleRegistryの値は、今回動作確認してるテストだとここを通る
this._moduleRegistryの値は Map になっている
mainが自身の値を受け取っている(循環参照)
Map(0) {}
Map(1) {
'/$HOME/jest/examples/getting-started/sum.test.js' => <ref *1> {
children: [],
exports: {},
filename: '/$HOME/jest/examples/getting-started/sum.test.js',
id: '/$HOME/jest/examples/getting-started/sum.test.js',
isPreloading: false,
loaded: false,
path: '/$HOME/jest/examples/getting-started',
parent: [Getter],
paths: [
'/$HOME/jest/examples/getting-started/node_modules',
'/$HOME/jest/examples/node_modules',
'/$HOME/jest/node_modules',
'/$HOME/node_modules',
'/$USER/dev/node_modules',
'/$USER/node_modules',
'/Users/node_modules',
'/node_modules'
],
main: [Circular *1]
}
}
this._loadModuleでモジュールを読み込んでるのかな
this._loadModuleの実装
テストファイルの拡張子は.js なので以下の分岐に進み、this._execModuleが実行される
fromをテストパスだけにすると、console.log が 2 回実行されてる。なんでだ
テストファイルと、テストファイルが import(require)してるファイルが map に格納されてるからっぽい
this._execModuleの実装
this._execModuleに渡される localModule の filename が'/Users/nus3/dev/fork/jest/examples/getting-started/sum.test.js'と'/Users/nus3/dev/fork/jest/examples/getting-started/sum.js'の場合が対象のテストファイルを load してる場合だ
this.transformFileをした時点で、テストファイルとテストファイルが require したテスト対象のファイルはトランスパイルされている
// sum.test.js
"use strict";
var sum = require("./sum");
test("adds 1 + 2 to equal 3", function () {
expect(sum(1, 2)).toBe(3);
});
// sum.js
function sum(a, b) {
return a + b;
}
module.exports = sum;
この transform 処理はjest-transformパッケージの以下で定義されている
呼び出し元を辿っていくと_instrumentFile()という関数の中でbabelTransformが呼ばれてる
このbabelTransformはbabel-coreのtransformSyncを使っている
どうやら対象のテストファイルは babel を使ってトランスパイルされてる
nus3
jest-resolve
jest-runtimeで使っていたunstable_shouldLoadAsEsmの大元の実装はこのパッケージにある
cachedShouldLoadAsEsm()
jest-circusで使っていたruntime.unstable_shouldLoadAsEsm(path)の大元の実装部分。esm の判定を拡張子でやってる
詳細は以下のリンクに記載
nus3どのようにしてテスト関数を実行しているのか
例えば examples にある sum のテストの場合
最終的に jest の内部では、以下の部分でテスト関数を実行している
このfnは以下のようになっている
function () {
expect(sum(1, 2)).toBe(3);
}
このfnを実行するだけでは、expectとsumが require されていないため、テストが実行できないのでは？
テスト実行時にはjest-runtimeのrequireModuleをjest-circusのjestAdapter(projectConfig.testRunnerに指定されている path)で呼んでいる
テストファイルやテストファイルで呼び出されているモジュールはruntime.requireModuleを実行する際に babel でトランスパイルされている
runtime.requireModuleでは、テストファイルで呼んでいるモジュールも localModule の exports に追加している
の部分の出力はそれぞれ以下になり、テストファイルが依存しているexamples/getting-started/sum.jsの関数であるsumがトランスパイルされた状態でlocalModule.exportsに追加されている
if (from === "/jest/examples/getting-started/sum.test.js") {
console.log(modulePath);
console.log(localModule.exports);
// それぞれ出力は以下
// /examples/getting-started/sum.js
// [Function: sum]
// /examples/getting-started/sum.test.js
// {}
}
テストファイルで定義した関数を実行する前にjest/packages/jest-circus/build/jestAdapterInit.jsのinitializeを実行している
これがあることで、expectやsumなどの依存しているモジュールを localModule.exports に追加してる？
@jest/expectのexpectを runtime に突っ込んでそうな雰囲気はある
runtime.requireModuleの引数である from が/Users/nus3/dev/fork/jest/examples/getting-started/sum.test.jsの場合だとruntime.requireModuleは 2 回呼ばれており、それぞれ別の引数であるmoduleNameは undefined と./sumが渡されている