Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 14908] ファイルの概要

このコミットは、Go言語の標準ライブラリである testing パッケージ内の example.go ファイルに対する修正です。具体的には、GoのExample関数が正しくテスト結果を報告し、ビルドが失敗しないようにするための変更が加えられています。Example関数は、コードの動作例を示すために使用され、go test コマンドによって実行され、その出力が期待される出力と一致するかどうかが検証されます。このコミットは、Example関数の実行結果を判定するロジックに ok という真偽値を追加し、初期値を true とし、失敗した場合に false に設定することで、Example関数のテストが適切にパスまたはフェイルするように修正しています。

コミット

commit e19cdc651cfdf2d3aa847f9700df639ddc8af591
Author: Andrew Gerrand <adg@golang.org>
Date:   Fri Jan 18 12:25:41 2013 +1100

    testing: allow examples to pass (fix build)
    
    R=golang-dev
    CC=golang-dev
    https://golang.org/cl/7132050

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/e19cdc651cfdf2d3aa847f9700df639ddc8af591

元コミット内容

testing: allow examples to pass (fix build)

R=golang-dev
CC=golang-dev
https://golang.org/cl/7132050

変更の背景

このコミットの背景には、Go言語の testing パッケージにおけるExample関数のテスト実行ロジックに不備があったことが考えられます。Example関数は、コードの利用例を示すだけでなく、go test コマンドによって自動的にテストされるという重要な役割を持っています。しかし、何らかの理由でExample関数の実行結果が正しく評価されず、ビルドプロセスが失敗する、あるいはExampleが常に失敗と報告されるといった問題が発生していた可能性があります。

このコミットメッセージ「testing: allow examples to pass (fix build)」から、Example関数が期待通りにパスしない、またはその状態がビルドに悪影響を与えていたことが示唆されます。開発者は、Example関数がその意図通りに動作し、かつビルドプロセスを妨げないようにするために、この修正を行ったと推測されます。

前提知識の解説

Go言語の testing パッケージ

Go言語には、標準ライブラリとして testing パッケージが提供されており、ユニットテスト、ベンチマークテスト、そしてExample関数を用いたテストをサポートしています。

  • ユニットテスト: TestXxx という形式の関数で記述され、コードの個々のユニットが正しく動作するかを検証します。
  • ベンチマークテスト: BenchmarkXxx という形式の関数で記述され、コードのパフォーマンスを測定します。
  • Example関数: ExampleXxx という形式の関数で記述されます。これは単なるテストではなく、コードの利用例を示すためのものです。Example関数は、その関数のドキュメントの一部として表示され、go doc コマンドで確認できます。さらに重要なのは、go test コマンドを実行すると、Example関数内のコードが実行され、その標準出力がExample関数のコメントブロックに記述された期待される出力（Output: コメント）と一致するかどうかが自動的に検証される点です。これにより、ドキュメントとコードの動作が常に同期していることを保証できます。

Example関数の役割と重要性

Example関数は、Goのコードベースにおいて以下の点で非常に重要です。

  1. ドキュメンテーション: コードの具体的な使用方法を簡潔かつ明確に示します。これにより、他の開発者がライブラリや関数の使い方を素早く理解できます。
  2. テスト: go test によって自動的に実行され、その出力が検証されるため、Exampleが示すコードの動作が常に正しいことを保証します。これは、リファクタリングや変更によってExampleの動作が変わってしまった場合に、それを検知するのに役立ちます。
  3. ビルドの健全性: Example関数が正しく動作しない場合、go test が失敗し、結果としてCI/CDパイプラインでのビルドが失敗する可能性があります。これは、コードベース全体の健全性を保つ上で重要です。

このコミットは、Example関数がそのテストとしての役割を適切に果たし、ビルドプロセスに悪影響を与えないようにするための、testing パッケージ内部のロジック修正に関するものです。

技術的詳細

このコミットは、src/pkg/testing/example.go ファイル内の runExample 関数に焦点を当てています。runExample 関数は、個々のExample関数を実行し、その結果を評価する役割を担っています。

変更前は、runExample 関数がExample関数の実行結果をどのように判定していたか、具体的なコードがないため断定できませんが、このコミットの目的が「examples to pass (fix build)」であることから、Example関数の実行が成功したにもかかわらず、その結果が正しく「パス」として認識されていなかった、あるいはビルドが失敗する原因となっていた可能性が高いです。

このコミットでは、runExample 関数の戻り値である ok という真偽値（bool型）の変数に注目しています。この ok 変数は、Example関数の実行が成功したかどうかを示すフラグとして機能します。

変更の核心は以下の2点です。

  1. ok の初期化: runExample 関数の実行開始直後、ok 変数を true に明示的に初期化しています。これは、Example関数が特にエラーを報告しない限り、デフォルトで成功とみなすという意図を示しています。
  2. ok の更新: Example関数の実行中にエラー（fail != "" または err != nil）が発生した場合、ok 変数を false に設定しています。これにより、Example関数が失敗したことを正確に記録します。

この修正により、runExample 関数はExample関数の実行結果をより正確に ok 変数に反映できるようになり、その結果が go test コマンドによって適切に解釈され、ビルドの失敗が解消されることが期待されます。

コアとなるコードの変更箇所

--- a/src/pkg/testing/example.go
+++ b/src/pkg/testing/example.go
@@ -67,6 +67,7 @@ func runExample(eg InternalExample) (ok bool) {
 	}()
 
 	start := time.Now()
+	ok = true
 
 	// Clean up in a deferred call so we can recover if the example panics.
 	defer func() {
@@ -84,6 +85,7 @@ func runExample(eg InternalExample) (ok bool) {
 		}
 		if fail != "" || err != nil {
 			fmt.Printf("--- FAIL: %s (%v)\\n%s", eg.Name, d, fail)
+			ok = false
 		} else if *chatty {
 			fmt.Printf("--- PASS: %s (%v)\\n", eg.Name, d)
 		}

コアとなるコードの解説

このコミットは、src/pkg/testing/example.go ファイル内の runExample 関数に2行の変更を加えています。

  1. ok = true の追加:

    @@ -67,6 +67,7 @@ func runExample(eg InternalExample) (ok bool) {
 	}()

 	start := time.Now()
+	ok = true

    この行は、runExample 関数がExample関数の実行を開始する直前に挿入されています。ok は runExample 関数の戻り値として宣言されており、Example関数の実行が成功したかどうかを示す真偽値です。ここで ok を true に初期化することで、Example関数はデフォルトで成功すると仮定されます。これは、Example関数が明示的に失敗を示すまで、その状態を「パス」として扱うというロジックの変更を意味します。

  2. ok = false の追加:

    @@ -84,6 +85,7 @@ func runExample(eg InternalExample) (ok bool) {
 		}
 		if fail != "" || err != nil {
 			fmt.Printf("--- FAIL: %s (%v)\\n%s", eg.Name, d, fail)
+			ok = false
 		} else if *chatty {
 			fmt.Printf("--- PASS: %s (%v)\\n", eg.Name, d)
 		}

    この行は、Example関数の実行が完了し、その結果を評価する部分に挿入されています。if fail != "" || err != nil という条件は、Example関数が期待される出力と一致しなかった場合（fail 文字列が空でない）か、実行中にエラーが発生した場合（err が nil でない）に真となります。つまり、Example関数が失敗したと判断された場合に、ok 変数を false に設定しています。これにより、Example関数の失敗が正確に runExample 関数の戻り値に反映されるようになります。

これらの変更により、runExample 関数はExample関数の実行結果をより正確に ok 変数を通じて呼び出し元に伝えることができるようになり、Example関数のテストが適切にパスまたはフェイルとして処理され、「fix build」というコミットメッセージの目的が達成されます。

関連リンク

参考にした情報源リンク