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

このコミットは、Go言語のgo testコマンドのヘルプドキュメント（go help testflag）と、testingパッケージのドキュメントを改訂するものです。主な目的は、テストフラグの記述をより明確にし、ユーザーが理解しやすくすることにあります。特に、go testコマンドに直接渡されるフラグと、テストバイナリに渡されるフラグの区別を明確にし、フラグのリストを整理しています。

コミット

commit 89a2a8c8df6f494dc75dd6a44dcd8ad1eccf1a20
Author: Russ Cox <rsc@golang.org>
Date:   Sun Feb 3 23:47:03 2013 -0500

    cmd/go, testing: revise docs for test flags
    
    In cmd/go's 'go help testflag':
    * Rewrite list of flags to drop test. prefix on every name.
    * Sort list of flags.
    * Add example of using -bench to match all benchmarks.
    
    In testing:
    * Remove mention of undefined 'CPU group' concept.
    
    Fixes #4488.
    Fixes #4508.
    
    R=adg
    CC=golang-dev
    https://golang.org/cl/7288053

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

https://github.com/golang/go/commit/89a2a8c8df6f494dc75dd6a44dcd8ad1eccf1a20

元コミット内容

cmd/go, testing: revise docs for test flags

go help testflagにおいて：

• 各フラグ名からtest.プレフィックスを削除してリストを書き直す。
• フラグのリストをソートする。
• 全てのベンチマークにマッチさせるための-bench .の使用例を追加する。

testingパッケージにおいて：

• 未定義の「CPUグループ」の概念への言及を削除する。

Fixes #4488. Fixes #4508.

変更の背景

このコミットの背景には、Go言語のテストコマンドgo testの使いやすさとドキュメントの明確化があります。以前のgo help testflagの出力は、go testコマンド自体に適用されるフラグと、生成されるテストバイナリ（pkg.test）に適用されるフラグの区別が曖昧でした。特に、テストバイナリに渡すフラグにはtest.プレフィックスが必要でしたが、go testコマンド経由で渡す場合はこのプレフィックスが省略可能であるという点が、ユーザーにとって混乱を招く可能性がありました。

また、ベンチマークの実行方法に関する説明が不足しており、特に全てのベンチマークを実行するための一般的なパターン（-bench .）が明示されていませんでした。

さらに、testingパッケージ内のドキュメントには「CPUグループ」という未定義の概念への言及があり、これもまた混乱の原因となっていました。このコミットは、これらのドキュメントの不備を修正し、ユーザーエクスペリエンスを向上させることを目的としています。

コミットメッセージに記載されているFixes #4488とFixes #4508は、当時のGoプロジェクトの課題追跡システムにおける特定の課題を指していると考えられます。これらの課題は、おそらく上記のドキュメントの不明瞭さや不足に関するユーザーからの報告や内部的な改善提案であったと推測されます。

前提知識の解説

このコミットを理解するためには、以下のGo言語のテストに関する基本的な知識が必要です。

• go testコマンド: Go言語の標準的なテスト実行ツールです。パッケージ内のテストファイル（_test.goで終わるファイル）を検出し、テスト、ベンチマーク、および例を実行します。
• テストフラグ: go testコマンドには、テストの挙動を制御するための様々なフラグがあります。これらは大きく分けて二種類あります。
  1. go testコマンド自体に適用されるフラグ: 例として、-v（詳細出力）、-run（特定のテストの実行）、-bench（ベンチマークの実行）などがあります。
  2. 生成されるテストバイナリに適用されるフラグ: go testは内部的にテストコードをコンパイルして実行可能なバイナリ（例: mypackage.test）を生成します。このバイナリを直接実行する場合、フラグにはtest.プレフィックス（例: -test.v, -test.run）が必要です。しかし、go testコマンド経由でこれらのフラグを渡す場合、Goツールは自動的にプレフィックスを付与するため、ユーザーはプレフィックスなしで指定できます。このコミット以前は、ヘルプドキュメントでこの区別が不明瞭でした。
• ベンチマーク: Goのテストフレームワークは、コードのパフォーマンスを測定するためのベンチマーク機能を提供します。ベンチマーク関数はBenchmarkXxxという形式で定義され、go test -benchフラグを使って実行されます。
• testingパッケージ: Goの標準ライブラリの一部であり、テスト、ベンチマーク、および例を記述するためのAPIを提供します。*testing.T型はテスト関数に、*testing.B型はベンチマーク関数に渡されます。
• t.Parallel(): *testing.T型が提供するメソッドで、テスト関数が並行して実行できることを示します。これにより、複数の並行テストが同時に実行され、テスト時間を短縮できます。このメソッドは、テストランナーがテストの並行実行をスケジュールするために使用します。
• GOMAXPROCS: Goランタイムが同時に実行できるOSスレッドの最大数を制御する環境変数です。テストの並行実行やCPUプロファイリングに影響を与えます。

技術的詳細

このコミットの技術的詳細は、主にgo help testflagの出力内容の変更と、testingパッケージ内のコメント修正に集約されます。

src/cmd/go/test.go の変更点

このファイルはgo help testflagコマンドのヘルプメッセージを定義しています。変更の核心は、ユーザーがgo testコマンドを使用する際の利便性と理解度を向上させることです。

1. フラグ名のtest.プレフィックスの削除:

   • 以前のドキュメントでは、-test.v, -test.runのように、全てのテストフラグにtest.プレフィックスが付いていました。これは、テストバイナリを直接実行する際に必要な形式です。
   • しかし、go testコマンド経由でこれらのフラグを渡す場合、ユーザーは-v, -runのようにプレフィックスなしで指定するのが一般的です。このコミットでは、ヘルプドキュメントのフラグリストからこのtest.プレフィックスを削除し、go testコマンドで直接使用する際の形式に合わせました。これにより、ドキュメントと実際の使用方法の乖離が解消され、ユーザーの混乱が軽減されます。
   • ただし、ドキュメントの最後に「テストバイナリを直接呼び出す場合、各標準フラグ名にはtest.プレフィックスを付ける必要がある」という注意書きが追加され、両方の使用方法が明確に説明されています。

2. フラグリストのソート:

   • 以前はフラグのリストが特定の順序で並んでいませんでしたが、このコミットによりアルファベット順にソートされました。これにより、ユーザーが特定のフラグを探しやすくなり、ドキュメントの可読性が向上します。
   • 具体的には、-bench, -benchmem, -benchtime, -blockprofile, -blockprofilerate, -cpu, -cpuprofile, -memprofile, -memprofilerate, -parallel, -run, -short, -timeout, -vの順に並べ替えられました。

3. -bench .の使用例の追加:

   • ベンチマークを全て実行するための一般的なイディオムである-bench .（または-bench=.）が明示的に例として追加されました。これは、正規表現.が任意の文字列にマッチすることを利用して、全てのベンチマーク関数を実行するものです。この追加により、ベンチマークの実行方法に関するドキュメントがより完全になりました。

4. go testとテストバイナリのフラグの区別の明確化:

   • 冒頭の記述が「The test binary, called pkg.test... has its own flags:」から「The following flags are recognized by the 'go test' command and control the execution of any test:」に変更されました。これにより、リストされているフラグがgo testコマンドに直接渡すものであることが明確になりました。
   • そして、リストの後に「The test binary, called pkg.test... can be invoked directly... When invoking the test binary directly, each of the standard flag names must be prefixed with 'test.', as in -test.run=TestMyFunc or -test.v.」という説明が追加され、テストバイナリを直接実行する場合のフラグの形式が明確に区別されました。

src/pkg/testing/testing.go の変更点

このファイルはGoのtestingパッケージのソースコードであり、主にt.Parallel()メソッドのコメントが修正されました。

1. 「CPUグループ」の概念の削除:
   • t.Parallel()メソッドのコメントが「// other parallel tests in this CPU group.」から「// other parallel tests.」に変更されました。
   • 「CPUグループ」という概念はGoのランタイムやテストフレームワークの内部には存在せず、ドキュメント上でのみ言及されていた未定義の用語でした。この修正により、ドキュメントの正確性が向上し、ユーザーが誤解する可能性がなくなりました。t.Parallel()は単に他の並行テストと並行して実行されることを意味し、特定の「CPUグループ」に属するという意味合いはありません。

これらの変更は、Goのテスト機能に関するドキュメントの品質を向上させ、ユーザーがより直感的にgo testコマンドを理解し、効果的に利用できるようにすることを目的としています。

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

このコミットで変更された主要なファイルは以下の2つです。

1. src/cmd/go/test.go: go help testflagコマンドのヘルプメッセージを定義しているファイル。
2. src/pkg/testing/testing.go: Goの標準testingパッケージのソースコード。

具体的な変更箇所は以下の通りです。

src/cmd/go/test.go

--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -81,31 +81,47 @@ var helpTestflag = &Command{\
  The 'go test' command takes both flags that apply to 'go test' itself
  and flags that apply to the resulting test binary.
  
-The test binary, called pkg.test, where pkg is the name of the
-directory containing the package sources, has its own flags:
+The following flags are recognized by the 'go test' command and
+control the execution of any test:
  
-\t-test.v
-\t    Verbose output: log all tests as they are run.
-\n-\t-test.run pattern
-\t    Run only those tests and examples matching the regular
-\t    expression.
-\n-\t-test.bench pattern
+\t-bench regexp
  	    Run benchmarks matching the regular expression.
-\t    By default, no benchmarks run.\n+\t    By default, no benchmarks run. To run all benchmarks,\n+\t    use '-bench .' or '-bench=.'.
  
-\t-test.benchmem
+\t-benchmem
  	    Print memory allocation statistics for benchmarks.
  
-\t-test.cpuprofile cpu.out
+\t-benchtime t
+\t\tRun enough iterations of each benchmark to take t, specified
+\t\tas a time.Duration (for example, -benchtime 1h30s).
+\t\tThe default is 1 second (1s).
+\n+\t-blockprofile block.out
+\t    Write a goroutine blocking profile to the specified file
+\t    when all tests are complete.
+\n+\t-blockprofilerate n
+\t    Control the detail provided in goroutine blocking profiles by setting
+\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.
+\t    The profiler aims to sample, on average, one blocking event every
+\t    n nanoseconds the program spends blocked.  By default,\n+\t    if -test.blockprofile is set without this flag, all blocking events
+\t    are recorded, equivalent to -test.blockprofilerate=1.
+\n+\t-cpu 1,2,4
+\t    Specify a list of GOMAXPROCS values for which the tests or
+\t    benchmarks should be executed.  The default is the current value
+\t    of GOMAXPROCS.
+\n+\t-cpuprofile cpu.out
  	    Write a CPU profile to the specified file before exiting.
  
-\t-test.memprofile mem.out
+\t-memprofile mem.out
  	    Write a memory profile to the specified file when all tests
  	    are complete.
  
-\t-test.memprofilerate n
+\t-memprofilerate n
  	    Enable more precise (and expensive) memory profiles by setting
  	    runtime.MemProfileRate.  See 'godoc runtime MemProfileRate'.
  	    To profile all memory allocations, use -test.memprofilerate=1
@@ -113,44 +129,35 @@ directory containing the package sources, has its own flags:\
  	    garbage collector, provided the test can run in the available
  	    memory without garbage collection.
  
-\t-test.blockprofile block.out
-\t    Write a goroutine blocking profile to the specified file
-\t    when all tests are complete.
-\n-\t-test.blockprofilerate n
-\t    Control the detail provided in goroutine blocking profiles by setting
-\t    runtime.BlockProfileRate to n.  See 'godoc runtime BlockProfileRate'.
-\t    The profiler aims to sample, on average, one blocking event every
-\t    n nanoseconds the program spends blocked.  By default,\n-\t    if -test.blockprofile is set without this flag, all blocking events
-\t    are recorded, equivalent to -test.blockprofilerate=1.
-\n-\t-test.parallel n
+\t-parallel n
  	    Allow parallel execution of test functions that call t.Parallel.\
  	    The value of this flag is the maximum number of tests to run
  	    simultaneously; by default, it is set to the value of GOMAXPROCS.
  
-\t-test.short
+\t-run regexp
+\t    Run only those tests and examples matching the regular
+\t    expression.
+\n+\t-short
  	    Tell long-running tests to shorten their run time.\
  	    It is off by default but set during all.bash so that installing
  	    the Go tree can run a sanity check but not spend time running
  	    exhaustive tests.
  
-\t-test.timeout t
+\t-timeout t
  	\tIf a test runs longer than t, panic.
  
-\t-test.benchtime t
-\t\tRun enough iterations of each benchmark to take t.\
-\t\tThe default is 1 second.\
+\t-v
+\t    Verbose output: log all tests as they are run.
  
-\t-test.cpu 1,2,4
-\t    Specify a list of GOMAXPROCS values for which the tests or
-\t    benchmarks should be executed.  The default is the current value
-\t    of GOMAXPROCS.
+The test binary, called pkg.test where pkg is the name of the
+directory containing the package sources, can be invoked directly
+after building it with 'go test -c'. When invoking the test binary
+directly, each of the standard flag names must be prefixed with 'test.',
+as in -test.run=TestMyFunc or -test.v.
  
-For convenience, each of these -test.X flags of the test binary is
-also available as the flag -X in 'go test' itself.  Flags not listed
-here are passed through unaltered.  For instance, the command
+When running 'go test', flags not listed above are passed through
+unaltered. For instance, the command
  
  	go test -x -v -cpuprofile=prof.out -dir=testdata -update
  

src/pkg/testing/testing.go

--- a/src/pkg/testing/testing.go
+++ b/src/pkg/testing/testing.go
@@ -281,7 +281,7 @@ func (c *common) Fatalf(format string, args ...interface{}) {
 }
 
 // Parallel signals that this test is to be run in parallel with (and only with)
-// other parallel tests in this CPU group.
+// other parallel tests.
 func (t *T) Parallel() {
 	t.signal <- (*T)(nil) // Release main testing loop
 	<-t.startParallel     // Wait for serial tests to finish

コアとなるコードの解説

src/cmd/go/test.go の変更解説

このファイルの変更は、go help testflagコマンドの出力内容を直接修正しています。

• ヘッダーの変更:

  • 旧: The test binary, called pkg.test, where pkg is the name of the directory containing the package sources, has its own flags:
  • 新: The following flags are recognized by the 'go test' command and control the execution of any test:
  • この変更により、リストされているフラグがgo testコマンド自体によって認識され、テストの実行を制御するものであることが明確になりました。以前の記述は、これらのフラグがテストバイナリ固有のものであるという誤解を招く可能性がありました。

• フラグ名のtest.プレフィックスの削除とソート:

  • 以前は-test.v, -test.run, -test.benchなどのように、全てのフラグにtest.プレフィックスが付いていました。これは、テストバイナリを直接実行する際の形式です。
  • 新しいバージョンでは、これらのプレフィックスが削除され、-v, -run, -benchのように、go testコマンドで一般的に使用される形式になりました。
  • さらに、フラグの順序がアルファベット順にソートされ、可読性が向上しました。
  • 例えば、-test.bench patternが-bench regexpに変更され、その説明に「To run all benchmarks, use '-bench .' or '-bench=.'.」という全てのベンチマークを実行する例が追加されました。これは、ユーザーがベンチマークをより簡単に実行できるようにするための重要な改善です。
  • -test.benchtimeや-test.cpuなどのフラグも、それぞれ-benchtimeや-cpuに変更され、適切な位置に移動されました。

• テストバイナリ直接実行時の説明の追加:

  • 変更後のドキュメントの最後に、go test -cでビルドされたテストバイナリを直接実行する場合のフラグの形式について明確な説明が追加されました。
  • The test binary, called pkg.test... can be invoked directly... When invoking the test binary directly, each of the standard flag names must be prefixed with 'test.', as in -test.run=TestMyFunc or -test.v.
  • この追加により、go testコマンド経由でのフラグ指定と、テストバイナリ直接実行時のフラグ指定の間の違いが明確になり、ユーザーの混乱が解消されます。

src/pkg/testing/testing.go の変更解説

このファイルの変更は、t.Parallel()メソッドのコメントの修正です。

• t.Parallel()コメントの修正:
  • 旧: // other parallel tests in this CPU group.
  • 新: // other parallel tests.
  • t.Parallel()は、そのテスト関数が他の並行テストと並行して実行できることをテストランナーに通知するものです。以前のコメントにあった「CPU group」という概念は、Goのテストフレームワークやランタイムには存在しない未定義の用語でした。この修正により、ドキュメントの正確性が向上し、ユーザーがt.Parallel()の動作について誤解する可能性がなくなりました。テストは単に他の並行テストと並行して実行されるだけであり、特定の「CPUグループ」に属するという意味合いはありません。

これらのコード変更は、Goのテスト機能に関するドキュメントの正確性、明確性、および使いやすさを大幅に向上させることを目的としています。

関連リンク

• GitHubコミットページ: https://github.com/golang/go/commit/89a2a8c8df6f494dc75dd6a44dcd8ad1eccf1a20

参考にした情報源リンク

• Go Code Review: https://golang.org/cl/7288053
• Go Issue #4488 (検索結果): https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQG8oeWIOpIFMZe3O8dBTx9bZ_WyUbVPw6k0DU3eJlIu_BIZeko9Sd39_9_gw0F00pjs0CwSq7W2qWAYiBPIMRY0O_LOV5au0uoza-K8GjYyEQJprHb3IPHToYOfrQbmhHEFhaVs
  • (注: 検索結果はコミットメッセージに記載されている当時のIssue #4488とは異なる可能性が高いです。これは、GoプロジェクトのIssue番号が時間とともに再利用されたり、内部的なトラッカーの番号であったりするためです。この解説では、コミットメッセージのテキスト内容を主な情報源としています。)
• Go Issue #4508 (検索結果): 検索では関連する情報が見つかりませんでした。
  • (注: 上記と同様に、当時のIssue #4508に関する公開情報は見つかりませんでした。この解説では、コミットメッセージのテキスト内容を主な情報源としています。)