api-testing 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use ree@contracted

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in api-testing.gemspec
+gemspec

data/README

@@ -0,0 +1,32 @@
+Contracted
+==========================================================
+Contracted provides a few tools to describe HTTP Responses
+and HTTP Response bodies.
+
+A few cucumber steps are implemented which faciliated this
+description.
+
+
+JSON Description Grammar
+----------------------------------------------------------
+The JSON Description Grammar is a superset of JSON which 
+adds some wildcards allowing you to describe the parts of
+the response your interested in. Example:
+
+{
+  "message": {
+    "text": ...,
+    ...
+  }
+}
+
+This says that the 'message' object has an entry with key
+'text' and any number of other entries.
+
+The cucumber features provide more examples.
+
+The grammar is based on the JSON parser from the following
+blog post:
+
+http://coderrr.wordpress.com/2008/02/13/treetop-is-cool/
+

data/Rakefile

@@ -0,0 +1,18 @@
+$:.unshift(File.dirname(__FILE__) + '/../../lib')
+
+require 'bundler'
+require 'cucumber/rake/task'
+require 'rspec/core/rake_task'
+
+desc 'Runs specs'
+RSpec::Core::RakeTask.new do |t|
+end
+
+Bundler::GemHelper.install_tasks
+
+desc 'Runs features'
+Cucumber::Rake::Task.new do |t|
+    t.cucumber_opts = %w{--format pretty}
+end
+
+task :default => [:spec, :cucumber]

data/contracted.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "contracted/version"
+
+Gem::Specification.new do |s|
+  s.name        = "api-testing"
+  s.version     = Contracted::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Andrew Kiellor"]
+  s.email       = ["akiellor@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Contracted is a tool aimed at testing JSON API's.}
+  s.description = %q{
+    Contracted is a tool aimed at testing JSON API's.
+  }
+
+  s.rubyforge_project = "contracted"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.add_dependency('cucumber')
+  s.add_dependency('thin')
+  s.add_dependency('rest-client')
+  s.add_dependency('activesupport')
+  s.add_dependency('rspec')
+  s.add_dependency('treetop')
+  s.add_dependency('polyglot')
+end

data/features/echo.feature

@@ -0,0 +1,18 @@
+Feature: Echo app responds with message
+
+Scenario: GET with message 'hello'
+  Given the "Echo" app is running
+  When an api client performs GET /?message=hello
+  Then the json response body should look like:
+  """
+  {"message": "hello"}
+  """
+
+Scenario: GET with any message
+  Given the "Echo" app is running
+  When an api client performs GET /?message=blah
+  Then the json response body should look like:
+  """
+  {"message": ...}
+  """
+

data/features/echo_body.feature

@@ -0,0 +1,71 @@
+Feature: EchoBody app responds with message
+
+Scenario: POST with body '{"message": "hello"}'
+  Given the "EchoBody" app is running
+  When an api client performs POST / with json body:
+  """
+    {'message': 'hello'}
+  """
+  Then the json response body should look like:
+  """
+  {"message": "hello"}
+  """
+
+Scenario: POST with body '{"message": "hello", "sender": "Tom"}'
+  Given the "EchoBody" app is running
+  When an api client performs POST / with json body:
+  """
+    {
+      "message": "hello",
+      "sender": "Tom"
+    }
+  """
+  Then the json response body should look like:
+  """
+  {
+    "message": "hello",
+    "sender": ...
+  }
+  """
+
+Scenario: POST with nested object body
+  Given the "EchoBody" app is running
+  When an api client performs POST / with json body:
+  """
+    {
+      "message": {
+        "sender": "Tom",
+        "text": "Hello"
+      }
+    }
+  """
+  Then the json response body should look like:
+  """
+  {
+    "message": {
+      "sender": "Tom",
+      "text": ...
+    }
+  }
+  """
+
+Scenario: POST with nested object body using wilcard match
+  Given the "EchoBody" app is running
+  When an api client performs POST / with json body:
+  """
+    {
+      "message": {
+        "sender": "Tom",
+        "text": "Hello"
+      }
+    }
+  """
+  Then the json response body should look like:
+  """
+  {
+    "message": {
+      "sender": ...,
+      ...
+    }
+  }
+  """

data/features/hello_world.feature

@@ -0,0 +1,17 @@
+Feature: HelloWorld app says "Hello World"
+
+Scenario: GET /
+  Given the "HelloWorld" app is running
+  When an api client performs GET /
+  Then the json response body should look like:
+  """
+  {"message": "Hello World"}
+  """
+
+Scenario: GET / has message
+  Given the "HelloWorld" app is running
+  When an api client performs GET /
+  Then the json response body should look like:
+  """
+  {"message": ...}
+  """

data/features/support/apps/echo.rb

@@ -0,0 +1,6 @@
+class Echo
+  def call env
+    message = Rack::Request.new(env).params["message"]
+    [200, {'Content-Type' => 'application/json'}, "{'message': '#{message}'}"]
+  end
+end

data/features/support/apps/echo_body.rb

@@ -0,0 +1,5 @@
+class EchoBody
+  def call env
+    [200, {'Content-Type' => 'application/json'}, Rack::Request.new(env).body]
+  end
+end

data/features/support/apps/hello_world.rb

@@ -0,0 +1,5 @@
+class HelloWorld
+  def call env
+    [200, {'Content-Type' => 'application/json'}, '{"message": "Hello World"}']
+  end
+end

data/features/support/env.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../../lib')
+require 'contracted'
+require 'contracted/cucumber'

data/lib/contracted.rb

@@ -0,0 +1,5 @@
+require 'polyglot'
+require 'treetop'
+
+require 'contracted/application'
+require 'contracted/json_description'

data/lib/contracted/application.rb

@@ -0,0 +1,61 @@
+require 'thin'
+require 'rest_client'
+Thin::Logging.silent = true
+
+module Contracted
+  def self.mount app, port = '9898'
+    @app = Application.new app, port.to_s
+  end
+
+  def self.app
+    @app
+  end
+
+  class Application
+    APPLICATION_START_TIMEOUT = 5
+    attr_reader :last, :app, :host, :port, :server
+
+    def initialize app, port
+      @app = app
+      @host = "0.0.0.0"
+      @port = port
+      @server = Thin::Server.new(host, port.to_s) { run app }
+      mount
+    end
+
+    def host_and_port
+      "#{host}:#{port}"
+    end
+
+    def unmount
+      @server.stop
+      @server_thread.terminate
+    end
+
+    def mount
+      @server_thread = Thread.start do
+        server.start
+      end
+      Timeout.timeout(APPLICATION_START_TIMEOUT) do
+        loop_until { server.running? }
+      end
+    end
+
+    def get url, body, headers
+      @last = RestClient.get("#{host_and_port}#{url}", headers)
+    end
+
+    [:post, :put, :delete].each do |method|
+      define_method(method) do |url, body, headers|
+        @last = RestClient::Resource.new("#{host_and_port}#{url}", {}).send(method, body.to_s, headers)
+      end
+    end
+
+    private
+
+    def loop_until &block
+      loop { break if begin block.call rescue false end; sleep(1) }
+    end
+  end
+end
+

data/lib/contracted/cucumber.rb

@@ -0,0 +1,27 @@
+require 'contracted'
+require 'active_support'
+
+After do
+  Contracted.app and Contracted.app.unmount
+end
+
+Given /^the "([^"]*)" app is running$/ do |app_name|
+  app = Kernel.const_get(app_name).new
+  Contracted.mount app, '9898'
+end
+
+When /^an api client performs (GET|POST|PUT|DELETE) ([^\s]+)$/ do |method, url|
+  Contracted.app.send(method.downcase.to_sym, url, "", {})
+end
+
+When /^an api client performs (POST|PUT) ([^\s]+) with json body:$/ do |method, url, body|
+  Contracted.app.send(method.downcase.to_sym, url, body, {:content_type => 'application/json'})
+end
+
+Then /^the json response should look like:$/ do |response_body_string|
+  Contracted::ResponseDescription.new(response_body_string).should be_description_of Contracted.app.last
+end
+
+Then /^the json response body should look like:$/ do |response_body_string|
+  JsonDescriptionParser.new.parse(response_body_string).value.should == ActiveSupport::JSON.decode(Contracted.app.last.body)
+end

data/lib/contracted/http_description.treetop

@@ -0,0 +1,74 @@
+grammar HttpDescription
+  rule http
+    status_line headers new_line body
+  end
+
+  rule body
+    .*
+  end
+
+  rule headers
+    header* (wildcard new_line)? {
+      def values
+        elements.collect {|e| e.elements }.flatten.compact.select {|e| e.respond_to?(:value) }.map(&:value)
+      end
+    } 
+  end
+
+  rule wildcard
+    '...' {
+      def value
+        text_value
+      end
+    }
+  end
+
+  rule header
+    header_key ':' white_space header_value new_line {
+      def value
+        {header_key.text_value => header_value.text_value}
+      end
+    }
+  end
+
+  rule header_key
+    [^:]+
+  end
+
+  rule header_value
+    [^\n]+ 
+  end
+
+  rule status_line
+    'HTTP/' version space status space reason new_line
+  end
+
+  rule version
+    [0-9.]+
+  end
+
+  rule white_space
+    [\s]+
+  end
+
+  rule space
+    ' '
+  end
+
+  rule reason_word
+    [A-Z]+
+  end
+
+  rule reason
+    reason_word (space reason_word)*
+  end
+
+  rule status
+    [0-9] 3..3
+  end
+
+  rule new_line
+    [\n]
+  end
+end
+

data/lib/contracted/json.rb

@@ -0,0 +1,29 @@
+module Contracted
+  module Json
+    class Wildcard
+      def self.instance
+        @@instance ||= Wildcard.new
+      end
+
+      def == other
+        true
+      end
+    end
+
+    class Object
+      def initialize elements
+        @hash = elements.select {|e| e != Wildcard.instance }.inject({}) {|r, h| r.merge(h)}
+        @include = elements.include? Wildcard.instance
+      end
+
+      def == other
+        if @include
+          other.merge(@hash) == other
+        else
+          @hash == other
+        end
+      end
+    end
+  end
+end
+

data/lib/contracted/json_description.treetop

@@ -0,0 +1,128 @@
+require 'contracted/json'
+
+grammar JsonDescription
+  rule json
+    space json_value space {
+      def value
+        json_value.value
+      end
+    }
+  end
+
+  rule json_value
+    string / numeric / keyword / object / array / wildcard
+  end
+
+  rule string
+    '"' chars:char* '"' {
+      def value
+        chars.elements.map {|e| e.value }.join
+      end
+    }
+  end
+
+  rule wildcard
+    space '...' space {
+      def value
+        Contracted::Json::Wildcard.instance
+      end
+    }
+  end
+
+  rule char
+    !'"' ('\\\\' ( ( [nbfrt"] / '\\\\' / '/' ) / 'u' hex hex hex hex ) / !'\\\\' .) {
+      def value
+        if text_value[0..0] == '\\\\'
+          case c = text_value[1..1]
+          when /[nbfrt]/
+            {'n' => "\n", 'b' => "\b", 'f' => "\f", 'r' => "\r", 't' => "\t"}[c]
+          when 'u'
+            [text_value[2,4].to_i(16)].pack("U")
+          else
+            c
+          end
+        else
+          text_value
+        end
+      end
+    }
+  end
+
+  rule hex
+    [0-9a-fA-F]
+  end
+
+  rule numeric
+    exp / float / integer
+  end
+
+  rule exp
+    (float / integer) [eE] [+-]? unsigned_integer  { def value; text_value.to_f; end }
+  end
+
+  rule float
+    integer '.' [0-9]+  { def value; text_value.to_f; end }
+  end
+
+  rule integer
+    '-'? unsigned_integer  { def value; text_value.to_i; end }
+  end
+
+  rule unsigned_integer
+    ('0' / [1-9] [0-9]*)
+  end
+
+  rule keyword
+    ('true' / 'false' / 'null') {
+      def value
+        { 'true' => true, 'false' => false, 'null' => nil }[text_value]
+      end
+    }
+  end
+
+  rule object
+    '{' space object_elements:object_element* space '}' {
+      def value
+        Contracted::Json::Object.new(object_elements.elements.map {|p| p.value })
+      end
+    }
+  end
+
+  rule object_element
+    e:(pair / wildcard) (',' &object_element / !object_element) {
+      def value
+        e.value
+      end
+    }
+  end
+
+  rule pair
+    space string space ':' space json_value space {
+      def value
+        { string.value => json_value.value }
+      end
+    }
+  end
+
+  rule array
+    '[' space array_values:array_value* space ']' {
+      def value
+        array_values.elements.map {|e| e.value }
+      end
+    }
+  end
+
+  rule array_value
+    space json_value space (',' &array_value / !array_value) {
+      def value
+        json_value.value
+      end
+    }
+  end
+
+  rule space
+    [ \t\r\n]*
+  end
+
+end
+

data/lib/contracted/version.rb

@@ -0,0 +1,3 @@
+module Contracted
+  VERSION = "0.0.1"
+end

data/spec/contracted/application_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'contracted/application'
+
+describe "a rack app mounted with contracted.mount" do
+  before :all do @app = Contracted.mount(proc {|env| [200, {}, "body"]}, '9898') end
+
+  after :all do @app.unmount end
+  
+  subject { @app }
+
+  its(:host_and_port) { should == '0.0.0.0:9898' }
+
+  it "should be able to perform GET operations" do
+    @app.get('/', '', {}).should == 'body'
+  end
+end
+
+describe "a rack app mounted with contracted.mount that returns a non 200 series status code" do
+  it "should timeout after waiting 5 seconds" do
+    Thin::Server.stub(:new).and_return(mock(:server, :running? => false))
+
+    Timeout.timeout(6) do
+      proc do
+        Contracted.mount(proc {|env| [500, {}, "body"]}, '9898')
+      end.should raise_error(Timeout::Error)
+    end
+  end  
+end

data/spec/contracted/http_description_parser_spec.rb

@@ -0,0 +1,38 @@
+require 'polyglot'
+require 'treetop'
+require 'contracted/http_description'
+
+describe HttpDescriptionParser do
+  let(:description) { HttpDescriptionParser.new.parse(description_string) }
+
+  context "no headers as part of description" do
+    let(:description_string) { "HTTP/1.1 200 OK\n\n{'message': 'hello'}" }
+    
+    describe "description" do
+      subject { description }
+
+      its(:headers) { subject.values.should == [] }
+      its(:headers) { subject.text_value.should == '' }
+      its(:body) { subject.text_value.should == "{'message': 'hello'}" }
+    end
+
+    describe "status line" do
+      subject { description.status_line }
+
+      its(:status) { subject.text_value.should == "200" }
+      its(:version) { subject.text_value.should == "1.1" }
+      its(:reason) { subject.text_value.should == "OK" }
+    end
+  end
+
+  context "wildcard header in description" do
+    let(:description_string) { "HTTP/1.1 200 OK\nContent-Type: application/json\n...\n\n{'message': 'hello'}" }
+
+    describe "description" do
+      subject { description }
+
+      its(:headers) { subject.values.should == [{'Content-Type' => 'application/json'}, '...'] }
+    end
+  end
+end
+

data/spec/contracted/json_description_parser_spec.rb

@@ -0,0 +1,46 @@
+require 'active_support'
+require 'contracted'
+
+describe JsonDescriptionParser do
+  let(:parser) { JsonDescriptionParser.new } 
+  let(:description) { parser.parse(description_string) }
+
+  subject { description.value }
+
+  context "a standard json representation" do
+    let(:description_string) { '{"message": "hello"}' }
+    
+    describe "the description" do
+      it { should == json('{"message": "hello"}') }
+      it { should_not == json('{"message": "goodbye"}') }
+    end
+  end
+
+  context "with a key wildcard" do
+    let(:description_string) { '{"message": "hello", ...}' }
+
+    describe "the description" do
+      it { should == json('{"message": "hello"}')  }
+      it { should == json('{"message": "hello", "type": "greeting"}') }
+      it { should_not == json('{"message": "goodbye"}') }
+      it { should_not == json('{"type": "greeting"}') }
+    end
+  end
+
+  context "with a wildcard value" do
+    let(:description_string) { '{"message": ..., "type": "greeting" }' }
+
+    describe "the description" do
+      it { should == json('{"message": "hello", "type": "greeting" }') }
+      it { should == json('{"message": "goodbye", "type": "greeting" }') }
+      it { should_not == json('{"msg": "hello", "type": "greeting" }') }
+      it { should_not == json('{"message": "hello"}') }
+      it { should_not == json('{"type": "greeting"}') }
+    end
+  end
+
+  def json json_string
+    ActiveSupport::JSON.decode json_string
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/../features/support')
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+end

metadata

@@ -0,0 +1,198 @@
+--- !ruby/object:Gem::Specification 
+name: api-testing
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Andrew Kiellor
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-31 00:00:00 +10:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: thin
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: treetop
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: polyglot
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id007
+description: "\n    Contracted is a tool aimed at testing JSON API's.\n  "
+email: 
+- akiellor@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- README
+- Rakefile
+- contracted.gemspec
+- features/echo.feature
+- features/echo_body.feature
+- features/hello_world.feature
+- features/support/apps/echo.rb
+- features/support/apps/echo_body.rb
+- features/support/apps/hello_world.rb
+- features/support/env.rb
+- lib/contracted.rb
+- lib/contracted/application.rb
+- lib/contracted/cucumber.rb
+- lib/contracted/http_description.treetop
+- lib/contracted/json.rb
+- lib/contracted/json_description.treetop
+- lib/contracted/version.rb
+- spec/contracted/application_spec.rb
+- spec/contracted/http_description_parser_spec.rb
+- spec/contracted/json_description_parser_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: contracted
+rubygems_version: 1.4.2
+signing_key: 
+specification_version: 3
+summary: Contracted is a tool aimed at testing JSON API's.
+test_files: 
+- features/echo.feature
+- features/echo_body.feature
+- features/hello_world.feature
+- features/support/apps/echo.rb
+- features/support/apps/echo_body.rb
+- features/support/apps/hello_world.rb
+- features/support/env.rb
+- spec/contracted/application_spec.rb
+- spec/contracted/http_description_parser_spec.rb
+- spec/contracted/json_description_parser_spec.rb
+- spec/spec_helper.rb