Jestを読む

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を実行するなど

packages

jestを実行すると、monorepoで管理されたpackages配下のパッケージが実行されるので、依存するパッケージを出てくる順番でみてみる

パッケージの実行順

実際にテストを実行している部分を、パッケージごとにみてみる

jestを実行した時に、呼ばれるパッケージ

2024/04/09まで読んでみてのイメージ

テストファイルと、その対象のファイル、そのほか依存しているモジュールに対してbabelでトランスパイルし、requireしておく
テストファイルの中で定義されたテストコードを実行する
テストコードはtry catchの中で実行し、実行したテストコードがerrorをthrowしたら、その呼び出しもとでテストは落ちたと判定するように
テスト結果を格納する

jestのbinは"./bin/jest.js"に実装されている

`jest`

"./bin/jest.js"ではjest-cliをrequire

nus3 2ヶ月前に更新

`jest-cli`

'jest-cli/bin/jest'では、jest-cli/src/run.tsのrun()が実行されている

nus3 2ヶ月前に更新

このrun()の中で実際にテストを実行している部分は@jest/coreのrunCLI()っぽい

nus3 2ヶ月前に更新

`@jest/core`

runCLI()

runCLI()の_run10000()のコールバック引数でテスト結果を変数に入れてそう

同じファイル上に_run10000()が実装されている

このonCompleteが結果を変数に入れるコールバックで、runWithoutWatch()の第4引数にそのまま渡されている

このonCompleteが引数として渡されたrunWithoutWatch()では、runJest()にそのまま渡している

関数名からjestを実行してそうだぞ

runJest()は同一パッケージ(@jest/core)内でexportされている関数

runJest()に渡されたonCompleteはprocessResults()で実行される

以下はprocessResults()でonCompleteが実行されている箇所

動作確認してみると、ここではprocessResults()の第一引数として渡されたrunResultsをonCompleteの第一引数に渡している

ということでテスト結果はprocessResults()の第一引数であるresults

このresultsはawait scheduler.scheduleTests(allTests, testWatcher);の返り値である

scheduler.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がファイルの中にあるテストケースごとの結果を配列で格納している

aggregateResultsは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 の場合の以下の処理が実行されていた

testRunner.on()は実装されているパッケージがjest-runnerなので、そっちに記載する

テスト結果の初期値入りオブジェクトを生成する関数。
TestScheduler.scheduleTestsの中で使用される

`@jest/test-result`

`makeEmptyAggregatedTestResult()`

テスト結果を受け取りAggregatedResultにその結果を追加する

`addResult()`

TestScheduler.scheduleTestsの中でテストが実行されていそうな以下の部分で使われている

`jest-runner`

`TestRunner.on`

定義されている場所は以下

TestRunner.onではTestRunnerのプライベートメソッドであるthis.#eventEmitter.onを実行してる
this.#eventEmitterはemitteryというパッケージを require している

このemitteryは非同期でイベントの listner や emit がシンプルにできるライブラリっぽい
TestRunner.onでは第一引数で指定したイベント名の listner を登録しており、this.#eventEmitter.emitで登録したイベントを実行してると推測

テスト結果が書き写されるイベント名はtest-file-successの時で、このイベントをemitしているのは手元で動作確認すると、yarn jest -- packages/jest-util/src/__tests__/nus3.test.tsのように対象のテストファイルを指定して実行する場合、#createInBandTestRun()の中でemitしている。

runTestInternalも同一ファイルに定義されている

this.#eventEmitter.emit('test-file-success', [test, result])で emit の際に渡される result はrunTestの返り値である

jest-runnter パッケージの中にrunTestは定義されていて、runTestInternalの返り値が result に格納されている

runTestInternalの返り値である 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 時に特定のコードを変換する処理を挟めるライブラリっぽい

https://github.com/danez/pirates

requireAndTranspileModuleの第一引数に渡した path のファイルを require してる認識で良さそ

testFrameworkはtransformer.requireAndTranspileModuleの第一引数に渡すモジュールを require してそう

testFrameworkの値はrequireAndTranspileModuleの第一引数の値が${HOME}/jest/packages/jest-circus/build/runner.jsの時

ということで result の値はjest/packages/jest-circus/build/runner.jsのモジュールが実行した返り値

対象のテストファイルのパスを引数に渡して、esm か cjs かをruntime.unstable_shouldLoadAsEsm(path)で判断してる

`jest-circus`

実際にテストを実行して結果を出力してそうなパッケージ

nus3 26日前に更新

テスト結果を返すtestFramework()の実態はpackages/jest-circus/src/runner.tsにある。
このモジュールはpackages/jest-circus/src/legacy-code-todo-rewrite/jestAdapter.tsが export するモジュールを使っている

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 する

nus3 19日前に更新

runtime.requireModuleについてはjest-runtimeパッケージに実装があるので以下に記載する

最終的に、テストファイルとテスト対象のファイル(さらにその依存も含め)をbabelでトランスパイルしてそう

runAndTransformResultsToJestFormat()の実装は以下

で、run()を実行している

対象の CJS ファイルを babel でトランスパイルしつつ、読み込み、その後runAndTransformResultsToJestFormat()を実行し、結果を格納してる

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 し、テストが落ちたと判定してる

requireModuleは以下に定義されている

TODO: なぜfn.call(testContext)が実行できるのか
これはテストコードのみでsum()はどこにも定義されていないはず
引数で渡されているtestContextの空オブジェクトのようだし

fn.callで呼ばれていることでfnが定義されている大元のtestからだと、テスト対象のモジュールにもアクセスできるのか？

nus3 26日前

`jest-runtime`

jest-circusが定義する jestAdapter に渡される runtime 部分の実装がある

nus3 19日前に更新

`requireModule`

今回、動作確認をしているのはexamples/getting-started/sum.test.jsで CJS だし、ESM はそもそも jest だと ESM 対応が experimental なので CJS のやつを見る

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