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

このコミットは、Go言語の公式ツールチェインの一部であるgoコマンドのドキュメントと内部ヘルプメッセージを更新するものです。具体的には、go testコマンドで使用される-test.runフラグの説明に、「examples」（例示コード）も正規表現のパターンマッチングの対象となることを明記する変更が加えられています。これにより、ユーザーが-test.runフラグの挙動をより正確に理解できるようになります。

コミット

commit 5573fa3bc57754847e3b9a5c9493cdbf29af32b9
Author: Rob Pike <r@golang.org>
Date:   Tue Feb 28 08:55:25 2012 +1100

    cmd/go: mention examples in docs for -test.run
    Missed in my last round. These things sure appear
    in a lot of places.
    
    R=golang-dev, gri
    CC=golang-dev
    https://golang.org/cl/5699096

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

https://github.com/golang/go/commit/5573fa3bc57754847e3b9a5c9493cdbf29af32b9

元コミット内容

cmd/go: mention examples in docs for -test.run
Missed in my last round. These things sure appear
in a lot of places.

R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5699096

変更の背景

このコミットは、Go言語のテストフレームワークにおける-test.runフラグのドキュメントの正確性を向上させることを目的としています。Goのテストシステムでは、通常のテスト関数（TestXxx）に加えて、パッケージの使用例を示すExampleXxx関数も実行されます。これらのExample関数は、ドキュメント生成にも利用されると同時に、go testコマンドによって自動的にテストされ、期待される出力と一致するかどうかが検証されます。

以前のドキュメントでは、-test.runフラグが「テストのみ」を対象とすると記述されていましたが、実際にはExample関数もこのフラグの正規表現パターンマッチングの対象となっていました。この不一致を修正し、ユーザーが-test.runフラグを使って特定のテストや例示コードを選択的に実行できることを明確にするために、この変更が導入されました。コミットメッセージにある「Missed in my last round. These things sure appear in a lot of places.」という記述は、このようなドキュメントの不整合が複数の箇所に存在し、見落とされがちであることを示唆しています。

前提知識の解説

Go言語のテスト

Go言語には、標準ライブラリtestingパッケージを用いた組み込みのテストフレームワークがあります。テストファイルは通常、テスト対象のGoファイルと同じディレクトリに_test.goというサフィックスを付けて配置されます。

テスト関数: func TestXxx(*testing.T)というシグネチャを持つ関数で、特定の機能の正しさを検証します。
ベンチマーク関数: func BenchmarkXxx(*testing.B)というシグネチャを持つ関数で、コードのパフォーマンスを測定します。
Example関数: func ExampleXxx()というシグネチャを持つ関数で、パッケージや関数の使用例を示します。これらの関数は、go docコマンドで生成されるドキュメントに組み込まれるだけでなく、go testコマンドによって実行され、コメントとして記述された期待される出力（// Output:）と実際の出力が一致するかどうかが検証されます。これにより、ドキュメントのコード例が常に動作することを保証します。

`go test`コマンド

go testコマンドは、Goパッケージのテストを実行するための主要なツールです。このコマンドは、指定されたパッケージ内の_test.goファイルを見つけ、その中のテスト関数、ベンチマーク関数、Example関数を実行します。

`-test.run`フラグ

go testコマンドには、テストの実行を制御するための様々なフラグがあります。その一つが-test.runフラグです。 -test.run <pattern>: このフラグは、指定された正規表現パターンに一致する名前のテスト関数、ベンチマーク関数、およびExample関数のみを実行します。これにより、開発者は特定のテストケースや例示コードに焦点を当てて実行することができます。例えば、go test -test.run "MyFeature"とすると、名前に"MyFeature"を含むテストやExample関数のみが実行されます。

`src/cmd/go/doc.go`と`src/cmd/go/test.go`

src/cmd/go/doc.go: これはgoコマンド自体のドキュメントを生成するためのソースファイルです。go helpコマンドなどで表示されるヘルプメッセージの元となる情報が含まれています。
src/cmd/go/test.go: これはgo testコマンドの内部実装に関連するソースファイルです。コマンドライン引数のパースや、テスト実行ロジックの一部が定義されています。

これらのファイルは、Goツールチェインのユーザー向けドキュメントと内部実装の両方で、-test.runフラグの挙動を説明する箇所を保持しています。

技術的詳細

このコミットの技術的詳細は、Goツールチェインのドキュメント生成とコマンドライン引数処理の仕組みにあります。

goコマンドのヘルプメッセージは、Goソースコード内の特定のコメントブロックから自動的に抽出されることがあります。src/cmd/go/doc.goファイルは、まさにその目的のために存在し、go helpコマンドが提供する詳細なドキュメントの大部分を構成しています。このファイル内のコメントは、Goのドキュメンテーションツールによって解析され、整形されたヘルプテキストとして表示されます。

一方、src/cmd/go/test.goは、go testコマンドの具体的な動作を定義するコードを含んでいます。ここには、-test.runのようなフラグがどのように定義され、その説明がどのようにユーザーに提示されるかが記述されています。多くの場合、ドキュメントファイルと実装ファイルの両方で同じ説明が重複して記述されることがあります。これは、ユーザーがgo help testのように特定のサブコマンドのヘルプを求めた場合と、go test -hのようにコマンド固有のヘルプを求めた場合の両方で、一貫した情報を提供するためです。

このコミットでは、両方のファイルで-test.runの説明を修正することで、ドキュメントの一貫性と正確性を確保しています。変更自体は非常にシンプルで、既存の文字列に「and examples」というフレーズを追加するだけですが、これによりGoのテストシステムにおけるExample関数の役割がより明確にユーザーに伝わるようになります。

Goのテストシステムは、内部的にtestingパッケージを使用してテスト、ベンチマーク、Example関数を識別し、実行します。-test.runフラグに渡された正規表現は、これらの関数名に対してマッチングが行われます。したがって、Example関数もこのマッチングの対象となるのは、Goのテストシステムの設計上自然な挙動です。このコミットは、その自然な挙動をドキュメントに反映させたものです。

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

このコミットでは、以下の2つのファイルが変更されています。

src/cmd/go/doc.go
src/cmd/go/test.go

それぞれのファイルで、-test.run patternの説明文が修正されています。

`src/cmd/go/doc.go`の変更

--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -565,7 +565,8 @@ directory containing the package sources, has its own flags:
 	    Verbose output: log all tests as they are run.
 
 	-test.run pattern
-	    Run only those tests matching the regular expression.
+	    Run only those tests and examples matching the regular
+	    expression.
 
 	-test.bench pattern
 	    Run benchmarks matching the regular expression.

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

--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -93,7 +93,8 @@ directory containing the package sources, has its own flags:
 	    Verbose output: log all tests as they are run.
 
 	-test.run pattern
-	    Run only those tests matching the regular expression.
+	    Run only those tests and examples matching the regular
+	    expression.
 
 	-test.bench pattern
 	    Run benchmarks matching the regular expression.

コアとなるコードの解説

両方のファイルで、-test.run patternの記述が以下のように変更されています。

変更前: Run only those tests matching the regular expression. （正規表現に一致するテストのみを実行します。）

変更後: Run only those tests and examples matching the regular expression. （正規表現に一致するテストと例示コードのみを実行します。）

この変更は、既存の文字列に「and examples」というフレーズを追加し、改行を調整しただけです。これにより、-test.runフラグがテスト関数だけでなく、Example関数にも適用されるという事実が明確に伝わるようになります。これは、GoのテストシステムがExample関数もテストの一部として扱い、-test.runフラグがそれらの実行も制御できるという、実際の挙動を正確に反映したものです。

この修正は、ユーザーがgo test -test.runを使用する際に、Example関数も対象となることを期待できるようになり、ドキュメントと実際の動作の間のギャップを埋める上で重要です。

参考にした情報源リンク

Go言語のソースコードリポジトリ: https://github.com/golang/go
Go Code Review Comments (Goのコードレビューガイドライン): https://github.com/golang/go/wiki/CodeReviewComments
GoのIssue Tracker (このコミットに関連するIssueがある場合): https://github.com/golang/go/issues
GoのCL (Change List) ページ: https://golang.org/cl/5699096 (コミットメッセージに記載されているCLへのリンク)
Goのテストに関する一般的な情報源（例: Go By Example, A Tour of Goなど）

comemo