pongo initが生成するファイルを確認する

Kong Gatewayのカスタムプラグインを作る際は[Pongo](https://github.com/Kong/kong-pongo)というテストツールを使うのが推奨されている。
このツールのコマンドとして、`pongo init`という初期ファイル生成コマンドがあるが、具体的にどのようなファイルを作ってくれるのか確認する。

なお、Pongo自体の使い方について興味がある方は@jirokichi2017さんが書かれた以下の記事が参考になると思う。
- [Kong Gatewayカスタムプラグインをテストする　～Part1: Pongoを実行する～](https://qiita.com/jirokichi2017/items/b6e272ac5fcba113e405)
- [Kong Gatewayカスタムプラグインをテストする　～Part2: Pongoでテストする～](https://qiita.com/jirokichi2017/items/35ccee0e09ce80365920)

## 実行の前提

前提として`./kong/plugins/<plugin_name>`というディレクトリがある必要がある。
ないと以下のエラーになる。
```sh
[pongo-INFO] no plugin-code folders found, e.g. './kong/plugins/<plugin_name>'
[pongo-INFO] current working dir has no plugin name, e.g. 'kong-plugin-<plugin_name>'
```
ということで、実行前に以下のような感じでディレクトリを作っておく。
```sh
PLUGIN_NAME=myplugin
mkdir -p ./kong/plugins/${PLUGIN_NAME}
```

## ファイルの生成
`pongo init`を実行する。
```sh
pongo init
```
実行すると以下の出力ようにファイルが追加されたことが確認できる。
```sh
[pongo-INFO] found plugin directory: ./kong/plugins/myplugin
[pongo-INFO] added '.busted' config file for the Busted test framework
[pongo-INFO] added '.luacov' config file for the LuaCov test coverage tool
[pongo-INFO] added '.editorconfig' config file with editor defaults and style items
[pongo-INFO] added '.luacheckrc' config file for the LuaCheck linter
[pongo-INFO] added '.pongo/pongorc' config file for Pongo test dependencies
[pongo-INFO] added 'servroot' to '.gitignore'
[pongo-INFO] added '*.rock' to '.gitignore'
[pongo-INFO] added '.pongo/.bash_history' to '.gitignore'
[pongo-INFO] added 'luacov.stats.out' to '.gitignore'
[pongo-INFO] added 'luacov.report.out' to '.gitignore'
[pongo-INFO] added 'luacov.report.html' to '.gitignore'
[pongo-INFO] added '.containerid' to '.gitignore'
```
なお、再度実行すると分かるが、既にファイルがある場合は以下のような感じのメッセージが既存のファイルを残して何もしない。
```sh
[pongo-INFO] '.busted' config file already present
```
## 生成されたファイルの確認

生成後のディレクトリでtreeコマンドを実施した結果は以下となる。
```
$ tree -a
.
├── .busted
├── .editorconfig
├── .gitignore
├── .luacheckrc
├── .luacov
├── .pongo
│   └── pongorc
└── kong
    └── plugins
        └── myplugin
```
作成されたものとそれぞれの意味は以下。

|ファイル|概要|利用するコマンド|
|---|---|---|
|`.busted`|Luaのテストフレームワーク[Busted](https://lunarmodules.github.io/busted/)の設定ファイル。|`pongo run`|
|`.editorconfig`|エディタのコードスタイルを統一するための設定ファイル（参考：[EditorConfig](https://editorconfig.org/))。|各種エディタ|
|`.gitignore`|Gitで無視するファイルやフォルダを指定するための設定ファイル。|`git add`|
|`.luacheckrc`|Luaの静的解析ツール[Luacheck](https://luacheck.readthedocs.io/en/stable/index.html)の設定ファイル。|`pongo lint`|
|`.luacov`|Luaのカバレッジツール[LuaCov](https://lunarmodules.github.io/luacov/)の設定ファイル。|`pongo run`|
|`.pongo/pongorc`|Pongoの設定ファイル。主に依存するサービスを記載するのに利用。|`pongo up`|

`pongo init`は空ファイルを作るのではなくデフォルトの推奨値が入った状態で設定ファイルを作成してくれる。
どのような値が設定されているかを見ていく。

### `.busted`
`.busted`はLuaのテストフレームワーク[Busted](https://lunarmodules.github.io/busted/)の設定ファイルで、中身は以下のようになっている。
```sh
return {
  default = {
    verbose = true,
    coverage = true,
    output = "gtest",
  },
}
```
設定しているオプションは以下となる。
- `verbose`: エラーの詳細出力を表示（デフォルトはoff）
- `coverage`: LuaCovを使ったカバレッジテストの実施有無（デフォルトはoff）
- `output`: 結果の出力フォーマットを指定（デフォルトは`utfTerminal`）

`output`については[ここ](https://github.com/lunarmodules/busted/tree/master/busted/outputHandlers)にあるハンドラから選択することが出来る。jsonなど選べるので、出力形式が気になる人は色々試してみると良いと思う。


### `.editorconfig`
`.editorconfig`はエディタのコードスタイルを統一するための設定ファイルで、中身は以下のようになっている。
```sh
root                     = true

[*]
end_of_line              = lf
insert_final_newline     = true
trim_trailing_whitespace = true
charset                  = utf-8

[*.lua]
indent_style             = space
indent_size              = 2

[kong/templates/nginx*]
indent_style             = space
indent_size              = 4

[*.template]
indent_style             = space
indent_size              = 4

[Makefile]
indent_style             = tab
```
nginxのテンプレートを利用する箇所についてはインデントが4になっているが、それ以外は2となる。


### `.gitignore`
`.gitignore`はGitで無視するファイルやフォルダを指定するための設定ファイルで、中身は以下のようになっている。
(コメントは削除した。)
```sh
servroot
*.rock
.pongo/.bash_history
luacov.stats.out
luacov.report.out
luacov.report.html
.containerid
```
削除しているものの意味は以下になる。
|対象|意味|
|---|---|
|servroot|`pongo run`時に一時的に作成するディレクトリ|
|*.rock|LuaRocks形式のパッケージファイル|
|.pongo/.bash_history|Pongoのシェル内で実行したBashの入力履歴|
|luacov.stats.out|LuaCov利用時の統計ファイル|
|luacov.report.out|LuaCov利用時のレポートファイル|
|luacov.report.html|LuaCov利用時のレポートファイル(HTML形式)|
|.containerid|PongoがコンテナIDを残すために利用するファイル|


### `.luacheckrc`
`.luacheckrc`はLuaの静的解析ツール[Luacheck](https://luacheck.readthedocs.io/en/stable/index.html)の設定ファイルで、中身は以下のようになっている。
（空行は削除した）
```lua
std             = "ngx_lua"
unused_args     = false
redefined       = false
max_line_length = false
include_files = {
  "**/*.lua",
  "*.rockspec",
  ".busted",
  ".luacheckrc",
}
globals = {
    "_KONG",
    "kong",
    "ngx.IS_CLI",
}
not_globals = {
    "string.len",
    "table.getn",
}
ignore = {
    "6.", -- ignore whitespace warnings
}
files["spec/**/*.lua"] = {
    std = "ngx_lua+busted",
}
```

設定は基本的に[LuaCheckのコマンドラインオプション](https://luacheck.readthedocs.io/en/stable/cli.html?highlight=ngx_lua#command-line-options)をコンフィグにしたもので、意味は以下になる。
|対象|意味|
|---|---|
|`std`|許容する標準ライブラリなどの指定。`ngx_lua`によりOpenRestyの`lua-nginx-module`をサポート|
|`unused_args`|未使用の関数の引数チェックをするかどうか。`false`にすることで無効化している。|
|`redefined`|変数の再定義を許可するかどうか。`false`にすることで再定義しても警告を出さない。|
|`max_line_length`|1行が長過ぎると(defaultで120文字)警告を出すが、`false`にすることで無効化している。|
|`include_files`|解析対象のファイル。全てのluaファイル、rockspecファイル、`.busted`ファイル、`.luacheckrc`ファイルを指定。|
|`globals`|ここに定義したものはグローバル変数として扱われ未定義のエラーが出ない。|
|`not_globals`|ここに定義したものはグローバル変数として扱われない。`string.len`や`table.getn`はLua5.3以降で非推奨のため警告を出す。|
|`ignore`|[警告コード](https://luacheck.readthedocs.io/en/stable/warnings.html#list-of-warnings)や変数名にマッチしたもの(正規表現も利用可)を無視する。ここでは`6.`に一致する警告コードを無視している。|
|`files["spec/**/*.lua"]` |`files`に記載したものは別ルールを適用することが出来る。specディレクトリ配下にはテストコードを置くため、`ngx_lua+busted`を記載してBustedのコードに対してもLuaCheckが効くようにしている。|

### `.luacov`
`.luacov`はLuaのカバレッジツール[LuaCov](https://lunarmodules.github.io/luacov/)の設定ファイルで、中身は以下のようになっている。
```lua
include = {
   "%/kong%-plugin%/kong%/.+$",
}

statsfile = "/kong-plugin/luacov.stats.out"

-- default reporter (text)
reportfile = "/kong-plugin/luacov.report.out"

-- html reporter
-- reportfile = "/kong-plugin/luacov.report.html"
-- reporter = "html"

runreport = true
```
設定内容は以下となる。
|対象|意味|
|---|---|
|`include`|カバレッジ計測の対象となるファイルパターンを指定。`%`はエスケープで正規表現で記載されており、`/kong-plugin/kong/` 以下の全てのファイルを対象としている。|
|`statsfile`|カバレッジ計測の生データを保存するファイルのパスを指定。このファイルには実行時の統計情報が記録される。|
|`reportfile`|カバレッジレポートの出力先ファイルを指定。デフォルトではテキスト形式で出力。（コメントアウトされている部分はHTML形式でのレポート出力の設定例。`reporter = "html"` を有効にするとHTML形式でレポートが生成される。）|
|`runreport`|`true`に設定すると、統計収集後に自動的にレポートを生成する。`false`の場合は、手動でレポート生成コマンドを実行する必要がある。|


### `.pongo/pongorc`
`.pongo/pongorc`の中身は以下のようになっている。
```sh
--postgres
```
デフォルトでPostgresを起動するようにしている。

## まとめ
`pongo init`を使うとPongoを使ったテストで使用する主要な設定ファイルを自動生成してくれることが確認できた。
生成物としては以下。
- Luaのテストフレームワークの設定ファイル
- エディタのコードスタイルを統一するための設定ファイル
- Gitで無視するファイルやフォルダを指定するための設定ファイル
- Luaの静的解析ツールの設定ファイル
- Luaのカバレッジツールの設定ファイル
- Pongoの設定ファイル

この結果からPongoがどのようなテストを実施しているかが確認できた。
また設定内容からどのような設定がされ出来そうかも確認できた。
実際に開発する際はプロジェクトのルールなどに則って設定変更していくと良さそうだ。