runnをインストールして使う方法は大きく分けて2つあります。

1. CLIツールとしてインストールして使う
2. Goのテストヘルパーとしてテストコードに組み込んで使う

この2つはどちらもrunnのファーストプライオリティとして開発しています。

例えば、APIのシナリオテスト基盤をrunnで構築するとき、CLIツールとして使う場合はAPIサーバの実装言語によらないポータビリティの高いシナリオテスト基盤を構築できます。

もしAPIサーバをGoで開発しているのであれば、テストヘルパーとして組み込むことで、さらに柔軟に、しかも go test でシナリオテストを実行できます。

CLIツールとしてインストールして使う

リリースバイナリをダウンロードする

サポートしているOS/Archであれば https://github.com/k1LoW/runn/releases からダウンロードして使うことができます。

Homebrewでインストールする

macOSであれはHomebrewでインストールできます。

$ go install github.com/k1LoW/runn/cmd/runn@latest

Dockerイメージを使う

Dockerイメージも提供しています。

https://github.com/k1LoW/runn/pkgs/container/runn

次のように実行が可能です。

$ docker container run -it --rm --name runn -v $PWD:/books ghcr.io/k1low/runn:latest run /books/*.yml

実行時には、ランブック（runnのYAML形式のシナリオファイルを「ランブック」または「ランブックファイル」と呼びます）やランブックがあるディレクトリをマウントしてください。

Notice
docker container run で、ホストOS側のlocalhostで起動しているHTTPサーバやDBサーバにrunnを実行する場合は、接続先の指定には工夫が必要です（runnからみた localhost 127.0.0.1 はコンテナ内を指すことになるため）。

Goのテストヘルパーとしてテストコードに組み込んで使う

REST APIサーバのAPIコールを中心としたシナリオテストにrunnをテストヘルパーとして組み込んで使うことができます。

次のテストコードは net/http/httptest パッケージで立てたテストサーバに対してrunnで複数のシナリオを実行する例です。

package xxxx

import (
	"context"
	"net/http/httptest"
	"testing"

	"github.com/k1LoW/runn"
)

func TestRouter(t *testing.T) {
	ctx := context.Background()
	ts := httptest.NewServer(NewRouter())
	t.Cleanup(func() {
		ts.Close()
	})
	opts := []runn.Option{
		runn.T(t),
		runn.Runner("req", ts.URL),
	}
	o, err := runn.Load("testdata/books/**/*.yml", opts...)
	if err != nil {
		t.Fatal(err)
	}
	if err := o.RunN(ctx); err != nil {
		t.Fatal(err)
	}
}

このように他のパッケージと同様にrunnをライブラリとして組み込むことができるようになっています。