golden_tests.md

ゴールデンテスト

TFF には、ゴールデンテストの記述と管理を簡単に行えるようにする golden という小さなライブラリが含まれています。

ゴールデンテストとは？いつ使用しますか？

ゴールデンテストは、開発者に、コードによって関数の出力が変化したことを知らせるときに使用します。これらのテストは、明確に文書化されたプロパティの特定のセットをテストするのではなく、関数の正確な出力について約束するという点で、優れたユニットテストの多くの特性と異なります。ゴールデン出力の変化が「期待」されるものなのか、ゴールデンテストが適用しようとするプロパティを違反しているものなのかが明確でないことがあります。そのため、十分な結果を生み出すユニットテストの方がゴールデンテストよりも好ましいのが通例です。

ただし、ゴールデンテストは、エラーメッセージ、診断、または生成されたコードの実際のコンテンツを検証する際に非常に役立つことがあります。こういった場合には、ゴールデンテストは、生成された出力への変更が「正しく見える」ことを確認するのに役立つ信頼性チェックになります。

golden を使ってテストを記述するには？

golden ライブラリへの主なエントリーポイントは golden.check_string(filename, value) です。再度のパス要素が filename であるファイルのコンテンツに対して、value 文字列がチェックされます。filename へのフルパスは、コマンドラインの --golden <path_to_file> 引数で指定されている必要がありアンス。同様に、これらのファイルは、py_test BUILD ルールの data 引数を使用して、テストに公開されている必要があります。該当する正しい相対パスを生成するには location 関数を使用してください。

py_string_test(
  ...
  args = [
    "--golden",
    "$(location path/to/first_test_output.expected)",
    ...
    "--golden",
    "$(location path/to/last_test_output.expected)",
  ],
  data = [
    "path/to/first_test_output.expected",
    ...
    "path/to/last_test_output.expected",
  ],
  ...
)

慣例により、ゴールデンファイルはテストターゲットと同じ名前で _goldens という接尾辞を使用して、兄弟ディレクトリに配置されます。

path/
  to/
    some_test.py
    some_test_goldens/
      test_case_one.expected
      ...
      test_case_last.expected

.expected ファイルを更新するには？

.expected ファイルは、影響のあるテストターゲットを引数 --test_arg=--update_goldens --test_strategy=local で実行することで更新できます。生成される差分について、予期しない変更がないかをチェックする必要があります。