riot-gear 0.0.8 → 0.0.9

data/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+.bundle/*
+*.tmproj
+pkg/*
+.rvmrc
+*.swp
+.watchr
+.yardoc
+Gemfile.lock
+

data/.yardopts

@@ -0,0 +1,6 @@
+-r README.markdown
+--protected
+--no-private
+-
+CHANGELOG
+MIT-LICENSE

data/CHANGELOG

@@ -0,0 +1,39 @@
+# @markup markdown
+
+# 0.0.9
+
+* get, post, put, delete can have responses saved for use in other requests within the same (or nested) context [jaknowlden]
+
+```ruby
+context GoNuts do
+  post(:the_new_nut) do
+    { :path => "/make/some", :body => "..." }
+  end
+
+  get do
+    { :path => "/get/some/#{response(:the_new_nut)["id"]}" }
+  end
+end
+```
+
+The last get, post, put, or delete in the context will still be the one used for assertions.
+
+* get, post, put, delete can take a block that expects a settings hash to be returned (with a path) [jaknowlden]
+
+```ruby
+context GoNuts do
+  post do
+    { :path => "/make/some", :body => "..." }
+  end
+
+  get do
+    { :path => "/get/some", :query => { ... } }
+  end
+end
+```
+
+* tons of documentation [jaknowlden]
+
+# 0.0.8 and before
+
+See the commit log: http://github.com/thumblemonks/riot-gear/commits/master

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gemspec
+
+group "test" do
+  gem "rake", ">=0.8.7"
+  gem "webmock", ">=1.6.1"
+end
+

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Justin Knowlden, Thumble Monks
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,17 +1,90 @@
 # Riot Gear
 
-Real HTTP-based smoke testing with a real testing framework; [Riot](http://thumblemonks.github.com/riot) + [HTTParty]().
+Riot Gear is a framework for HTTP-based smoke testing using a real testing framework; [Riot](http://thumblemonks.github.com/riot) + [HTTParty](http://github.com/jnunemaker/httparty). The principle impetus for creating Riot Gear came from a desire to easily develop a suite of smoke tests for a few, JSON-based web services. On one hand you could use Riot Gear to develop in-depth integration tests hitting a local testing environment that are constantly run through your continuous integration system. On the other hand, you could use Riot Gear to implement real smoke tests that hit your production environment frequently and/or maybe after a release. From this you can derive that Riot Gear does not intend to replace Selenium (Se) or any of Se's "competitors". Nope ... Riot Gear just wants to make the real-world testing of web-enabled APIs easier.
 
-    require 'teststrap'
+How Riot Gear does this is by combining two things I enjoy; Riot for its lightweight, contextual, and flexible testing framework; and HTTParty for its simplistic and powerful approach to providing HTTP enabled APIs (so to speak). The resulting DSL essentially allows one to mix HTTParty behavior directly with Riot behavior; i.e. build up and make an HTTP request and then test its response.
 
-    context "Logging into Example.com as foo" do
+Here's an example involving a hypothetical login and login failure:
+
+    require 'riot/gear'
+
+    context "Logging into Example.com as good.user" do
+      base_uri "http://example.com"
+      post "/session", :body => {"email" => "good.user@example.com", "password" => "p4$sw0R)"}
+
+      asserts_status.equals(200)
+      asserts_header("Content-Type").equals("application/json;charset=utf-8")
+      asserts_json("user.name").equals("Slick Rick")
+    end
+
+    context "Failing to log into Example.com as good.user" do
+      base_uri "http://example.com"
+      post "/session", :body => {"email" => "good.user@example.com", "password" => "y0uF41l"}
+
+      asserts_status.equals(403)
+      asserts_header("Content-Type").equals("application/json;charset=utf-8")
+      asserts_json("error.message").matches(/email or password is invalid/i)
+    end
+
+If you're familiar with Riot and/or HTTParty you'll recognize their natures immediately. To begin, there are two Riot `context` blocks. Each context (and any of the sub-contexts) are independent from each other; this is in keeping with the nature of Riot. Within each context there will be setup code and then validation code. Setup code will most likely be reflected as HTTParty calls - though you should feel free to use Riot's helpers, setups, and hookups; whereas validation code will always be Riot (until this statement is wrong).
+
+Thus, in the two example contexts, the setup code involves telling HTTParty what the `base_uri` is that any HTTP requests for that context will be made to; followed by the actual HTTP request - a `post` to `/session` with login credentials. After the `post` is sent, the `HTTParty::Response` object is made available for validation as the Riot helper named `response`.
+
+Riot Gear provides a few built-in assertions for validating common response information, which you see above: `asserts_status`, `asserts_header`, and `asserts_json`. Each of these generate normal Riot assertions that can have assertion macros applied to them (eg. `equals`, `kind_of`, `matches`, `nil`, `exists`, etc.). You could easily replace what `asserts_status` does in the example above with this:
+
+    asserts("status code") do
+      response.code
+    end.equals(200)
+
+## Priming a request
+
+A common problem when testing services is that you need to perform a few activities before you can perform the one you want to test. For instance, you may need to login and create some resource before you can test an update to that resource. This is simple enough in Riot Gear since the last request made through `get`, `post`, `put`, `delete`, or `head` is the one whose response will be validated. For instance:
+
+    require 'riot/gear'
+
+    context "Updating a playlist" do
       base_uri "http://example.com"
-      get "/session/new?username=foo&password=password"
+
+      post "/session", :body => {"email" => "good.user@example.com", "password" => "p4$sw0R)"}
+      persist_cookie("example_session")
+
+      post "/user/playlists", :body => {"name" => "Dubsteppin to the oldies"}
+      put "/user/playlists/dubsteppin-to-the-oldies", :body => {"name" => "Dubsteppin to the newbies"}
 
       asserts_status.equals(200)
       asserts_header("Content-Type").equals("application/json;charset=utf-8")
+      asserts_json("data.message").equals("Playlist updated successfully")
+    end
+
+The `post` commands and the `put` will execute in the order they are defined. However, only the response from the `put` will be used for validation. It also would not matter where in the context you put the assertions because they always run last. For instance, this context is effectually the same as the one above:
+
+    require 'riot/gear'
+
+    context "Updating a playlist" do
+      base_uri "http://example.com"
+
+      post "/session", :body => {"email" => "good.user@example.com", "password" => "p4$sw0R)"}
+      persist_cookie("example_session")
+
+      asserts_json("data.message").equals("Playlist updated successfully")
 
-      # ... more stuff
+      post "/user/playlists", :body => {"name" => "Dubsteppin to the oldies"}
+
+      asserts_header("Content-Type").equals("application/json;charset=utf-8")
+
+      put "/user/playlists/dubsteppin-to-the-oldies", :body => {"name" => "Dubsteppin to the newbies"}
+
+      asserts_status.equals(200)
     end
 
-Lots lots more to come soon.
+*This fact is likely to change soon.*
+
+## Coming soon
+
+* Reusable macro-like blocks
+* Priming a test against another host via `at_host`
+* Sequential command processing
+
+## License
+
+Riot Gear is released under the MIT license. See {file:MIT-LICENSE}.

data/Rakefile

@@ -1,6 +1,6 @@
 require 'rubygems'
-
-require 'rake'
+require 'bundler'
+Bundler::GemHelper.install_tasks
 require 'rake/testtask'
 
 #
@@ -15,34 +15,14 @@ task(:console) { exec "irb -r boot" }
 
 #
 # Testing
+task :default => ["test"]
 
 Rake::TestTask.new("test") do |t|
   t.libs << "test"
   t.pattern = "test/**/*_test.rb"
+  #t.warning = true
   t.verbose = false
 end
-Rake::Task["test"].instance_variable_set(:@full_comment, nil) # Dumb dumb dumb
-Rake::Task["test"].comment = "Run the tests!"
 
 task :default => :test
 
-#
-# Some monks like diamonds. I like gems.
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "riot-gear"
-    gem.summary = "Riot + HTTParty smoke testing framework"
-    gem.description = "Riot + HTTParty smoke testing framework. You'd use it for integration testing with real HTTP requests and responses"
-    gem.email = "gus@gusg.us"
-    gem.homepage = "http://github.com/thumblemonks/riot-gear"
-    gem.authors = ["Justin 'Gus' Knowlden"]
-    gem.add_dependency 'riot'
-    gem.add_dependency 'httparty'
-    gem.add_development_dependency 'webmock', ">=1.6.1"
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end

data/lib/riot/gear/context/asserts_header.rb

@@ -4,6 +4,12 @@ module Riot
   module Gear
     module AssertsHeader
 
+      # Generates an assertion that retrieves the value of some header from the last response.
+      #
+      #   asserts_header("Content-Length").equals("125")
+      #
+      # @param [String] header_key the name of the header
+      # @return [Riot::Assertion] an assertion block that macros can be applied to
       def asserts_header(header_key)
         asserts("header variable #{header_key}") { response.headers[header_key] }
       end

data/lib/riot/gear/context/asserts_json.rb

@@ -4,15 +4,29 @@ module Riot
   module Gear
     module AssertsJson
 
-      # Returns the value of passing the JSON path to the json_path helper. If a handler block is provided,
-      # that block will be called with the value and the response from the block will be used as the actual
-      # in the assertion test.
+      # Generates an assertion that based on the value returned from passing the JSON path to the json_path
+      # helper. If a handler block is provided, that block will be called with the value and the response
+      # from the block will be used as the actual in the assertion test.
       #
-      #   asserts_json("http.status_code").equals(200)
+      #   context "testing a hash" do
+      #     setup do
+      #       {"a" => {"b" => {"c" => {"d" => "foo"}}}}
+      #     end
       #
-      #   asserts_json("http") do |value|
-      #     value["status_code"]
-      #   end.equals(200)
+      #     asserts_json("a.b.c.d").equals("foo")
+      #     asserts_json("a['b'].c['d']").equals("foo")
+      #
+      #     asserts_json("a.b") do |value|
+      #       value["c"]
+      #     end.equals({"d" => "foo"})
+      #  end
+      #
+      # This is useful for testing actual JSON responses from some service that are converted to a hash by
+      # HTTParty.
+      #
+      # @param [String] json_string a JSON looking path
+      # @param [lambda] &handler an optional block for filtering the actual value
+      # @return [Riot::Assertion] an assertion block that macros can be applied to
       def asserts_json(json_string, &handler)
         asserts("value from body as json:#{json_string}") do
           value = json_path(response, json_string)

data/lib/riot/gear/context/asserts_status.rb

@@ -4,6 +4,12 @@ module Riot
   module Gear
     module AssertsStatus
 
+      # Generates an assertion that retrieves the status code from the last response. The statuc code will
+      # be an integer.
+      #
+      #   asserts_status.equals(200)
+      #
+      # @return [Riot::Assertion] an assertion block that macros can be applied to
       def asserts_status
         asserts("status code") { response.code }
       end

data/lib/riot/gear/context/persist_cookie.rb

@@ -5,6 +5,23 @@ module Riot
   module Gear
     module PersistCookie
 
+      # Graft a cookie (name and value) from the last response onto the next and subsequent requests. Only
+      # applies to multiple requests within a {Riot::Context}. For instance, if you log into your service,
+      # you will probably want to pass along whatever the session cookie was to the next request in the test.
+      #
+      #   context "Get new messages" do
+      #     base_uri "http://example.com"
+      #     post "/session?email=foo@bar.baz&password=beepboopbop"
+      #
+      #     persist_cookie("example_session")
+      #
+      #     get "/user/messages.json"
+      #     asserts_status.equals(200)
+      #     asserts_json("messages").length(8)
+      #   end
+      #
+      # @param [String] cookie_name the name of a cookie to persist
+      # @return [Riot::Assertion] an assertion block that macros can be applied to
       def persist_cookie(cookie_name)
         hookup do
           if cookie_value = cookie_values[cookie_name]

data/lib/riot/gear/middleware/riotparty.rb

@@ -2,9 +2,18 @@ require 'httparty'
 
 module Riot
   module Gear
+    # Here we prepare a {Riot::Context} to have HTTParty bound to it. Basically, this means that you can
+    # use HTTParty within a context the same way you would inside any class or you would normally use it in.
+    # Anything you can do with HTTParty, you can do within a context ... and then you can test it :)
+    #
+    # Great pains are made to ensure that the HTTParty setup bound to one context does not interfere setup 
+    # bound to another context.
     class RiotPartyMiddleware < ::Riot::ContextMiddleware
       register
 
+      # Prepares the context for HTTParty support.
+      #
+      # @param [Riot::Context] context the context to prepare
       def call(context)
         setup_faux_class(context)
         setup_helpers(context)
@@ -16,49 +25,93 @@ module Riot
     private
 
       # Only cluttering anonymous classes with HTTParty stuff. Keeps each context safe from collision ... in
-      # theory
+      # theory.
+      #
+      # @param [Riot::Context] context the context to create the setup for
+      # @todo Fix this so that settings like +base_uri+ can be inherited
       def setup_faux_class(context)
         context.setup(true) do
+          @saved_responses = {}
+
           Class.new do
             include HTTParty
             # debug_output $stderr
           end
         end
 
-        context.helper(:response) { @smoke_response }
+        context.helper(:response) do |name=nil|
+          @saved_responses[name] || @smoke_response
+        end
       end # setup_faux_class
 
+      # Returns the list of methods that do something; like make a network call.
       #
-      # Method proxying. This is the meat of the DSL.
-
+      # @return [Array<Symbol>]
       def actionable_methods; [:get, :post, :put, :delete, :head]; end
 
-      def proxy_action_methods(context)
-        proxy_class_methods_to_context(context, actionable_methods) do |situation, result|
-          situation.instance_eval { @smoke_response = result }
-        end
-      end
-
+      # Returns the list of methods that configure actionable HTTParty methods. The {HTTParty.options} and
+      # {HTTParty.default_options} methods are explicitly excluded from this list
+      #
+      # @return [Array<Symbol>]
       def proxiable_methods
         methods = HTTParty::ClassMethods.instance_methods.map { |m| m.to_s.to_sym }
         methods - actionable_methods - [:options, :default_options]
       end
 
-      def proxy_httparty_hookups(context)
-        proxy_class_methods_to_context(context, proxiable_methods)
-      end
-
-      # Basically, we're just passing standard HTTParty setup methods onto situation via hookups
-      def proxy_class_methods_to_context(context, methods, &proxy_block)
-        methods.each do |method_name|
-          (class << context; self; end).__send__(:define_method, method_name) do |*args|
+      # Bind the set of actionable methods to a given context.
+      #
+      # Basically, we're just passing standard HTTParty setup methods onto situation via hookups. These
+      # hookups - so long as the topic hasn't changed yet - are bound to an anonymous class that has
+      # HTTParty included to it. Meaning, this is how you call get, post, put, delete from within a
+      # test.
+      #
+      # There are couple of different forms for these actions. As you would expect, there's:
+      #
+      #   get "/path", :query => {...}, ...
+      #
+      # But you can also record the response for use later in the test:
+      #
+      #   post(:new_thing) do
+      #     { :path => "/things", :body => ... }
+      #   end
+      #
+      #   get do # this response will be used for assertions since it's last
+      #     { :path => "/things/#{response(:new_thing).id}/settings" }
+      #   end
+      #
+      # @param [Riot::Context] context the context to add the helper to
+      def proxy_action_methods(context)
+        context_eigen = (class << context; self; end)
+        actionable_methods.each do |method_name|
+          context_eigen.__send__(:define_method, method_name) do |*args, &settings_block|
             hookup do
-              result = topic.__send__(method_name, *args)
-              yield(self, result) if proxy_block
+              if settings_block
+                name = args.first
+                options = instance_eval(&settings_block)
+                path = options.delete(:path) || "/"
+              else
+                name = nil
+                path, options = *args
+              end
+              result = topic.__send__(method_name, path, options || {})
+              @saved_responses[name] = result
+              @smoke_response = result # TODO remove this after it's certain no usages in the wild
             end
-          end # class << context
+          end
         end # methods.each
-      end # proxy_class_methods_to_context
+      end
+
+      # Bind the set of proxiable (non-action) methods to a given context.
+      #
+      # @param [Riot::Context] context the context to add the helper to
+      def proxy_httparty_hookups(context)
+        context_eigen = (class << context; self; end)
+        proxiable_methods.each do |method_name|
+          context_eigen.__send__(:define_method, method_name) do |*args|
+            hookup { topic.__send__(method_name, *args) }
+          end
+        end # methods.each
+      end
 
       #
       # Helpful helpers
@@ -70,13 +123,13 @@ module Riot
 
       # Maps a JSON string to a Hash tree. For instance, give this hash:
       #
-      #     json_object = {"a" => {"b" => "c" => {"d" => "foo"}}}
+      #     json_object = {"a" => {"b" => {"c" => {"d" => "foo"}}}}
       #
       # You could retrieve the value of 'd' via JSON notation in any of the following ways:
       #
       #     json_path(json_object, "a.b.c.d")
       #     => "foo"
-      #     json_path(json_object, "a['b'].c[d]")
+      #     json_path(json_object, "a['b'].c['d']")
       #     => "foo"
       #
       # You can even work with array indexes
@@ -84,6 +137,8 @@ module Riot
       #     json_object = {"a" => {"b" => "c" => ["foo", {"d" => "bar"}]}}
       #     json_path(json_object, "a[b].c[1].d")
       #     => "bar"
+      #
+      # @param [Riot::Context] context the context to add the helper to
       def helper_json_path(context)
         context.helper(:json_path) do |dictionary, path|
           return nil if path.to_s.empty?
@@ -102,6 +157,8 @@ module Riot
       #       "stupid_marketing_tricks" => {"value" => "personal-information", ...},
       #       ...
       #     }
+      #
+      # @param [Riot::Context] context the context to add the helper to
       def helper_cookie_value(context)
         context.helper(:cookie_values) do
           response.header["set-cookie"].split("\n").inject({}) do |jar, cookie_str|