golang-testing

Go のプロジェクトで、テストを書く・直す・見直すときに効きます。samber が公開する、Go 専用のスキル集の 1 本です。

本文は「網羅率の数字を上げるためではなく、振る舞いを縛るためにテストを書く」という立場を最初に置いています。*.go のファイルを扱うときに読み込まれる設定です。

進め方（書く・見る・点検・原因を追う）

4 つ

冒頭の決まりの一覧

13 項目

go test の早見表

14 行

同梱ファイル（2026-10-23 時点）

8 件

4 つの進め方を使い分ける

本文は、頼まれた作業の種類で進め方を変えるよう決めています。

• 新しく書く対象のコードを順に見ていき、gotests で表の形のテストのひな形を作ってから、端の値と失敗の経路を足す
• 差分を見るプルリクエストの差分に絞り、新しい振る舞いが試されているか、確かめ方の質、表の形、不安定になる書き方が無いかを見る
• 全体を点検する大きなテスト一式を、最大 3 つの下位のエージェントに分けて並行で調べ、1 つの報告にまとめる
• 落ちる原因を追う確実に再現させ、失敗した確かめを切り出し、本番のコードか準備のどちらに原因があるかを追う

点検で分ける 3 つの観点は、単体テストの質と抜け、結合テストの分離とビルドタグ、goroutine の漏れと競合です。

冒頭の決まり 13 項目の主なもの

表で並べるテストには必ず名前を付けて t.Run に渡す、結合テストは //go:build integration で分ける、実行の順番に頼らない、などが並びます。

内部の実装ではなく、外から見える振る舞いと公開の約束を確かめる、という項目もあります。実装に縛られたテストは、作り替えのたびに書き直しになるのに、約束については何も示さない、という理由が添えられています。

ファイルの名前と並び順

テストのファイルは、試す関数の名前ではなく元のファイルの名前に合わせます（foo.go なら foo_test.go）。go test や網羅率の報告、エディタの移動が、ファイル単位で対応を取るからです。

ファイルの中のテスト関数も、元のファイルの関数と同じ順に並べます。とても大きなファイルだけは関心ごとに分けてよいが、名前は元のファイルから付ける、と決めています。

Go の新しい版の機能も扱う

goroutine と時間を含むテストには、Go 1.25 以降の testing/synctest を勧めています。全部の goroutine が止まったときだけ時間が進むので、順番が毎回同じになります。

Go 1.26 以降の ArtifactDir() でテストの成果物を残す方法や、ベンチマークで b.N ではなく b.Loop()（Go 1.24 以降）を使う決まりも載っています。本文は Go 1.27 以降の synctest.Sleep と httptest.NewTestServer()、go test が stdversion の検査を自動で流すことにも触れています。

testify の API の細部を知りたいとき

本文は、testify の assert・require・mock・suite の詳しい使い方は、同じ公開元の別のスキル（golang-stretchr-testify）を見るよう案内しています。測り方の作法（benchstat や性能の回帰の検出）も、別の golang-benchmark の範囲です。

CI の組み立てや静的検査の設定をしたいとき

CI でのテストの設定、thelper・paralleltest・testifylint などの検査の設定も、同じ公開元の別のスキルに回されています。このスキル 1 本では、テストを書く・見る部分だけを受け持ちます。

会社の決まりがすでにあるとき

本文は、自分を「共同体の既定」と位置づけ、明示的に置き換える会社のスキルがあればそちらを優先する、と書いています。社内の書き方の決まりがあるなら、そちらを先に入れてください。

テストを先に書く進め方そのものを身につけたいとき

テストを先に書いてから実装する手順を体に入れたいなら、言語を問わない test-driven-development や tdd のほうが向きます。このスキルは Go のテストの書き方の作法に寄っています。

書かれているコマンドと道具

frontmatter の allowed-tools には、Bash(go:*)・Bash(golangci-lint:*)・Bash(git:*)・Bash(gotests:*) と、ファイルの読み書き、下位のエージェント（Agent）、利用者への質問が並びます。allowed-tools は道具を絞る設定ではなく、呼ばれた回に確認なしで使ってよい道具を宣言するものです。ほかの道具も使えます。

前提として go と gotests の実行ファイルが要り、go install で gotests を取ってくる手順が書かれています。

結合テストの例は、データを消して入れ直す

例の接続先は localhost:5433 の試験用の Postgres です。本文の短い例は DATABASE_URL の環境変数から接続先を読むので、その値が本番を指していないかも見てください。

下位のエージェントを並べると費用が増える

全体を点検するときは、最大 3 つの下位のエージェントを並行で動かす決まりです。本文は、Claude Code では ultrathink で深く考えさせ、ultracode で複数のエージェントの進め方を明示的に選ぶよう書いています。大きなテスト一式ほど、使う量が増えることを見込んでください。

testify の確かめを親のテストで作らない

本文がわざわざ節を立てている落とし穴です。親のテスト関数で assert.New(t) を作って、t.Run の中で使い回すと、失敗が親に付き、落ちた場合分けの行は PASS のまま出ます。

並列にしてもしなくても起きるので、場合分けの中でそれぞれ作る、と決めています。わざと壊した場合分けで確かめる手順も載っています。

網羅率は目標ではない

網羅率は「試されていない経路を見つける道具」で、確かめの質は測らない、という立場です。関数を呼ぶだけで結果を見ないテストでも 100% になる、と同梱の資料は注意しています。

既定では網羅率はパッケージごとに数えられ、結合テストはビルドタグを渡さないと数に入りません。生成されたコードは数字を押し上げるので、しきい値を決める前に外すよう書かれています。

gotests は必ず入れる必要がありますか

本文は前提として go と gotests を挙げ、新しく書くときは gotests で表の形のひな形を作ってから肉付けする手順です。入っていなければ go install github.com/cweill/gotests/gotests@latest で入れるよう書かれています。差分を見る・原因を追う作業では、ひな形を作る場面はありません。

goroutine の漏れはどう調べますか

go.uber.org/goleak を使い、TestMain で goleak.VerifyTestMain(m) を呼ぶのが基本の形です。既知の漏れや外部のライブラリの goroutine は goleak.IgnoreCurrent() で除き、テスト 1 本だけなら defer goleak.VerifyNone(t) と書きます。goroutine を使うパッケージでは入れるべき、と決まりの一覧にあります。

時間に頼るテストが不安定です

本文は、time.Sleep や time.After を使う並行のコードには testing/synctest を勧めています。Go 1.25 以降は synctest.Test を使い、Go 1.24 の試験的な synctest.Run は使わない決まりです。時間を差し替える別の手として、同梱の資料は clockwork の偽の時計で時間を進める例も載せています。

単体テストと結合テストはどう分けますか

結合テストのファイルの先頭に //go:build integration を置き、go test -tags=integration ./... で別に流します。単体テストは外部に頼らず、1 本 1 ミリ秒未満に保つ、と本文は決めています。CI では競合の検出（-race）を付けて流すことも決まりの 1 つです。