Murker

Murker detects changes in schemas of Rails API-interactions in json-format.

To use murker, tag spec having API-interaction with :murker tag.

In first run murker will generate and save schema of interaction in Open API v3 format [https://swagger.io/docs/specification/about/].

Next time it will validate an interaction against stored schema and fail if schema has changed.

Usage

Let's say we have nested resource Martians/Pets in V1 namespace.

We can write a request-spec and tag it with :murker tag:

require 'rails_helper'
require 'murker/spec_helper'

RSpec.describe V1::PetsController, type: :request do

  describe "GET pet" do
    it "returns a success response", :murker do
      martian = Martian.create! name: 'spajic', age: 30, id: 1
      martian.pets.create! name: 'chubby', weight: 10, id: 1

      get '/v1/martians/1/pets/1.json'

      expect(response).to be_success
    end
  end
end

After first run murker will generate OAS3 schema and dump it to /spec/murker/v1/martians/__martian_id/pets/__id/GET.yml

---
openapi: 3.0.0
info:
  title: Generated by Murker
  version: 0.1.0
paths:
  "/v1/martians/{martian_id}/pets/{id}":
    get:
      parameters:
      - in: path
        name: martian_id
        description: martian_id
        schema:
          type: integer
        required: true
        example: '1'
      - in: path
        name: id
        description: id
        schema:
          type: integer
        required: true
        example: '1'
      responses:
        "'200'":
          description: GET /v1/martians/:martian_id/pets/:id -> 200
          content:
            application/json:
              schema:
                type: object
                required:
                - name
                - weight
                properties:
                  name:
                    type: string
                  weight:
                    type: integer

This schema can be supplied to swagger. [https://editor.swagger.io/]

Let's say we accedentally changed schema of response. For example, openapi version was changed from 3.0.0 to 4.0.0 and age propertie was removed.

In that case murker will fail test with message, saying what have actually changed.

Murker::ValidationError:
  MURKER VALIDATION FAILED!

  Interaction 'GET /v1/martians/:martian_id/pets/:id' failed! Scheam changed:
  -openapi: 3.0.0
  +openapi: 4.0.0
   info:
     title: Generated by Murker
     version: 0.1.0
   paths:
     "/martians":
       get:
         responses:
           "'200'":
             content:
               application/json:
                 schema:
                   type: array
                   minItems: 1
                   uniqueItems: true
                   items:
                     type: object
                     required:
                     - name
                     - age
                     properties:
                       name:
                         type: string
  -                    age:
  -                      type: integer

Installation

Add this line to your application's Gemfile:

group :test
  gem 'murker'
end

And then execute:

$ bundle

Or install it yourself as:

$ gem install murker

require 'murker/spec_helper' # in your specs

Features

• TravisCI integration
• Rspec tests and Cucumber tests via prepared rails 5.1 test-app
• Generation of valid OAS3 schema
• Support to capture multiple interactions per block
• Support tag (:murker) and block (Murker.capture {}) syntax
• Diff of schemas via diffy gem [https://github.com/samg/diffy]

TODO

• Support and test different versions of rails and ruby
• Support minitest
• Automatically validate generated schemas against OAS3 spec
• Handle compatible and incompatible changes of schema differently
• Allow non-necessary attributes to vary (require only necessary attributes to be equal)
• Generate schema for form-encoded params?
• Generate more OAS3 schema attributes?
• Refactor
• Improve Readme

Limitations

• Capture maximum 1 interaction in :controller spec (see rails/rails#13851)
• Only support application/json interactions yet

Development

To run cucumber specs:

bundle exec appraisal install
bundle exec appraisal rails-5 cucumber
rm -r spec/murker && bundle exec appraisal reils-5 cucumber

To run rspec specs:

rspec

You can also run prepared test app:

cd test_apps/rails_51
rails s

And you can run specs of prepared test app:

cd test_apps/rails_51
rspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aderyabin/murker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Murker project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.