hatt 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38589e6ed1df4b139b3339624ba5eb130548c062
-  data.tar.gz: 6b52ef37b1b0fc458b9ffd88c951e20d0efee1bc
+  metadata.gz: 8ec241d7bb22baf345d1380532c613ba88ee6e99
+  data.tar.gz: 3f322224a43da43dcf3ec9eba8de6d3931f621bc
 SHA512:
-  metadata.gz: a69fbe934e0a246fc33c7e3de4c00f5ae52fff5af334a408dc86319f6c2213fec4ca3e9963993db03c5180d7f06eaaf4a58e500411bf3141a40e5288858d7abc
-  data.tar.gz: 8e88242846ac574f6f811b5166d307aee6f8234789c3aaa1b9058a8e1e14f3ede903f57c07c726eed1d2600b3ed099619f0f5abd0cea1c0dd4017cfc1f60c473
+  metadata.gz: e3b146cbe7bcbbca8de97ad68c9da85a3eb1caad4a1b5dfe6c6d1070743e3643a2984455642067a71a545c0327dc9bc00102bc5dc983a0a178ca89b8322199ca
+  data.tar.gz: d6c9e9e406a432cb17d3d61353a894b571bca3bb0ec4b9794dff4be16ce4c35c5249e2da8b6d6eccc5b33c506f04876ea5c3a3ca5c666685a871fba2d7d0b975

data/Gemfile

@@ -19,9 +19,10 @@ gem 'awesome_print'
 
 group :development do
   gem 'debase'
-  gem 'jeweler'
+  gem 'jeweler', "~> 2"
   gem 'rspec'
   gem 'rubocop'
   gem 'ruby-debug-ide'
   gem 'simplecov'
+  gem 'rdoc2md'
 end

data/Gemfile.lock

@@ -1,120 +1,121 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (5.1.0)
+    activesupport (5.2.0)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (~> 0.7)
+      i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.1)
-      public_suffix (~> 2.0, >= 2.0.2)
-    ast (2.3.0)
-    awesome_print (1.7.0)
+    addressable (2.4.0)
+    ast (2.4.0)
+    awesome_print (1.8.0)
     builder (3.2.3)
-    coderay (1.1.1)
+    coderay (1.1.2)
     concurrent-ruby (1.0.5)
-    debase (0.2.1)
-      debase-ruby_core_source
-    debase-ruby_core_source (0.9.9)
+    debase (0.2.2)
+      debase-ruby_core_source (>= 0.10.2)
+    debase-ruby_core_source (0.10.3)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
-    docile (1.1.5)
-    ethon (0.10.1)
+    docile (1.3.1)
+    ethon (0.11.0)
       ffi (>= 1.3.0)
     faraday (0.9.2)
       multipart-post (>= 1.2, < 3)
-    ffi (1.9.18)
-    git (1.3.0)
-    github_api (0.11.3)
-      addressable (~> 2.3)
-      descendants_tracker (~> 0.0.1)
+    ffi (1.9.25)
+    git (1.4.0)
+    github_api (0.16.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
       faraday (~> 0.8, < 0.10)
-      hashie (>= 1.2)
-      multi_json (>= 1.7.5, < 2.0)
-      nokogiri (~> 1.6.0)
-      oauth2
-    hashie (3.5.5)
-    highline (1.7.8)
-    i18n (0.8.1)
-    jeweler (2.3.5)
+      hashie (>= 3.4)
+      mime-types (>= 1.16, < 3.0)
+      oauth2 (~> 1.0)
+    hashie (3.5.7)
+    highline (2.0.0)
+    i18n (1.0.1)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.1)
+    jeweler (2.3.9)
       builder
-      bundler (>= 1.0)
+      bundler
       git (>= 1.2.5)
-      github_api (~> 0.11.0)
+      github_api (~> 0.16.0)
       highline (>= 1.6.15)
       nokogiri (>= 1.5.10)
-      psych (~> 2.2)
+      psych
       rake
       rdoc
       semver2
     json (2.1.0)
     jwt (1.5.6)
-    method_source (0.8.2)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
-    multi_json (1.12.1)
+    method_source (0.9.0)
+    mime-types (2.99.3)
+    mini_portile2 (2.3.0)
+    minitest (5.11.3)
+    multi_json (1.13.1)
     multi_xml (0.6.0)
     multipart-post (2.0.0)
-    nokogiri (1.6.8.1)
-      mini_portile2 (~> 2.1.0)
-    oauth2 (1.3.1)
-      faraday (>= 0.8, < 0.12)
+    nokogiri (1.8.4)
+      mini_portile2 (~> 2.3.0)
+    oauth2 (1.4.0)
+      faraday (>= 0.8, < 0.13)
       jwt (~> 1.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
-    parser (2.4.0.0)
-      ast (~> 2.2)
-    powerpack (0.1.1)
-    pry (0.10.4)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.11.3)
       coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
-    psych (2.2.4)
-    public_suffix (2.0.5)
-    rack (2.0.1)
-    rainbow (2.2.2)
-      rake
-    rake (12.0.0)
-    rdoc (5.1.0)
-    rspec (3.5.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.4)
-      rspec-support (~> 3.5.0)
-    rspec-expectations (3.5.0)
+      method_source (~> 0.9.0)
+    psych (3.0.2)
+    rack (2.0.5)
+    rainbow (3.0.0)
+    rake (12.3.1)
+    rdoc (6.0.4)
+    rdoc2md (0.1.1)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-mocks (3.5.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-support (3.5.0)
-    rubocop (0.48.1)
-      parser (>= 2.3.3.1, < 3.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    rubocop (0.57.2)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5)
       powerpack (~> 0.1)
-      rainbow (>= 1.99.1, < 3.0)
+      rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-debug-ide (0.6.0)
+    ruby-debug-ide (0.6.1)
       rake (>= 0.8.1)
-    ruby-progressbar (1.8.1)
+    ruby-progressbar (1.9.0)
     semver2 (3.4.2)
-    simplecov (0.14.1)
-      docile (~> 1.1.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.0)
-    slop (3.6.0)
+    simplecov-html (0.10.2)
     tcfg (0.2.2)
       activesupport
     thread_safe (0.3.6)
-    typhoeus (1.1.2)
+    typhoeus (1.3.0)
       ethon (>= 0.9.0)
-    tzinfo (1.2.3)
+    tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    unicode-display_width (1.2.1)
+    unicode-display_width (1.4.0)
 
 PLATFORMS
   ruby
@@ -124,9 +125,10 @@ DEPENDENCIES
   awesome_print
   debase
   faraday
-  jeweler
+  jeweler (~> 2)
   multi_json
   pry
+  rdoc2md
   rspec
   rubocop
   ruby-debug-ide
@@ -135,4 +137,4 @@ DEPENDENCIES
   typhoeus
 
 BUNDLED WITH
-   1.13.6
+   1.16.2

data/README.md

@@ -0,0 +1,167 @@
+# 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: <your api key here>
+
+#### 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:
+
+    ... <detailed logging showing full request / response>
+    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:
+
+    ... <detailed logging showing all request response details> ...
+
+    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]

data/README.rdoc

@@ -1,62 +1,88 @@
-Hatt
-=======
-Do cool stuff with HTTP JSON APIs.  Designed for the real world of developing systems based on service-oriented-architecture.
+= HATT (HTTP API Testing Tool)
 
-What is Hatt?
-----------------
-Hatt is primarily designed to be used by software teams that build HTTP JSON services.
-Hatt makes it easy to:
-* Define "macro" methods that accomplish high level goals through service calls.
-* Call services or macro methods from the command line, adhoc scripts, or programtically within any Ruby program.
-* Test services using RSpec or other testing frameworks
-* "Point" at different environments (eg. QA, Staging, Production)
+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 relies heavily on the 'convention over configuration' approach.  For very little code, you
-get a lot of functionality.
+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.
 
-Hatt is based on [Faraday](https://github.com/lostisland/faraday), thus there is basic support for making requests concurrently, and for swapping out the HTTP "adapter".
+== Basic testing features
 
-Getting Started
----------------
-Lets demo how this works using a simple example of an API that requires no
-authentication.
+* 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.
 
-The OpenWeatherMap is a good candidate for a simple API
-which is accessible without needing any authentication key:
-[http://api.openweathermap.org/]
 
+== Short Example
 
-### make a project directory
+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.
 
-    mkdir weather
-    cd weather
+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...
 
-### setup hatt.yml
+=== Configure HATT, and setup a simple DSL method
 
-     services:
-       owm:
-         hostname: api.openweathermap.org
+==== install hatt
 
-### make the hatts directory, and a hatt file
+    gem install hatt
 
-    mkdir owm_hatts
-    touch owm_hatts/weather_hatts.rb
+==== 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: <your api key here>
+
+==== make the hattdsl directory:
+
+    mkdir hattdsl
+
+==== add method for checking weather to hattdsl/open_weather_map_hattdsl.rb
 
-### add method for checking weather to owm_hatts/weather.rb
     def weather_for city
-      owm.get "/data/2.5/weather?q=#{URI.encode(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 weather_for 'Pleasantville, NY'
+==== Call it from the cmd line:
+
+    hatt -v weather_for "Pleasantville, NY"
 
 And that returns something like this:
-    {"coord"=>{"lon"=>-73.79169, "lat"=>41.13436}, "sys"=>{"country"=>"United States of America", "sunrise"=>1366883974, "sunset"=>1366933583}, "weather"=>[{"id"=>501, "main"=>"Rain", "description"=>"moderate rain", "icon"=>"10d"}], "base"=>"global stations", "main"=>{"temp"=>290.46, "humidity"=>26, "pressure"=>1020, "temp_min"=>289.15, "temp_max"=>292.59}, "wind"=>{"speed"=>2.06, "gust"=>4.11, "deg"=>265}, "rain"=>{"1h"=>2.32}, "clouds"=>{"all"=>0}, "dt"=>1366926419, "id"=>5131757, "name"=>"Pleasantville", "cod"=>200}
 
-Use the -v command line option and see the full request/response logged to StdOut
+    ... <detailed logging showing full request / response>
+    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....
+
 
-### Script it
-Make a file called temperatures.rb with this in it:
+=== Make a ruby script, that uses the hattdsl:
+
+==== Make a file called temperatures.rb with this in it:
 
     [
       'New York, NY',
@@ -71,50 +97,71 @@ Make a file called temperatures.rb with this in it:
       puts "#{city}: #{celcius} celcius"
     end
 
-And then run the hatt script like so:
+==== And then run the hatt script like so:
 
-    hatt -f temperatures.rb
+    hatt -q -f temperatures.rb
 
-And get this nice output:
+And get this nice output (-q supresses all the detailed request/response logging, leaving only the puts in the script):
 
-    I: [04/25/13 17:59:22][hatt] - Running data script 'temperatures.rb'
     New York, NY: 18 celcius
     Toronto, Canada: 7 celcius
     Paris, France: 18 celcius
     Tokyo, Japan: 16 celcius
     Sydney, Australia: 14 celcius
 
-### Test it
-Using the included helper module, testing an api becomes easy.  Lets setup a simple RSpec example.  Step one is create the spec folder:
+
+=== 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 contents like:
+==== Setup spec/spec_helper.rb with these contents to :
 
-    require 'hatt/helpers'
+    require 'hatt'
 
     RSpec.configure do |config|
-      config.include Hatt::Helpers
+
+      config.include Hatt::SingletonMixin
+
+      config.before(:all) do
+        hatt_initialize
+      end
     end
 
-Setup spec/weather_spec.rb with contents like:
+==== 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']
-        response['main'].keys.should include(*expected_items)
+        # 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:
+==== Run it:
 
-    gem install rspec
     rspec
 
 And get back:
 
+    ... <detailed logging showing all request response details> ...
+
     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]

data/Readme.md

@@ -0,0 +1,167 @@
+# 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: <your api key here>
+
+#### 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:
+
+    ... <detailed logging showing full request / response>
+    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:
+
+    ... <detailed logging showing all request response details> ...
+
+    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]

data/bin/hatt

@@ -47,12 +47,8 @@ def parse_cmd_line
               ENV['HATT_ENVIRONMENT'] = e
             end
 
-    opts.on('-n', '--no-authenticate',
-            'Do not authenticate') { options[:authenticate] = false }
-
     opts.on('-l', '--list', 'Print each available hatt dsl method') do
       options[:list_hatt_methods] = true
-      options[:authenticate] = false # no point in authenticating for --list
     end
 
     opts.on('-r', '--pry-repl', 'Launch an interactice repl with full access to hatt services and dsl') do

data/hatt.gemspec

@@ -2,27 +2,29 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: hatt 0.0.1 ruby lib
+# stub: hatt 0.0.2 ruby lib
 
 Gem::Specification.new do |s|
-  s.name = "hatt"
-  s.version = "0.0.1"
+  s.name = "hatt".freeze
+  s.version = "0.0.2"
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.require_paths = ["lib"]
-  s.authors = ["Robert Schultheis"]
-  s.date = "2017-05-12"
-  s.description = "convention based approach to interfacing with an HTTP JSON API."
-  s.email = "robert.schultheis@gmail.com"
-  s.executables = ["hatt"]
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Robert Schultheis".freeze]
+  s.date = "2018-07-05"
+  s.description = "convention based approach to interfacing with an HTTP JSON API.".freeze
+  s.email = "robert.schultheis@gmail.com".freeze
+  s.executables = ["hatt".freeze]
   s.extra_rdoc_files = [
     "LICENSE.txt",
+    "README.md",
     "README.rdoc"
   ]
   s.files = [
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
+    "Readme.md",
     "bin/hatt",
     "hatt.gemspec",
     "lib/hatt.rb",
@@ -31,64 +33,66 @@ Gem::Specification.new do |s|
     "lib/hatt/blankslateproxy.rb",
     "lib/hatt/configuration.rb",
     "lib/hatt/dsl.rb",
-    "lib/hatt/hattmixin.rb",
     "lib/hatt/http.rb",
     "lib/hatt/json_helpers.rb",
     "lib/hatt/log.rb",
     "lib/hatt/mixin.rb",
     "lib/hatt/singleton_mixin.rb"
   ]
-  s.homepage = "http://github.com/rschultheis/hatt"
-  s.licenses = ["MIT"]
-  s.rubygems_version = "2.5.1"
-  s.summary = "Make calls to HTTP JSON APIs with ease and confidence"
+  s.homepage = "http://github.com/rschultheis/hatt".freeze
+  s.licenses = ["MIT".freeze]
+  s.rubygems_version = "2.6.14.1".freeze
+  s.summary = "Make calls to HTTP JSON APIs with ease and confidence".freeze
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activesupport>, [">= 0"])
-      s.add_runtime_dependency(%q<faraday>, [">= 0"])
-      s.add_runtime_dependency(%q<multi_json>, [">= 0"])
-      s.add_runtime_dependency(%q<tcfg>, ["~> 0.2.2"])
-      s.add_runtime_dependency(%q<typhoeus>, [">= 0"])
-      s.add_runtime_dependency(%q<pry>, [">= 0"])
-      s.add_runtime_dependency(%q<awesome_print>, [">= 0"])
-      s.add_development_dependency(%q<debase>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, [">= 0"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-      s.add_development_dependency(%q<rubocop>, [">= 0"])
-      s.add_development_dependency(%q<ruby-debug-ide>, [">= 0"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_runtime_dependency(%q<activesupport>.freeze, [">= 0"])
+      s.add_runtime_dependency(%q<faraday>.freeze, [">= 0"])
+      s.add_runtime_dependency(%q<multi_json>.freeze, [">= 0"])
+      s.add_runtime_dependency(%q<tcfg>.freeze, ["~> 0.2.2"])
+      s.add_runtime_dependency(%q<typhoeus>.freeze, [">= 0"])
+      s.add_runtime_dependency(%q<pry>.freeze, [">= 0"])
+      s.add_runtime_dependency(%q<awesome_print>.freeze, [">= 0"])
+      s.add_development_dependency(%q<debase>.freeze, [">= 0"])
+      s.add_development_dependency(%q<jeweler>.freeze, ["~> 2"])
+      s.add_development_dependency(%q<rspec>.freeze, [">= 0"])
+      s.add_development_dependency(%q<rubocop>.freeze, [">= 0"])
+      s.add_development_dependency(%q<ruby-debug-ide>.freeze, [">= 0"])
+      s.add_development_dependency(%q<simplecov>.freeze, [">= 0"])
+      s.add_development_dependency(%q<rdoc2md>.freeze, [">= 0"])
     else
-      s.add_dependency(%q<activesupport>, [">= 0"])
-      s.add_dependency(%q<faraday>, [">= 0"])
-      s.add_dependency(%q<multi_json>, [">= 0"])
-      s.add_dependency(%q<tcfg>, ["~> 0.2.2"])
-      s.add_dependency(%q<typhoeus>, [">= 0"])
-      s.add_dependency(%q<pry>, [">= 0"])
-      s.add_dependency(%q<awesome_print>, [">= 0"])
-      s.add_dependency(%q<debase>, [">= 0"])
-      s.add_dependency(%q<jeweler>, [">= 0"])
-      s.add_dependency(%q<rspec>, [">= 0"])
-      s.add_dependency(%q<rubocop>, [">= 0"])
-      s.add_dependency(%q<ruby-debug-ide>, [">= 0"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<activesupport>.freeze, [">= 0"])
+      s.add_dependency(%q<faraday>.freeze, [">= 0"])
+      s.add_dependency(%q<multi_json>.freeze, [">= 0"])
+      s.add_dependency(%q<tcfg>.freeze, ["~> 0.2.2"])
+      s.add_dependency(%q<typhoeus>.freeze, [">= 0"])
+      s.add_dependency(%q<pry>.freeze, [">= 0"])
+      s.add_dependency(%q<awesome_print>.freeze, [">= 0"])
+      s.add_dependency(%q<debase>.freeze, [">= 0"])
+      s.add_dependency(%q<jeweler>.freeze, ["~> 2"])
+      s.add_dependency(%q<rspec>.freeze, [">= 0"])
+      s.add_dependency(%q<rubocop>.freeze, [">= 0"])
+      s.add_dependency(%q<ruby-debug-ide>.freeze, [">= 0"])
+      s.add_dependency(%q<simplecov>.freeze, [">= 0"])
+      s.add_dependency(%q<rdoc2md>.freeze, [">= 0"])
     end
   else
-    s.add_dependency(%q<activesupport>, [">= 0"])
-    s.add_dependency(%q<faraday>, [">= 0"])
-    s.add_dependency(%q<multi_json>, [">= 0"])
-    s.add_dependency(%q<tcfg>, ["~> 0.2.2"])
-    s.add_dependency(%q<typhoeus>, [">= 0"])
-    s.add_dependency(%q<pry>, [">= 0"])
-    s.add_dependency(%q<awesome_print>, [">= 0"])
-    s.add_dependency(%q<debase>, [">= 0"])
-    s.add_dependency(%q<jeweler>, [">= 0"])
-    s.add_dependency(%q<rspec>, [">= 0"])
-    s.add_dependency(%q<rubocop>, [">= 0"])
-    s.add_dependency(%q<ruby-debug-ide>, [">= 0"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<activesupport>.freeze, [">= 0"])
+    s.add_dependency(%q<faraday>.freeze, [">= 0"])
+    s.add_dependency(%q<multi_json>.freeze, [">= 0"])
+    s.add_dependency(%q<tcfg>.freeze, ["~> 0.2.2"])
+    s.add_dependency(%q<typhoeus>.freeze, [">= 0"])
+    s.add_dependency(%q<pry>.freeze, [">= 0"])
+    s.add_dependency(%q<awesome_print>.freeze, [">= 0"])
+    s.add_dependency(%q<debase>.freeze, [">= 0"])
+    s.add_dependency(%q<jeweler>.freeze, ["~> 2"])
+    s.add_dependency(%q<rspec>.freeze, [">= 0"])
+    s.add_dependency(%q<rubocop>.freeze, [">= 0"])
+    s.add_dependency(%q<ruby-debug-ide>.freeze, [">= 0"])
+    s.add_dependency(%q<simplecov>.freeze, [">= 0"])
+    s.add_dependency(%q<rdoc2md>.freeze, [">= 0"])
   end
 end
 

data/lib/hatt/configuration.rb

@@ -5,7 +5,7 @@ require 'tcfg/tcfg_base'
 module Hatt
   module Configuration
     DEFAULT_CONFIG_FILE = 'hatt.yml'.freeze
-    DEFAULT_HATT_GLOBS = ['*_hattdsl/*_hattdsl.rb'].freeze
+    DEFAULT_HATT_GLOBS = ['*hattdsl/*hattdsl.rb'].freeze
 
     def hatt_configuration
       init_config

data/lib/hatt/http.rb

@@ -97,7 +97,7 @@ module Hatt
       end
 
 
-      log_request(method, parsed_uri, query_hash, headers, body)
+      log_request(method, parsed_uri, query_hash, req_headers, body)
 
       # doing it this way avoids problem with OPTIONS method: https://github.com/lostisland/faraday/issues/305
       response = nil
@@ -204,15 +204,18 @@ module Hatt
     end
 
     def log_response(response, response_obj)
+      log_messages = [
+        'Response Details:',
+        @log_headers ? ['Response Headers:',
+                        response.headers.map { |k, v| "#{k}: #{v.inspect}" }] : nil
+      ]
       if response.headers['content-type'] =~ /json/
-        logger.debug [
-          'Response Details:',
-          @log_headers ? ['Response Headers:',
-                          response.headers.map { |k, v| "#{k}: #{v.inspect}" }] : nil,
+        log_messages += [
           @log_bodies ? ['Response Body:', jsonify(response_obj)] : nil,
           ''
-        ].flatten.compact.join("\n")
+        ]
       end
+      logger.debug log_messages.flatten.compact.join("\n")
     end
 
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hatt
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Robert Schultheis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-12 00:00:00.000000000 Z
+date: 2018-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -126,16 +126,16 @@ dependencies:
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +192,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc2md
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: convention based approach to interfacing with an HTTP JSON API.
 email: robert.schultheis@gmail.com
 executables:
@@ -199,12 +213,15 @@ executables:
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
+- README.md
 - README.rdoc
 files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- README.md
 - README.rdoc
+- Readme.md
 - bin/hatt
 - hatt.gemspec
 - lib/hatt.rb
@@ -213,7 +230,6 @@ files:
 - lib/hatt/blankslateproxy.rb
 - lib/hatt/configuration.rb
 - lib/hatt/dsl.rb
-- lib/hatt/hattmixin.rb
 - lib/hatt/http.rb
 - lib/hatt/json_helpers.rb
 - lib/hatt/log.rb
@@ -239,7 +255,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.14.1
 signing_key: 
 specification_version: 4
 summary: Make calls to HTTP JSON APIs with ease and confidence

data/lib/hatt/hattmixin.rb

@@ -1,21 +0,0 @@
-require_relative 'configuration'
-require_relative 'api_clients'
-require_relative 'dsl'
-
-module Hatt
-  module HattMixin
-    include Hatt::Configuration
-    include Hatt::DSL
-    include Hatt::ApiClients
-
-    def initialize(*opts)
-      hatt_initialize
-      super(*opts)
-    end
-
-    def hatt_initialize
-      hatt_build_client_methods
-      load_hatts_using_configuration
-    end
-  end
-end