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

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

このコミットは、Go言語の公式ツールチェインにおけるgo testコマンドのヘルプメッセージを拡充し、従来のgotestコマンドからの移行を促進することを目的としています。具体的には、gotestが提供していた詳細なドキュメントをgo testのヘルプシステムに統合し、ユーザーがgo testの機能、フラグ、テスト関数の書き方についてより簡単にアクセスできるようにしています。

コミット

  • コミットハッシュ: 143f3b38f5fe48d33bff8f76728739694b3e060f
  • 作者: Russ Cox rsc@golang.org
  • 日付: 2011年12月15日 木曜日 13:54:19 -0500

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

https://github.com/golang/go/commit/143f3b38f5fe48d33bff8f76728739694b3e060f

元コミット内容

go: help messages for 'go test'

The plan is to make 'go test' replace gotest entirely, so it
cannot refer to gotest's godoc. Instead, copy gotest's
documentation in as three different help messages:
'go help test', 'go help testflag', and 'go help testfunc'.

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

変更の背景

このコミットが行われた2011年当時、Go言語のテストツールはgotestという独立したコマンドとして存在していました。しかし、Go言語のツールチェインは、go buildやgo runのように、単一のgoコマンドの下にサブコマンドとして機能を統合する方向へと進化していました。この流れの中で、テスト機能もgo testとしてgoコマンドに統合される計画が進行していました。

gotestは独自のドキュメントを持っていましたが、go testがgotestを完全に置き換えるためには、gotestのドキュメントを参照するのではなく、go test自身がその機能に関する包括的な情報を提供する必要がありました。このコミットの背景には、ユーザーがgotestからgo testへスムーズに移行できるよう、必要なヘルプ情報をgo testの内部に組み込むという明確な意図があります。これにより、ユーザーはgo help test、go help testflag、go help testfuncといったコマンドを通じて、テストに関する詳細な情報を直接参照できるようになります。

前提知識の解説

Go言語のテストフレームワーク

Go言語には、標準ライブラリの一部としてtestingパッケージが提供されており、これを用いてテスト、ベンチマーク、および例（Example）を記述します。

  • テスト関数 (Test Functions):

    • Testで始まり、その後に大文字で始まる任意の文字列が続く関数名（例: TestMyFunction）。
    • シグネチャはfunc TestXXX(t *testing.T)。
    • *testing.T型は、テストの失敗報告、ログ出力、サブテストの実行などの機能を提供します。
    • テストファイルは、テスト対象のパッケージと同じディレクトリに配置され、ファイル名が_test.goで終わる必要があります（例: my_package_test.go）。

  • ベンチマーク関数 (Benchmark Functions):

    • Benchmarkで始まり、その後に大文字で始まる任意の文字列が続く関数名（例: BenchmarkMyFunction）。
    • シグネチャはfunc BenchmarkXXX(b *testing.B)。
    • *testing.B型は、ベンチマークの実行回数制御やタイマーのリセットなどの機能を提供します。
    • パフォーマンス測定に使用され、通常はgo test -bench=.のように-benchフラグを指定して実行します。

  • 例関数 (Example Functions):

    • Exampleで始まり、その後に大文字で始まる任意の文字列が続く関数名（例: ExamplePrintln）。
    • シグネチャはfunc ExampleXXX()またはfunc ExampleT_M()（メソッドの例の場合）。
    • os.Stdoutに出力された内容が関数のドキュメントコメントに記述された期待される出力と一致するかどうかで検証されます。
    • コードの利用例を示すために使用され、godocコマンドでドキュメントとして表示されます。

go testコマンド

go testは、Go言語のパッケージをテストするための主要なコマンドです。以下の機能を提供します。

  • テストの自動検出と実行: カレントディレクトリまたは指定されたインポートパスにあるパッケージ内の_test.goファイルを見つけ、テスト関数、ベンチマーク関数、例関数を自動的に実行します。
  • テストバイナリの生成: テスト対象のパッケージとテストコードをコンパイルし、一時的なテストバイナリを生成して実行します。これにより、通常のインストール済みパッケージに影響を与えません。
  • フラグのサポート: テストの実行方法を制御するための様々なフラグをサポートしています。これには、詳細出力、特定のテストの実行、CPUプロファイルやメモリプロファイルの生成などが含まれます。

gotestコマンド (旧来)

gotestは、go testが統合される以前に存在したGo言語のテスト実行ツールです。このコミットの時点では、go testへの移行が進められており、gotestはその役割を終えようとしていました。

技術的詳細

このコミットの技術的な核心は、gotestのドキュメントをgoコマンドのヘルプシステムに移植することです。これは主に以下の3つの新しいヘルプメッセージとして実装されています。

  1. go help test: go testコマンドの基本的な使い方と概要を説明します。
  2. go help testflag: go testコマンド自身が受け取るフラグと、生成されるテストバイナリが受け取るフラグ（-test.v, -test.run, -test.benchなど）について詳細に説明します。これにより、ユーザーはテストの挙動を細かく制御する方法を理解できます。
  3. go help testfunc: Go言語のテスト関数、ベンチマーク関数、例関数のシグネチャと命名規則、およびそれぞれの目的について説明します。これは、testingパッケージのドキュメントの要約版として機能します。

これらのヘルプメッセージは、src/cmd/go/test.goファイル内のCommand構造体として定義され、src/cmd/go/main.goのcommandsスライスに追加されることで、go helpコマンドからアクセス可能になります。

変更点を見ると、cmdTest（go testコマンドに対応）のUsageLineがより詳細になり、Longフィールド（go help testの出力内容）が大幅に拡張されています。また、helpTestflagとhelpTestfuncという新しいCommand構造体が定義され、それぞれが対応するヘルプメッセージの長い説明（Longフィールド）を含んでいます。これらの長い説明は、gotestの既存のドキュメントからコピーされた内容であり、go testの機能に関する包括的な情報を提供します。

このアプローチにより、go testは自己完結型のテストツールとなり、外部のgotestドキュメントへの依存がなくなります。

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

src/cmd/go/main.go

--- a/src/cmd/go/main.go
+++ b/src/cmd/go/main.go
@@ -72,6 +72,8 @@ var commands = []*Command{
 	helpGopath,
 	helpImportpath,
 	helpRemote,
+	helpTestflag,
+	helpTestfunc,
 }
 
 var exitStatus = 0

この変更は、新しく追加されたhelpTestflagとhelpTestfuncというCommand構造体を、goコマンドが認識するコマンドのリスト（commandsスライス）に追加しています。これにより、go help testflagおよびgo help testfuncとしてこれらのヘルプメッセージが利用可能になります。

src/cmd/go/test.go

--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -6,10 +6,10 @@ package main
 
 var cmdTest = &Command{
 	Run:       runTest,
-	UsageLine: "test [importpath...]",
+	UsageLine: "test [importpath...] [-file a.go -file b.go ...] [-c] [-x] [flags for test binary]",
 	Short:     "test packages",
 	Long: `
-Test runs gotest to test the packages named by the import paths.
+'Go test' automates testing the packages named by the import paths.
 It prints a summary of the test results in the format:
 
 	test archive/tar
@@ -17,14 +17,147 @@ It prints a summary of the test results in the format:
 	test compress/gzip
 	...
 
-followed by gotest output for each failed package.
+followed by detailed output for each failed package.
 
-For more about import paths, see 'go help importpath'.
+'Go test' recompiles each package along with any files with names matching
+the file pattern "_test.go".  These additional files can contain test functions,
+benchmark functions, and example functions.  See 'go help testfunc' for more.
+
+By default, gotest needs no arguments.  It compiles and tests the package
+with source in the current directory, including tests, and runs the tests.
+If file names are given (with flag -file=test.go, one per extra test source file),
+only those test files are added to the package.  (The non-test files are always
+compiled.)
+
+The package is built in a temporary directory so it does not interfere with the
+non-test installation.
+
+See 'go help testflag' for details about flags
+handled by 'go test' and the test binary.
+
+See 'go help importpath' for more about import paths.
 
 See also: go build, go compile, go vet.
 	`,
 }
 
+var helpTestflag = &Command{
+	UsageLine: "testflag",
+	Short:     "description of testing flags",
+	Long: `
+The 'go test' command takes both flags that apply to 'go test' itself
+and flags that apply to the resulting test binary.
+
+The flags handled by 'go test' are:
+
+	-c  Compile the test binary to test.out but do not run it.
+
+	-file a.go
+	    Use only the tests in the source file a.go.
+	    Multiple -file flags may be provided.
+
+	-x  Print each subcommand gotest executes.
+
+The resulting test binary, called test.out, has its own flags:
+
+	-test.v
+	    Verbose output: log all tests as they are run.
+
+	-test.run pattern
+	    Run only those tests matching the regular expression.
+
+	-test.bench pattern
+	    Run benchmarks matching the regular expression.
+	    By default, no benchmarks run.
+
+	-test.cpuprofile cpu.out
+	    Write a CPU profile to the specified file before exiting.
+
+	-test.memprofile mem.out
+	    Write a memory profile to the specified file when all tests
+	    are complete.
+
+	-test.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
+	    and set the environment variable GOGC=off to disable the
+	    garbage collector, provided the test can run in the available
+	    memory without garbage collection.
+
+	-test.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.
+
+	-test.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.
+
+	-test.timeout n
+		If a test runs longer than n seconds, panic.
+
+	-test.benchtime n
+		Run enough iterations of each benchmark to take n seconds.
+		The default is 1 second.
+
+	-test.cpu 1,2,4
+	    Specify a list of GOMAXPROCS values for which the tests or 
+	    benchmarks should be executed.  The default is the current value
+	    of GOMAXPROCS.
+
+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
+
+	go test -x -v -cpuprofile=prof.out -dir=testdata -update -file x_test.go
+
+will compile the test binary using x_test.go and then run it as
+
+	test.out -test.v -test.cpuprofile=prof.out -dir=testdata -update
+	`,
+}
+
+var helpTestfunc = &Command{
+	UsageLine: "testfunc",
+	Short:     "description of testing functions",
+	Long: `
+The 'go test' command expects to find test, benchmark, and example functions
+in the "_test.go" files corresponding to the package under test.
+
+A test function is one named TestXXX (where XXX is any alphanumeric string
+not starting with a lower case letter) and should have the signature,
+
+	func TestXXX(t *testing.T) { ... }
+
+A benchmark function is one named BenchmarkXXX and should have the signature,
+
+	func BenchmarkXXX(b *testing.B) { ... }
+
+An example function is similar to a test function but, instead of using *testing.T
+to report success or failure, prints output to os.Stdout and os.Stderr.
+That output is compared against the function's doc comment.
+An example without a doc comment is compiled but not executed.
+
+Godoc displays the body of ExampleXXX to demonstrate the use
+of the function, constant, or variable XXX.  An example of a method M with
+receiver type T or *T is named ExampleT_M.  There may be multiple examples
+for a given function, constant, or variable, distinguished by a trailing _xxx,
+where xxx is a suffix not beginning with an upper case letter.
+
+Here is an example of an example:
+
+	// The output of this example function.
+	func ExamplePrintln() {
+		Println("The output of this example function.")
+	}
+
+See the documentation of the testing package for more information.
+		`,
+}
+
 func runTest(cmd *Command, args []string) {
 	args = importPaths(args)
 	_ = args

このファイルでは、以下の主要な変更が行われています。

  1. cmdTestの更新:

    • UsageLineがより詳細になり、go testが受け入れる一般的なフラグ（-file, -c, -x）と、テストバイナリに渡されるフラグのプレースホルダーが追加されました。
    • Longフィールドの内容が大幅に拡張され、go testの動作、_test.goファイルの役割、一時ディレクトリでのビルド、そして新しいヘルプメッセージ（go help testflag, go help testfunc）への参照が含まれるようになりました。これにより、go help testの出力が非常に情報豊富になりました。

  2. helpTestflagの追加:

    • Command構造体として新しく定義され、go testコマンド自身が処理するフラグ（-c, -file, -x）と、生成されるテストバイナリが処理するフラグ（-test.v, -test.run, -test.bench, -test.cpuprofile, -test.memprofile, -test.memprofilerate, -test.parallel, -test.short, -test.timeout, -test.benchtime, -test.cpu）について詳細な説明が記述されています。
    • 特に、-test.memprofilerateや-test.parallelのような高度なフラグについても、その目的と使用方法が具体的に説明されています。
    • go testに渡された-test.X形式のフラグが、内部でテストバイナリに適切に渡されるメカニズムについても言及されています。

  3. helpTestfuncの追加:

    • Command構造体として新しく定義され、Go言語のテスト、ベンチマーク、例関数の命名規則、シグネチャ、およびそれぞれの目的について詳細に説明されています。
    • *testing.Tと*testing.Bの役割、例関数の出力検証メカニズム、godocでの表示方法などが含まれています。
    • 具体的な例関数（ExamplePrintln）のコードスニペットも提供されており、ユーザーがテスト関数の書き方を理解するのに役立ちます。

コアとなるコードの解説

このコミットのコアとなる変更は、goコマンドのヘルプシステムに、go testに関する詳細なドキュメントを組み込んだ点にあります。

  • src/cmd/go/main.goの変更:

    • commandsスライスにhelpTestflagとhelpTestfuncを追加することで、これらの新しいヘルプメッセージがgo helpコマンドのサブコマンドとして認識されるようになります。これは、GoのCLIツールが新しいヘルプドキュメントを公開するための標準的な方法です。

  • src/cmd/go/test.goの変更:

    • cmdTestのLongフィールドの拡張は、go help testを実行した際に表示される情報量を劇的に増やします。これにより、ユーザーはgo testの基本的な機能と、より詳細なヘルプメッセージへの参照を一度に得ることができます。
    • helpTestflagとhelpTestfuncという新しいCommand構造体の導入は、gotestのドキュメントをモジュール化し、go testのヘルプシステムに直接組み込むための鍵となります。それぞれのLongフィールドには、テストフラグとテスト関数の詳細な説明がMarkdown形式で記述されており、これはgodocのドキュメントから移植されたものです。
    • 特に、helpTestflagでは、go testコマンド自身が処理するフラグと、生成されるテストバイナリに渡されるフラグを明確に区別しています。これは、ユーザーがコマンドライン引数をどのように解釈されるかを理解する上で非常に重要です。例えば、-cや-xはgo testが直接処理しますが、-test.vや-test.runはテストバイナリに渡されます。また、利便性のために、-test.X形式のフラグがgo test自体でも-Xとして利用できることが説明されており、これはユーザーエクスペリエンスを向上させるための重要な機能です。
    • helpTestfuncでは、Goのテスト、ベンチマーク、例関数の厳密な命名規則とシグネチャが強調されています。これは、Goのテストフレームワークがこれらの規則に依存して関数を自動的に発見し実行するため、開発者にとって不可欠な情報です。

これらの変更により、go testは単なるテスト実行コマンドではなく、Go言語のテストに関する包括的な情報源としての役割も果たすようになりました。

関連リンク

参考にした情報源リンク

  • コミットメッセージと差分情報 (./commit_data/10821.txt)
  • Go言語の公式ドキュメント (現在のgo testおよびtestingパッケージのドキュメントを参照し、当時の文脈を補完)
  • Go言語のテストに関する一般的な知識
  • godocコマンドの機能に関する一般的な知識
  • go helpコマンドの動作に関する一般的な知識
  • Go言語のツールチェインの進化に関する一般的な知識