どうも。
WebAPIのテストを、PHPUnitやCodeceptionとか使わないでしたいって要望が周辺からあがったんでライブラリを作りました。
https://github.com/cloudpack/Rorschach
https://packagist.org/packages/cloudpack/rorschach
Rorschach (ロールシャッハ)
ライブラリの名前です。この名前超気に入ってます。
- 絶対に妥協しないアメコミヒーローのロールシャッハ
- シミ？をみる有名な性格診断テスト
の意味合いが決め手となり、社内でのコンペを勝ち上がった名前です。かっこいい。
Guzzleとsymfony/consoleベースです。
使い方
READMEよんでって言いたいんですけど怒られそうなんで書きます。
インストール
# composerをインストール
curl -S https://getcomposer.org/installer | php
# Rorshachをインストール
php composer.phar require --dev cloudpack/rorschach
例によって、 vendor 以下にライブラリがインストールされます。
実行
composer exec rorschach inspect
構文
base: https://(( env )).example.com
headers:
x-api-key: YOUR-SECRET-KEY
ContentType: application/json
allow_redirects:
max: 5
strict: false
referer: false
protocols:
- http
- https
track_redirects: false
pre-requests:
-
resource: /auth
method: GET
headers:
x-header: HEADER
body:
name: shinichi
password: p@ssw0rd
bind:
api-token: response.data.param
resources:
-
url: /users
method: GET
headers:
api-token: (( api-token ))
body:
exclude: false
expect:
code: 200
has:
- id
- user.name
- user.address..tel01
assert:
id: integer|nullable
name: string
-
url: /items
method: GET
expect:
code: 302
redirect: https://prod.example.com
base句
- base: テスト対象のAPIのURLを指定 (必須)
header句
- headers: 全てのリクエストに付与するHTTP headerを指定
allow_redirects句
- リダイレクトに関する設定を行う。
- Guzzleのドキュメント を参照ください。
pre-requests句
- resource: テストをしたいリソースを指定
- method: methodを指定 (GET, POST, PUT, DELETE, PATCH ...)
- body: テスト時に送るbody部を記載
- bind: レスポンスから変数に代入したい値と、変数名を記載（後述）
resources句
- resources: テストするリクエストを定義 (必須)
- resources.url: テストをしたいリソースを指定
- resources.method: methodを指定 (GET, POST, PUT, DELETE, PATCH ...)
- resources.body: テスト時に送るbody部を記載
- resources.expect: レスポンスから期待する型、status codeなどを記載
- code: レスポンスのstatus codeが同値であるかを判定
- has: 列挙したキー名が存在するかを判定
探査可能 - assert: 列挙したキー名に該当する値の型が妥当かを判定（integer, string, nullable, array)
探査可能 - redirect: リダイレクト先が正しいか判定（allow_redirects句の設定が必要）
探査可能とは？
探査可能なオプションでは、（ resources.expect.has や resources.expect.assert ）は、以下のようにオブジェクトや配列を柔軟に探査することができます。
a.b の場合
{
"a": {
"b": "object:aの中の、key:bを探査"
}
}
a..b の場合
{
"a": [
{
"b": "object:aの中の、配列の最初の要素の中の、key:bを探査"
}
]
}
オプション
--file
プロジェクトのルート・ディレクトリにある test*.yml を勝手に取りに行ってパースしてテスト流し始めます。
特定ファイルだけのテストをしたい場合は、 --file オプションを指定してください。
./vendor/cloudpack/rorschach/console inspect --file='test-orenotest.yml
--bind -b
(( )) ブラケットを記載することで、変数を外部から設定できます。
コマンドライン引数として設定するコマンドインジェクション方式と、pre-requestsのresponseから設定するプリリクエスト方式の２つの方法で設定が可能です。
コマンドインジェクション方式
例えば、
https://abc.example.com
https://xyz.example.com
のようにAPIのサブドメインを変えてテストしたい場合は、
https://(( env )).example.com
と、 (( )) ブラケットで囲い、コマンドライン引数から設定することで柔軟に対応が可能です。
base: https://(( env )).example.com
...
./vendor/cloudpack/rorschach/console inspect --bind='{"env": "abc"}'
プリリクエスト方式
pre-requests句を使うことで、続くリクエストに認証が必要な場合に、レスポンスから変数に値を代入できます。
pre-requests句は、基本文法の resources とほぼ書き方は一緒で、 bind 句が追加されます。
/auth に対して認証を行い、responseからapi-tokenを取得する場合は以下のようにします。
pre-requests:
-
resource: /auth
method: GET
body:
name: shinichi
password: p@ssw0rd
bind:
api-token: response.data.param
bind構文では、responseを探査する仕組みを実装しています。
response.data.param とした場合、 (( api-token )) 変数に以下の API-TOKEN が代入されます。
{
"response": {
"data": {
"param": "API-TOKEN"
}
}
}
最後に
まだ実践導入してないので、どなたかご利用頂いた上でご意見いただけると超うれしいです！
ダメ出しプルリク大歓迎！文句も受け付けます。リファクタも随時すすめていきます。