RSpecのrequest specでComittteeを使ってレスポンスJSONを自動的にバリデーションする

この記事の続きのようなものです。

blog.kymmt.com

やりたいこと

Rails + RSpecでWeb APIのrequest specを書くときに、Committee(とCommitee::Rails)の assert_schema_conform を使って、レスポンスのJSONがOpenAPIドキュメントで定義したレスポンスのJSON Schemaと一致するかどうか自動でチェックできるようにします。つまり、次のようにrequest specを書いたら自動でJSONのバリデーションが走ります。

describe 'User', type: :request do
  describe 'GET /users/:id' do
    it 'returns 200 OK' do
      get "/users/:id" # GETリクエスト発行後にJSONのバリデーションを自動で実行
    end
  end
end

前提

前述した記事の内容を実施しているものとします。

使うソフトウェアのバージョンは次のとおりです。

  • Rails 5.1.4
  • Commitee 2.0.0
  • Commitee::Rails 0.2.0

結論

先に結論を書いておくと、次のことをやればできます。

  • ActionDispatch::Integration::Session#process を実行したあとにCommitteeの assert_schema_conform を実行する

やりかたは後述の「HTTPリクエスト発行後に assert_schema_conform を実行する」を見てください。

request spec内でのHTTPリクエスト発行メソッドの正体を調べる

request specで get, post などのHTTPリクエストメソッドを発行したときに assert_schema_conform を実行したいので、まずはこれらのHTTPリクエスト発行メソッドの正体を調べます。

結論としては、これらのメソッドの実体は、RailsのAction Dispatch(以下AD, AD とします)における AD::Integration::Session という結合テスト時のHTTP通信セッション管理用クラスが持つメソッド #process です。このメソッドは次のようにHTTPメソッド、パス、パラメータなどHTTPリクエストを発行するのに必要なデータを受け取って、実際にリクエストを発行します。

# see: https://github.com/rails/rails/blob/d79e102bfaefc0dce843a73a48456831bd7848b7/actionpack/lib/action_dispatch/testing/integration.rb#L204
def process(method, path, params: nil, headers: nil, env: nil, xhr: false, as: nil)
  # ...
end

AD::Integration::Session#process はモジュール AD::integration::RequestHelpers で定義されている get, post などのヘルパーメソッドから呼び出されています。get の例を引用します。

# see: https://github.com/rails/rails/blob/d79e102bfaefc0dce843a73a48456831bd7848b7/actionpack/lib/action_dispatch/testing/integration.rb#L17-L19
module ActionDispatch
  module Integration #:nodoc:
    module RequestHelpers
      # Performs a GET request with the given parameters. See ActionDispatch::Integration::Session#process
      # for more details.
      def get(path, **args)
        process(:get, path, **args)
      end
      # ...

モジュール AD::integration::RequestHelpers はクラス AD::Integration::Sessioninclude されています。

モジュール AD::Integration::Runner は結合テストを実行するために AD::Integration::Session を使ってHTTP通信のセッションを開きます。そして、get, post などのメソッド呼び出しを AD::Integration::Session へ委譲するメソッドを動的に定義しています。AD::Integration::SessionAD::Integration::RequestHelperinclude しているので、委譲されてきたメソッド呼び出しを処理することができます。

# see: https://github.com/rails/rails/blob/d79e102bfaefc0dce843a73a48456831bd7848b7/actionpack/lib/action_dispatch/testing/integration.rb#L343-L354
module ActionDispatch
  module Integration
    # ...
    module Runner
      %w(get post patch put head delete cookies assigns follow_redirect!).each do |method|
        define_method(method) do |*args|
          # reset the html_document variable, except for cookies/assigns calls
          unless method == "cookies" || method == "assigns"
            @html_document = nil
          end

          # 注:integraion_session が Session のインスタンス
          integration_session.__send__(method, *args).tap do
            copy_session_variables!
          end
        end
      end
    # ...

rspec-railsでは、モジュール RSpec::Rails::RequestExampleGroup でモジュール AD::Integration::Runnerinclude しています。また、rspec-railsはrequest specのときにモジュール RSpec::Rails::RequestExampleGroupinclude します。これにより、request specでは get, post などが使えるようになっています。

HTTPリクエスト発行後に assert_schema_conform を実行する

ここまで把握したら、あとは Session#process を実行したあとに assert_schema_conform を差し込めばよさそうです。他にいいやりかたがあるかもしれませんが、今回は次のようにしました。

# spec/support/assert_schema_conform_available.rb
# CommittteeRailsOpenapi2 は前回記事参照
module AssertSchemaConformAvailable
  include CommitteeRailsOpenapi2

  def process(*args)
    super *args
    assert_schema_conform
  end
end

class ActionDispatch::Integration::Session
  prepend AssertSchemaConformAvailable
end

まず、#process を定義したモジュール AssertSchemaConformAvailable を作り、継承チェーンの上位に process があるとして、そのメソッドを呼んだあとに assert_schema_conform を単純に差し込んでいます。そして、このモジュールを AD::Integration::Sessionprepend することで、このモジュールが継承チェーンにおいて AD::Integration::Session の下位に入り、request specから getpost を呼んだときに AssertSchemaConformAvailable#process を呼べるようにしています。

あとは spec/rails_helper.rb でこのファイルを require しておけば、普通にrequest specを書くだけで、OpenAPIドキュメントに基づいて自動でレスポンスJSONをバリデーションできるようになります。

その他

  • OpenAPIドキュメントに書いていないパスがあれば AssertSchemaConformAvailable#process の中で除外しておく
  • OpenAPIドキュメントをファイル分割して書いて必要なときに結合する運用のときは、request spec実行前後でドキュメントを自動作成/削除すると便利そう

参考

この記事での試みはこちらに影響されております。

Web APIのレスポンスJSONをCommittee + OpenAPIでバリデーションして仕様と実装の乖離を防ぐ

APIドキュメントに書いたJSON Schemaと実際に実装したWeb APIのレスポンスJSONが一致するかバリデーションするためのCommitteeというgemがあります。また、このCommitteeをRailsプロジェクト中のテストから使うためのCommittee::Railsというgemがあります。

CommitteeはAPIドキュメントの形式としてJSON Hyper SchemaOpenAPI 2.0に対応しています。また、APIエンドポイントを叩いたときのレスポンスJSONがドキュメントで定義したJSON Schemaと一致したかを確認するアサーションメソッド assert_schema_conform を持っているので、このメソッドを使ってAPIドキュメントの実際の動作の乖離を未然に防ぐことができます。

今回はOpenAPI 2.0の形式で書いたAPIドキュメントを使って、Railsで作ったAPIのエンドポイントからのレスポンスをRspecのテストでバリデーションしてみます。

使用するライブラリのバージョン

ライブラリのバージョンは次のものとします。

  • Commitee 2.0.0
  • Commitee::Rails 0.2.0

例のAPI仕様

今回、次のようなAPIエンドポイントを持つ単純なアプリケーションを考えます。

  • GET /users/{userId}

このエンドポイントはステータスコード200で userId のIDを持つユーザを返します。ここで、ユーザは次のような属性を持つデータとします。

属性名 必須
id
email
name
age

すなわち、レスポンスのJSONは次のような形となります。

{
  "id": 1,
  "email": "foo@example.com",
  "name": "John Doe",
  "age": 25
}

OpenAPIドキュメントの記述

上述した仕様に基づいて、次のようなOpenAPI 2.0形式のドキュメントを書きます。

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Committee Rails Sample",
    "license": {
      "name": "MIT"
    }
  },
  "host": "example.com",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/users/{userId}": {
      "get": {
        "summary": "get users",
        "operationId": "userShow",
        "tags": [
          "users"
        ],
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "description": "user ID",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "A user",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "User": {
      "required": [
        "id",
        "email",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer"
        },
        "email": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    }
  }
}

ここでは次の点に注目してもらえればOKです。

  • GET /usres/{userId} のレスポンスとして definitions 配下のデータ定義 User を使っている
  • データ定義 User では required で必須パラメータを指定しつつ、additionalPropertiesfalse を指定して記述したパラメータ以外が含まれることを禁じている

Committee::RailsでOpenAPIを使う準備

Committee::RailsでOpenAPIを使うために、Committee::Test::Methods#committee_schema というメソッドをオーバーライドします。このメソッドはAPIドキュメントに書いたJSON Schemaで実際のJSONをバリデーションするときに、そのAPIドキュメントを読み込むメソッドです。Commitee::Railsでは Commitee::Rails::Test::Methods#commitee_schema でJSON Hyper Schemaのドライバを使うようにあらかじめオーバーライドしていますが、今回はOpenAPI 2.0のドライバを使いたいので、自前でオーバーライドし直します。

# spec/support/committee_rails_openapi2.rb
module CommittteeRailsOpenapi2
  include Committee::Rails::Test::Methods

  def committee_schema
    @committee_schema ||=
      begin
        driver = Committee::Drivers::OpenAPI2.new
        schema_hash = JSON.parse(File.read(schema_path))
        driver.parse(schema_hash)
      end
  end

  def schema_path
    Rails.root.join('docs', 'swagger.json')
  end
end

ここでは、例としてRailsプロジェクトの docs/swagger.json に存在するOpenAPIドキュメントを読み込んでいます。

テストの記述

ここまで来ると、上述の commitee_schema オーバーライドによって、APIエンドポイントが返すレスポンスがOpenAPIドキュメントに記述したJSON Schemaに一致するかどうかをRailsのテストで確認できるようになりました。テストはCommittee::RailsのREADMEに書かれているものとまったく同じで、RSpecを使うと次のように書けます。

# spec/requests/users_spec.rb
require 'rails_helper'

RSpec.describe 'Users', type: :request do
  describe 'GET /users/:id' do
    let!(:user) { create(:user) }

    it 'レスポンスがAPI定義と一致する' do
      get "/users/#{user.id}"
      assert_schema_conform
    end
  end
end

もしレスポンス用テンプレートの記述を間違えて必須属性 email を含めなかった場合、次のようなエラーが出ます。

  1) Users GET /users/:id レスポンスがAPI定義と一致する
     Failure/Error: assert_schema_conform

     Committee::InvalidResponse:
       Invalid response.

       #: failed schema #/properties//users/{userId}/properties/GET: "email" wasn't supplied.

また、もしレスポンス用テンプレートの記述を間違えてOpenAPIドキュメントで定義していない属性 phone を含めた場合、次のようなエラーが出ます。

  1) Users GET /users/:id レスポンスがAPI定義と一致する
     Failure/Error: assert_schema_conform

     Committee::InvalidResponse:
       Invalid response.

       #: failed schema #/properties//users/{userId}/properties/GET: "phone" is not a permitted key.

さらに、 属性 age は必須としない定義にしているので、レスポンスに age を含めなくてもエラーにはなりません。

なお、注意点として、ライブラリの実装上、正常系(ステータスコード200〜300番台)のレスポンスだけテストでき、異常系(ステータスコード400〜500番台)についてはテストできません*1

まとめ

  • Railsで作るWeb APIのレスポンスJSONがOpenAPIに定義したJSON Schemaと一致しているかをチェックするにはCommitteeとCommittee::Railsを使う
  • OpenAPI 2.0の形式のドキュメントを読み込むように必要なメソッドをオーバーライドしておく必要がある

Yokohama.rb Monthly Meetup #84 に参加した

2017-09-09(土)のYokohama.rb Monthly Meetup #84参加のメモです。

yokohamarb.doorkeeper.jp

Rubyレシピブック

今回から最終章のひとつ手前、第10章の「Webプログラミング」に入りました。次のレシピを読みました。

  • 261: RSSを扱う
  • 262: Rackを使う
  • 263: フォームから入力された値を取り出す
  • 264: クエリ文字列を取り出す

標準添付ライブラリのひとつであるrssを触ったり、クライアントからのリクエストを受けてレスポンスを返すコードを標準添付ライブラリcgiと言わずと知れたRackそれぞれを使って書いたりしていました。

その他

仮想通貨(ビットコイン/モナコイン)で決済できるECモールをRails+AWSで開発/運用されている方から、サービスの紹介と開発について発表がありました。最近、周囲でビットコインを触っている人が増えたので、仮想通貨自体がだいぶ気になってきました。

また、るびま編集の@miyohideさんがいるということで、先日話題になった@kbaba1001さんのHanamiの記事をみんなで読んでいました。「まとめ」に書かれている内容が本当に大事。



来月10月のYokohama.rbはお休みです。

次回はおそらく11月第2週の土曜日になるかと(勝手に)思っています。レシピブックの最後のほうを読みたい人やRubyについて雑にお話ししたい人はぜひ。

OpenAPI v3.0.0のCallback Objectについて調べた

2017年7月末リリースのOpenAPI v3.0.0に入ったCallback Objectという仕様がパッと見だとどう使うかわかりにくかったので、調べてみました。

Callback Objectの仕様は次のリンク先のとおりです。

OpenAPI-Specification/3.0.0.md at master · OAI/OpenAPI-Specification

Callack Objectについて簡単に述べると、「OpenAPIドキュメントで記述しているエンドポイントに対してリクエストしたあと、こちらが指定したエンドポイントに対してリクエスト先がwebhookなどでコールバックするような場合についての仕様が記述できるもの」、です。

まだわかりにくいので、OpenAPI公式のリポジトリに置いてある次のサンプルを見てみます。

まず、このYAML中のキー post 配下を見てみると次のようになっています(抜粋)。

post:
  description: subscribes a client to receive out-of-band data
  parameters:
    - name: callbackUrl
      in: query
      required: true
      description: # ...
      schema:
        type: string
        format: uri
        example: https://tonys-server.com
  responses:
    '201':
      description: subscription successfully created
      content:
        application/json:
          schema:
            description: subscription information
            required:
              - subscriptionId
            properties:
              subscriptionId:
                description: this unique identifier allows management of the subscription
                type: string
                example: 2531329f-fb09-4ef7-887e-84e648214436

ここでは、

  • /streams というエンドポイントに対して callbackUrl というパラメータとともにPOSTリクエストを投げることができる
  • リクエストが成功すると subscription(購読)リソースが作成される

というエンドポイント仕様が記述されていることがわかります。

parameters, responses のさらに下の callbacks 配下にある記述が、今回着目するCallbacks Objectです(抜粋)。

callbacks:
  onData:
    '{$request.query.callbackUrl}/data':
      post:
        requestBody:
          description: subscription payload
          content:
            application/json:
              schema:
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  userData:
                    type: string
        responses:
          '202':
            description: # ...
          '204':
            description: # ...

これは、このAPIを提供している側(仕様書内ではAPI providerと呼ばれています)はクライアント側が指定した '{$request.query.callbackUrl}/data' というURLに対して requestBody の内容でPOSTリクエストするようになるという記述です。

ここで、$request.query.callbackUrl のようなデータの指定方法は仕様書の Key Expression の項に書いてあるURL, HtTPメソッド、HTTPリクエストのデータ、HTTPレスポンスの Location ヘッダが取得できる「実行時式」(runtime expression) です。

responses には返すべきステータスコードなどが記述できます。ここでいうエンドポイント '{$request.query.callbackUrl}/data' を持つホストは responses に書いた記述を満たすようにレスポンスを返す必要があります。

以上のようにして、Callback Objectを使うことで、あるエンドポイントに付随したAPI provider側からのコールバックについての仕様も記述できるようになります。

Rails 5.1でRails pluginをセットアップする手順

最近読んでいる “Crafting Rails 4 Applications” の中でRails pluginを開発する場面が多々あるので、手元でもRails 5を使ってRails pluginを書いてみています。

Rails 5だと、プラグインのセットアップ手順が本の記述やRails Guidesの記述と少し違っていたので書いておきます。

環境は次のとおりです。

  • Ruby 2.4.1
  • Rails 5.1.3
  • Bundler 1.14.6

プラグインの新規作成

$ rails plugin new my_plugin
      create
      create  README.md
      create  Rakefile
      create  my_plugin.gemspec
      create  MIT-LICENSE
      create  .gitignore
      create  Gemfile
      create  lib/my_plugin.rb
      create  lib/tasks/my_plugin_tasks.rake
      create  lib/my_plugin/version.rb
      create  bin/test
      create  test/test_helper.rb
      create  test/my_plugin_test.rb
      append  Rakefile
  vendor_app  test/dummy

gemのインストール

$ cd my_plugin
$ bundle
You have one or more invalid gemspecs that need to be fixed.
The gemspec at /Users/kymmt/my_plugin/my_plugin.gemspec is not valid. Please fix this gemspec.
The validation error was '"FIXME" or "TODO" is not a description'

Rails pluginはgemの一種なのでプロジェクト中に *.gemspec ファイルを持ちます。plugin作成時はこの gemspec 中の次の項目に TODO の文字列が入っていて、これだと gemspec がinvalidと判定され先に進めないので、消すなりなんなりします。

Gem::Specification.new do |s|
  # ...
  s.homepage    = "TODO" # TODOを消す
  s.summary     = "TODO: Summary of MyPlugin." # TODOを消す
  s.description = "TODO: Description of MyPlugin." # TODOを消す
  # ...
end

もう1回 bundle するとgemが入ります。

$ bundle
Fetching gem metadata from https://rubygems.org/..........
(snip)
Bundle complete! 2 Gemfile dependencies, 40 gems now installed.
Gems in the groups production and rmagick were not installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

テストの実行

“Crafting Rails 4 Applications” には「rake test でテストを実行できる」という旨の記述がありますが、これをやると次のようになります。

$ rake test
/Users/kymmt/my_plugin/test/dummy/db/schema.rb doesn't exist yet. Run `rails db:migrate` to create it, then try again. If you do not intend to use a database, you should instead alter /Users/kymmt/my_plugin/test/dummy/config/application.rb to limit the frameworks that will be loaded.
/Users/kymmt/my_plugin/test/test_helper.rb:9:in `<top (required)>': uninitialized constant Rails::TestUnitReporter (NameError)
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `require'
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `<top (required)>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `require'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `block in <main>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `select'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `<main>'
rake aborted!
Command failed with status (1)

Tasks: TOP => test
(See full trace by running task with --trace)

テスト用ダミーアプリケーションのDBマイグレーションができていないので、ダミーアプリケーションのルートディレクトリまで降りてから、DBマイグレーションを実行します。

$ cd test/dummy
$ rake db:migrate
$ cat db/schema.rb
# This file is auto-generated from the current state of the database. Instead
# of editing this file, please use the migrations feature of Active Record to
# incrementally modify your database, and then regenerate this schema definition.
#
# Note that this schema.rb definition is the authoritative source for your
# database schema. If you need to create the application database on another
# system, you should be using db:schema:load, not running all the migrations
# from scratch. The latter is a flawed and unsustainable approach (the more migrations
# you'll amass, the slower it'll run and the greater likelihood for issues).
#
# It's strongly recommended that you check this file into your version control system.

ActiveRecord::Schema.define(version: 0) do

end

これで、もう1回テストを実行すると、今度は次のエラーになります。

$ cd ../../
$ rake test
/Users/kymmt/my_plugin/test/test_helper.rb:9:in `<top (required)>': uninitialized constant Rails::TestUnitReporter (NameError)
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `require'
        from /Users/kymmt/my_plugin/test/my_plugin_test.rb:1:in `<top (required)>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `require'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:15:in `block in <main>'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `select'
        from /Users/kymmt/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/rake-12.0.0/lib/rake/rake_test_loader.rb:4:in `<main>'
rake aborted!
Command failed with status (1)

Tasks: TOP => test
(See full trace by running task with --trace)

これは test/test_helper.rbRails::TestUnitReporter を読み込んでないのが原因で、test/test_helper.rbrequire 'rails/test_unit/reporter' を加えれば動くようになります*1

ですが、実は “The Basics of Creating Rails Plugins — Ruby on Rails Guides” の第2節に書いてあるとおり、テストを実行するには bin/test を実行するだけでOKです。これは bin/test の中で rails/plugin/testrequire しており、その rails/plugin/test では Rails::TestUnitReporterrequire_relative されているからです*2

$ bin/test
Run options: --seed 60803

# Running:

.

Finished in 0.002613s, 382.6843 runs/s, 382.6843 assertions/s.
1 runs, 1 assertions, 0 failures, 0 errors, 0 skips

参考

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)