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

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

このコミットは、Go言語のtestingパッケージにおけるLogおよびLogf関数の出力挙動に関するドキュメントの改善と、それに伴うgo help testコマンドの出力、そしてドキュメント生成スクリプトの修正を目的としています。具体的には、これらの関数が通常はテストが失敗した場合、または-test.vフラグが設定された場合にのみ出力を生成するという重要な挙動を明確にしています。

コミット

commit 144dd2b21cd5ca0ff15a89ad5d8e9eba591b0c1e
Author: Rob Pike <r@golang.org>
Date:   Mon Apr 1 15:17:00 2013 -0700

    testing: document that Log and Logf do not usually produce output
    The text is printed only if the test fails or -test.v is set.
    Document this behavior in the testing package and 'go help test'.
    Also put a 'go install' into mkdoc.sh so I don't get tricked by the
    process of updating the documentation ever again.
    
    Fixes #5174.
    
    R=golang-dev, dsymonds
    CC=golang-dev
    https://golang.org/cl/8118047

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

https://github.com/golang/go/commit/144dd2b21cd5ca0ff15a89ad5d8e9eba591b0c1e

元コミット内容

testing: document that Log and Logf do not usually produce output The text is printed only if the test fails or -test.v is set. Document this behavior in the testing package and 'go help test'. Also put a 'go install' into mkdoc.sh so I don't get tricked by the process of updating the documentation ever again.

Fixes #5174.

変更の背景

Go言語のtestingパッケージには、テスト中にログメッセージを出力するためのLogおよびLogf関数が提供されています。しかし、これらの関数は、常に標準出力にメッセージを表示するわけではありません。デフォルトでは、テストが失敗した場合、またはgo testコマンドに-v（verbose）フラグが指定された場合にのみ、これらのログメッセージが出力されます。

この挙動は、テストの実行速度を向上させ、成功したテストの冗長な出力を避けるための設計上の選択です。しかし、この暗黙的な挙動は、特にGoのテストフレームワークに慣れていない開発者にとっては混乱の原因となる可能性がありました。開発者がLogやLogfを呼び出したにもかかわらず、期待する出力が得られない場合、デバッグが困難になることが考えられます。

このコミットは、このような混乱を解消し、LogおよびLogfの実際の出力条件を明確にドキュメント化することを目的としています。また、ドキュメントの更新プロセスを改善するために、mkdoc.shスクリプトにgo installコマンドを追加し、ドキュメントが確実に最新の状態になるようにしています。コミットメッセージにあるFixes #5174は、この挙動に関する既存の課題（おそらくGoの内部バグトラッカーでの報告）に対応するものです。

前提知識の解説

  • Go言語のtestingパッケージ: Go言語に組み込まれているテストフレームワークです。go testコマンドを通じてテストを実行します。
  • *testing.T: テスト関数に渡される構造体で、テストの状態管理、エラー報告、ログ出力などの機能を提供します。
  • LogおよびLogfメソッド: *testing.T構造体のメソッドで、テスト中に情報をログに記録するために使用されます。Logはfmt.Printlnのように引数をフォーマットし、Logfはfmt.Printfのようにフォーマット文字列と引数を受け取ります。
  • go test -vフラグ: go testコマンドに-vフラグを付けると、テストの実行が詳細モードになり、各テストの実行状況や、通常は表示されないLog/Logfからの出力も表示されるようになります。
  • go help test: goコマンドのヘルプ機能で、testサブコマンドに関する詳細な情報（利用可能なフラグなど）を表示します。
  • mkdoc.sh: Goプロジェクト内でドキュメントを生成または更新するためのシェルスクリプト。
  • go install: Goのコマンドで、パッケージをコンパイルして実行可能ファイルをGOPATH/binまたはGOBINにインストールします。この文脈では、ドキュメント生成に必要なツールやパッケージを最新の状態に保つために使用されます。

技術的詳細

このコミットの主要な技術的変更は、ドキュメントのテキスト修正と、ドキュメント生成スクリプトへの小さな追加です。

  1. src/cmd/go/doc.goおよびsrc/cmd/go/test.goの更新:

    • これらのファイルは、go help testコマンドの出力内容を定義しています。
    • -vフラグの説明が修正され、LogおよびLogfからのテキストがテストが成功した場合でも出力されることが明記されました。
    • 変更前: Verbose output: log all tests as they are run.
    • 変更後: Verbose output: log all tests as they are run. Also print all text from Log and Logf calls even if the test succeeds.
    • これにより、ユーザーは-vフラグの完全な効果を理解できるようになります。

  2. src/pkg/testing/testing.goの更新:

    • testingパッケージのLogおよびLogfメソッドのコメントが更新されました。
    • 変更前は、単に「エラーログにテキストを記録する」と記載されていました。
    • 変更後には、「テキストはテストが失敗した場合、または-test.vフラグが設定された場合にのみ出力されます」という重要な注意書きが追加されました。
    • これにより、これらの関数の挙動に関する公式ドキュメントが明確になります。

  3. src/cmd/go/mkdoc.shの更新:

    • ドキュメント生成スクリプトの冒頭にgo installコマンドが追加されました。
    • これは、ドキュメントを生成する前に、関連するGoツールやパッケージが最新の状態であることを保証するためのものです。これにより、古いバージョンのツールが原因でドキュメントが正しく更新されないという問題を回避できます。コミットメッセージにある「I don't get tricked by the process of updating the documentation ever again.」という記述は、この問題に直面した経験があることを示唆しています。

これらの変更は、コードの機能自体を変更するものではなく、主にユーザーがGoのテストフレームワークをより正確に理解し、効果的に使用できるようにするためのドキュメントの改善に焦点を当てています。

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

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

  1. src/cmd/go/doc.go: go helpコマンドのドキュメントの一部。-vフラグの説明が更新されました。

    --- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -763,7 +763,8 @@ control the execution of any test:
  	If a test runs longer than t, panic.

  -v
-	    Verbose output: log all tests as they are run.
+	    Verbose output: log all tests as they are run. Also print all
+	    text from Log and Logf calls even if the test succeeds.

 The test binary, called pkg.test where pkg is the name of the
 directory containing the package sources, can be invoked directly

  2. src/cmd/go/mkdoc.sh: ドキュメント生成用のシェルスクリプト。go installコマンドが追加されました。

    --- a/src/cmd/go/mkdoc.sh
+++ b/src/cmd/go/mkdoc.sh
@@ -3,6 +3,7 @@
 # Use of this source code is governed by a BSD-style
 # license that can be found in the LICENSE file.

+go install # So the next line will produce updated documentation.
 go help documentation > doc.go
 gofmt -w doc.go

  3. src/cmd/go/test.go: go testコマンドの内部実装に関連するファイル。ここでも-vフラグの説明が更新されました。

    --- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -153,7 +153,8 @@ control the execution of any test:
  	If a test runs longer than t, panic.

  -v
-	    Verbose output: log all tests as they are run.
+	    Verbose output: log all tests as they are run. Also print all
+	    text from Log and Logf calls even if the test succeeds.

 The test binary, called pkg.test where pkg is the name of the
 directory containing the package sources, can be invoked directly

  4. src/pkg/testing/testing.go: testingパッケージのコアファイル。LogおよびLogfメソッドのコメントが更新されました。

    --- a/src/pkg/testing/testing.go
+++ b/src/pkg/testing/testing.go
@@ -246,11 +246,13 @@ func (c *common) log(s string) {
 }

 // Log formats its arguments using default formatting, analogous to Println,
-// and records the text in the error log.
+// and records the text in the error log. The text will be printed only if
+// the test fails or the -test.v flag is set.
 func (c *common) Log(args ...interface{}) { c.log(fmt.Sprintln(args...)) }

 // Logf formats its arguments according to the format, analogous to Printf,
-// and records the text in the error log.
+// and records the text in the error log. The text will be printed only if
+// the test fails or the -test.v flag is set.
 func (c *common) Logf(format string, args ...interface{}) { c.log(fmt.Sprintf(format, args...)) }

 // Error is equivalent to Log followed by Fail.

コアとなるコードの解説

このコミットの「コア」は、Goのテストにおけるログ出力の挙動に関するドキュメントの正確性を向上させる点にあります。

  • src/pkg/testing/testing.goにおけるコメントの追加:

    • LogとLogfの関数シグネチャ自体は変更されていません。重要なのは、これらの関数の目的を説明するコメントブロックに、出力が「テストが失敗した場合、または-test.vフラグが設定された場合にのみ」行われるという条件が明示的に追加されたことです。
    • これは、開発者がこれらの関数を使用する際に、なぜログメッセージが表示されないのかという疑問を解消し、デバッグの効率を向上させるための非常に重要な情報です。

  • src/cmd/go/doc.goおよびsrc/cmd/go/test.goにおける-vフラグの説明の修正:

    • これらのファイルは、go help testコマンドを通じてユーザーに表示されるヘルプテキストを定義しています。
    • -vフラグが単に「すべてのテストをログに記録する」だけでなく、「テストが成功した場合でもLogおよびLogfからのすべてのテキストを出力する」という追加の機能を持つことを明確にすることで、ユーザーは-vフラグの真の価値を理解できます。これにより、テストのデバッグ時に-vフラグを適切に使用する動機付けとなります。

  • src/cmd/go/mkdoc.shへのgo installの追加:

    • これは直接的なコードの挙動変更ではありませんが、ドキュメントの正確性を維持するための重要なプロセス改善です。
    • go installを実行することで、ドキュメント生成に必要なツール（例えば、go helpコマンドの出力を生成する内部ツールなど）が常に最新の状態に保たれます。これにより、古いツールが原因でドキュメントが古くなったり、不正確になったりするリスクが低減されます。これは、Goプロジェクトのような大規模なコードベースにおいて、ドキュメントとコードの整合性を保つ上で不可欠なプラクティスです。

全体として、このコミットは、Goのテストフレームワークの使いやすさと理解度を向上させるための、小さくも重要な改善です。

関連リンク

参考にした情報源リンク

  • Go言語の公式ドキュメント
  • Go言語のソースコード（特にsrc/pkg/testing/testing.go、src/cmd/go/doc.go、src/cmd/go/test.go）
  • Gitのコミット履歴と差分表示
  • （Fixes #5174については、Goの公開されているGitHubリポジトリでは直接的な関連issueが見つかりませんでした。これは、Goの内部バグトラッカーのIDであるか、あるいは古い情報である可能性があります。）