Goのexample関数を使ってドキュメントの管理とテストを同時に行う

example関数について

Goには、testringパッケージにexample関数が用意されており、test実行時にexample通りに動作しているか確認することが可能です。
また、Godocにも関数のexampleが追加されるため、コードベースでドキュメント管理することが可能です。

Goでは_test.goで終わるファイルがテストファイルとして認識されます。テストファイルにExampleで始まる関数名を記述するとgodocにexampleが追加され、exampleの結果が正しく動作しているかテストされるようになります。

// display_test.go
package main

import (
    "testing"
)

// Openは　文字列のバイト数分　- が出力される
func ExampleDisplay_Open() {
    d := Display{"yokohama"}
    d.Open()
    // Output: +--------+
}

// display.go
package main

import (
    "fmt"
)

type Display struct {
    str   string
}

func (d Display) Open(str string) {
    fmt.Print("+")
    for i := 0; i < len(d.str); i++ {
        fmt.Print("-")
    }
    fmt.Println("+")
}

example関数名について

ただし、Exampleを記述する際に規則がありtest関数名のように自由な名前をつけられないため注意する必要があります。下記の通り、Exampleで関数名を初め、そのあとに「関数名」もしくは「型名」、「型名_関数名」を指定することが可能です。

func Example() { ... }
func ExampleF() { ... }
func ExampleT() { ... }
func ExampleT_M() { ... }

example実行結果

$ go test -v
=== RUN   ExampleDisplay_Open
--- PASS: ExampleDisplay_Open (0.00s)
PASS
ok      work/example    0.006s

godocにもexampleのコードが反映されます。exampleの内容が正しいかテストも実行されるため、ドキュメントの管理とテストを管理を同時に行うことが可能です。

参考URL

https://blog.golang.org/examples
https://golang.org/pkg/testing/