Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rschultheis/hatt

HTTP API Testing Tool
https://github.com/rschultheis/hatt

api-testing automated-testing faraday http-client minitest quality rest-api rspec testing

Last synced: 12 days ago
JSON representation

HTTP API Testing Tool

Awesome Lists containing this project

README 

        
# HATT (HTTP API Testing Tool)



HATT is a tool, and a pattern, for testing HTTP APIs (RESTful or otherwise).  It can be used to

construct fully automated tests, and also provides support for simple manual testing.



HATT is a Ruby tool and gem.  It leverages the full power of Ruby.  That said, HATT should be usable by those

with little familiarity of Ruby, but some knowledge of scripting languages in general.  HATT works with standard

Ruby testing frameworks like RSpec and MiniTest.



## Basic testing features



* Easily configure and interact with one or more HTTP services (RESTful services).

* "Point" tests and requests at various deployment environments (eg, QA, Staging, Production)

* Using RSpec or MiniTest or any other testing framework, construct fully automated tests.

* Easily define a "DSL", or domain-specific-language for interacting with your API in your

  own terms.  This allows for writing self-documenting, easy to understand tests.

* Easily integrates into popular Continuos Integration tools like Jenkins.  This means

  your tests can run on a central server where all team members can access them.



## Short Example



The code for this entire example lives at [https://github.com/rschultheis/hatt_example].

Looking through that project shows examples of using nearly every hatt feature,

and examples of many kinds of tests and assertions against APIs.



This example is based on a free API: OpenWeatherMap.  While the API is free, one must sign-up for an API key here:

[http://openweathermap.org/appid].  Keep your API key handy you will need it soon...



### Configure HATT, and setup a simple DSL method



#### install hatt



    gem install hatt



#### make a project directory



    mkdir open_weather_map_api_test_suite

    cd open_weather_map_api_test_suite



#### Make a file called 'hatt.yml' with these contents:



    hatt_services:

      # shothand of owm for "open weather map api"

      owm:

        url: http://api.openweathermap.org



#### Put our API key into hatt.secret.yml



We need a special place to put our API key. For that make a file called hatt.secret.yml.  This is a file that is generally not to be checked into source control, it should be used for configuring any secrets (like API keys or passwords). Put this one line into the file:



    owm_app_id: 



#### make the hattdsl directory:



    mkdir hattdsl



#### add method for checking weather to hattdsl/open_weather_map_hattdsl.rb



    def weather_for city

      owm.get "/data/2.5/weather?q=#{URI.encode(city)}&APPID=#{appid}"

    end



    def appid

      hatt_configuration['owm_app_id']

    end



#### Call it from the cmd line:



    hatt -v weather_for "Pleasantville, NY"



And that returns something like this:



    ... 

    D: [06/14/17 17:07:53][hatt] - HATT method 'weather_for' returned:

    {"coord"=>{"lon"=>-73.79, "lat"=>41.13}, "weather"=>[{"id"=>800, "main"=>"Clear", "description"=>"clear sky", "icon"=>"01d"}], "base"=>"stations", "main"=>{"temp"=>299.68, "pressure"=>1014, "humidity"=>39, "temp_min"=>296.15, "temp_max"=>303.15}, "visibility"=>16093, "wind"=>{"speed"=>4.1, "deg"=>190}, "clouds"=>{"all"=>1}, "dt"=>1497480900, "sys"=>{"type"=>1, "id"=>1980, "message"=>0.0057, "country"=>"US", "sunrise"=>1497432119, "sunset"=>1497486575}, "id"=>5131757, "name"=>"Pleasantville", "cod"=>200}



So, at this point we are able to call the API, and see the full details of the request and response.  We can manually

test a lot at this point.  But HATT can do more....



### Make a ruby script, that uses the hattdsl:



#### Make a file called temperatures.rb with this in it:



    [

      'New York, NY',

      'Toronto, Canada',

      'Paris, France',

      'Tokyo, Japan',

      'Sydney, Australia',

    ].each do |city|

      weather = weather_for city

      kelvin = weather['main']['temp']

      celcius = (kelvin - 273.15).round

      puts "#{city}: #{celcius} celcius"

    end



#### And then run the hatt script like so:



    hatt -q -f temperatures.rb



And get this nice output (-q supresses all the detailed request/response logging, leaving only the puts in the script):



    New York, NY: 18 celcius

    Toronto, Canada: 7 celcius

    Paris, France: 18 celcius

    Tokyo, Japan: 16 celcius

    Sydney, Australia: 14 celcius



### Make an automated test



Using the included Hatt::Mixin and Hatt::SingletonMixin module, testing an api becomes easy.  Lets setup a simple RSpec example here.



#### Install rspec:



    gem install rspec



#### Create the spec folder:



    mkdir spec



#### Setup spec/spec_helper.rb with these contents to :



    require 'hatt'



    RSpec.configure do |config|



      config.include Hatt::SingletonMixin



      config.before(:all) do

        hatt_initialize

      end

    end



#### Setup spec/weather_spec.rb with contents like:



    require 'spec_helper'

    describe "getting weather reports" do

      it "should know the weather for New York City" do

        response = weather_for 'New York, NY'

        expected_items = ['temp', 'temp_min', 'temp_max', 'humidity', 'pressure']

        # the actual assertions here

        expect(response['main'].keys).to include(*expected_items)

        # the temp is in kelvin, so it looks kinda wierd

        expect(response['main']['temp']).to be_between(100, 400)

      end

    end



#### Run it:



    rspec



And get back:



    ...  ...



    1 example, 0 failures



And THAT is the basic way to use HATT to test an API.



For more information, and more detailed examples of how to do nearly anything using HATT, see the example

project: [https://github.com/rschultheis/hatt_example]