Introducing Vigia: API testing using RAML files in ruby


#1

Hello,

I’d like to introduce Vigia to the RAML community. Vigia is ruby gem that generates integration RSpec test by consuming a RAML definition file. Short story, with a RAML file like this:

#%RAML 0.8
 
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
/songs:
  get:
    queryParameters:
      genre:
        description: filter the songs by genre
        example: 'rock'
    responses:
      200:
        body:
          application/json:
            schema: !include songs.json

Vigia will generate the following RSpec tests

describe Vigia::RSpec do
  describe 'Resource: songs' do
    describe 'Method: get' do
      describe 'Response 200' do
        describe 'Content type application/json' do
          it 'has a valid response code' do
            expect(response.status).to eql 200
          end
          # more examples run here
        end
      end
    end
  end
end

Currently, Vigia Raml support is still beta and some raml functionalities are not working (like the security schemas).

You can get more information about it on the project github: http://github.com/nogates/vigia

Cheers


#2

Cool David. Thanks for contributing. QQ: In a continues integration environment -> you would run Vigia during the testing phase. I guess you have to generate the RSpec test before and fill in the tests logic, or everything will be generated automatically?


#3

Everything will be generated automatically. The only three things you have to pass to the Vigia configuration block is the localisation of the raml file, the adapter class that it will be use (in this case Vigia::Adapter::Raml although, I am thinking in doing this automatically when user provoides a file with the .raml extension) and the host url of the API server you want to test. That’s it!


#4

Thanks David. So what is included in the testing besides valid response status?


#5

By default, Vigia runs two comparison for each request sent to the server. The first one, as I posted above, is that the response matches the expected http status code. The second one, is that the response headers includes the content type specified in the RAML definition file. In the example I posted above, the response should include application/json.

You can see the actual RSpec expectations for these two examples here: https://github.com/lonelyplanet/vigia/blob/master/lib/vigia/sail/examples/default.rb

These two examples run by default as I said, but Vigia can be easily extended. For example, you can create a new example that ensures the response is a valid JSON by including the following code

# expect the response body to be a valid SON block. don't do it if response status is 204 (no body)
Vigia::Sail::Example.register(
  :is_valid_json_response,
  expectation: -> { expect { JSON.parse(result.body) }.not_to raise_error },
  disable_if:  -> { result.code == 204 } 
)

You can get more information about how to include more examples in Vigia’s wiki page about shared examples and expectations/examples