Kong Gatewayのカスタムプラグインを作る際はPongoというテストツールを使うのが推奨されている。
このツールのコマンドとして、pongo initという初期ファイル生成コマンドがあるが、具体的にどのようなファイルを作ってくれるのか確認する。
なお、Pongo自体の使い方について興味がある方は@jirokichi2017さんが書かれた以下の記事が参考になると思う。
実行の前提
前提として./kong/plugins/<plugin_name>というディレクトリがある必要がある。
ないと以下のエラーになる。
[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>'
ということで、実行前に以下のような感じでディレクトリを作っておく。
PLUGIN_NAME=myplugin
mkdir -p ./kong/plugins/${PLUGIN_NAME}
ファイルの生成
pongo initを実行する。
pongo init
実行すると以下の出力ようにファイルが追加されたことが確認できる。
[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'
なお、再度実行すると分かるが、既にファイルがある場合は以下のような感じのメッセージが既存のファイルを残して何もしない。
[pongo-INFO] '.busted' config file already present
生成されたファイルの確認
生成後のディレクトリでtreeコマンドを実施した結果は以下となる。
$ tree -a
.
├── .busted
├── .editorconfig
├── .gitignore
├── .luacheckrc
├── .luacov
├── .pongo
│ └── pongorc
└── kong
└── plugins
└── myplugin
作成されたものとそれぞれの意味は以下。
| ファイル | 概要 | 利用するコマンド |
|---|---|---|
.busted |
LuaのテストフレームワークBustedの設定ファイル。 | pongo run |
.editorconfig |
エディタのコードスタイルを統一するための設定ファイル（参考：EditorConfig)。 | 各種エディタ |
.gitignore |
Gitで無視するファイルやフォルダを指定するための設定ファイル。 | git add |
.luacheckrc |
Luaの静的解析ツールLuacheckの設定ファイル。 | pongo lint |
.luacov |
LuaのカバレッジツールLuaCovの設定ファイル。 | pongo run |
.pongo/pongorc |
Pongoの設定ファイル。主に依存するサービスを記載するのに利用。 | pongo up |
pongo initは空ファイルを作るのではなくデフォルトの推奨値が入った状態で設定ファイルを作成してくれる。
どのような値が設定されているかを見ていく。
.busted
.bustedはLuaのテストフレームワークBustedの設定ファイルで、中身は以下のようになっている。
return {
default = {
verbose = true,
coverage = true,
output = "gtest",
},
}
設定しているオプションは以下となる。
-
verbose: エラーの詳細出力を表示（デフォルトはoff） -
coverage: LuaCovを使ったカバレッジテストの実施有無（デフォルトはoff） -
output: 結果の出力フォーマットを指定（デフォルトはutfTerminal）
outputについてはここにあるハンドラから選択することが出来る。jsonなど選べるので、出力形式が気になる人は色々試してみると良いと思う。
.editorconfig
.editorconfigはエディタのコードスタイルを統一するための設定ファイルで、中身は以下のようになっている。
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で無視するファイルやフォルダを指定するための設定ファイルで、中身は以下のようになっている。
(コメントは削除した。)
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の設定ファイルで、中身は以下のようになっている。
（空行は削除した）
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のコマンドラインオプションをコンフィグにしたもので、意味は以下になる。
| 対象 | 意味 |
|---|---|
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 |
警告コードや変数名にマッチしたもの(正規表現も利用可)を無視する。ここでは6.に一致する警告コードを無視している。 |
files["spec/**/*.lua"] |
filesに記載したものは別ルールを適用することが出来る。specディレクトリ配下にはテストコードを置くため、ngx_lua+bustedを記載してBustedのコードに対してもLuaCheckが効くようにしている。 |
.luacov
.luacovはLuaのカバレッジツールLuaCovの設定ファイルで、中身は以下のようになっている。
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の中身は以下のようになっている。
--postgres
デフォルトでPostgresを起動するようにしている。
まとめ
pongo initを使うとPongoを使ったテストで使用する主要な設定ファイルを自動生成してくれることが確認できた。
生成物としては以下。
- Luaのテストフレームワークの設定ファイル
- エディタのコードスタイルを統一するための設定ファイル
- Gitで無視するファイルやフォルダを指定するための設定ファイル
- Luaの静的解析ツールの設定ファイル
- Luaのカバレッジツールの設定ファイル
- Pongoの設定ファイル
この結果からPongoがどのようなテストを実施しているかが確認できた。
また設定内容からどのような設定がされ出来そうかも確認できた。
実際に開発する際はプロジェクトのルールなどに則って設定変更していくと良さそうだ。