contracts_api_test 0.0.1

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.swp
+*.swo
+.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in contracts.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,8 @@
+guard 'rspec', :cli => '--color --require spec_helper', :version => 2 do
+  watch(%r{^spec/contracts/.+_spec\.rb$})
+  watch(%r{^spec/json/.+_spec\.rb$})
+  watch(%r{^lib/contracts\.rb$})      { |m| "spec" }
+  watch(%r{^lib/json-generator\.rb$}) { |m| "spec" }
+  watch(%r{^lib/(.+)\.rb$})           { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')        { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 TODO: Write your name
+
+MIT License
+
+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

@@ -0,0 +1,117 @@
+# Contracts
+
+Contracts is a Ruby implementation of the [Consumer-Driven Contracts](http://martinfowler.com/articles/consumerDrivenContracts.html)
+pattern for evolving services. It's main features are:
+
+- A simple language for specifying a contract;
+- An automated way to validate that a producer meets it's consumers requirements;
+- An auto-generated stub to be used in the consumer's acceptance tests.
+
+It was developed in a micro-services environment, specifically a RESTful one, so expect it to be opinionated. Although
+there is enough functionality implemented to motivate us to open-source this, it is still a work in progress and under active
+development. Check the Constraints session for further information on what works and what doesn't.
+
+## Specifying Contracts
+
+A contract specifies a single message exchange between a consumer and a provider. In a RESTful world, this means
+an HTTP interaction, which is composed of two main parts: a request and a response.
+
+A request has the following attributes:
+
+- Method: the method of the HTTP request (e.g. GET, POST, PUT, DELETE);
+- Path: the relative path (without host) of the provider's endpoint;
+- Headers: headers sent in the HTTP request;
+- Params: any data or parameters of the HTTP request (e.g. query string for GET, body for POST)
+
+A response has the following attributes:
+
+- Status: the HTTP response status code (e.g. 200, 404, 500);
+- Headers: the HTTP response headers;
+- Body: a JSON Schema defining the expected structure of the HTTP response body.
+
+Contracts relies on a simple, JSON based language for defining contracts. Below is an example contract for a GET request
+to the /hello_world endpoint of a provider:
+
+    {
+      "request": {
+        "method": "GET",
+        "path": "/hello_world",
+        "headers": {
+          "Accept": "application/json"
+        },
+        "params": {}
+      },
+
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "description": "A simple response",
+          "type": "object",
+          "properties": {
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+
+The host address is intentionally left out of the request specification so that we can validate a contract against any provider.
+It also reinforces the fact that a contract defines the expectation of a consumer, and not the implementation of any specific provider.
+
+## Validating Contracts
+
+There are two ways to validate a contract against a provider: through a Rake task or programatically.
+
+### Rake Task
+
+Contracts includes a default Rake task. To use it, include it in your Rakefile:
+
+    require 'contracts/rake_task'
+
+Validating a contract against a provider is as simple as running:
+
+    $ rake contracts:validate[host,dir]  # Validates all contracts in a given directory against a given host
+
+It is recommended that you also include [colorize](https://github.com/fazibear/colorize) to get prettier, colorful output.
+
+### Programatically
+
+The easiest way to load a contract from a file and validate it against a host is by using the builder interface:
+
+    > contract = Contracts.build_from_file('/path/to/contract.json', 'http://dummyprovider.com')
+    > contract.validate
+
+## Auto-Generated Stubs
+
+Contracts provides an API to be used in the consumer's acceptance tests. It uses a custom JSON Schema parser and generator
+to generate a valid JSON document as the response body, and relies on [WebMock](https://github.com/bblimke/webmock)
+to stub any HTTP requests made by your application. Important: the JSON generator is in very early stages and does not work
+with the entire JSON Schema specification.
+
+First, register the contracts that are going to be used in the acceptance tests suite:
+
+    contract = Contracts.build_from_file('/path/to/contract.json', 'http://dummyprovider.com')
+    Contracts.register('my_contract', contract)
+
+Then, in the setup phase of the test, specify which contracts will be used for that test:
+
+    Contracts.use('my_contract')
+
+If default values are not specified in the contract's response body, a default value will be automatically generated. It is possible
+to overwrite those values, however, by passing a second argument:
+
+    Contracts.use('my_contract', :value => 'new value')
+
+The values are merged using [hash-deep-merge](https://github.com/Offirmo/hash-deep-merge).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+if defined?(RSpec)
+  RSpec::Core::RakeTask.new('spec')
+  task :default => :spec
+end

data/TODO.md

@@ -0,0 +1,19 @@
+# TODO
+
+## Nice to have
+
+- Cucumber Tests as docs (see https://relishapp.com/cucumber/cucumber/docs/);
+- Fake Server (sinatra app generating fake responses based on the contracts);
+- Optional "require" format for JSON Schema: # 'required': ['id', 'categorias', 'titulo', ...];
+- Contract variables for easy writing. Such as: 'path': '/member/{id}';
+- Add JSHint rake task to validate contracts syntax;
+- Pretty output for hash difference (using something like [hashdiff](https://github.com/liufengyun/hashdiff)).
+- A default header in the response marking the response as "mocked"
+- Parameter matcher should use an idea of "subset" instead of matching all the parameters
+- 'default' value to be used when it is present with an array of types
+- Support 'null' attribute type
+- Validate contract structure in a rake task. Then assume all contracts are valid.
+
+## Assumptions
+
+- JSON Schema references are stored in the 'definitions' attribute, in the schema's root element.

data/contracts.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'contracts/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "contracts_api_test"
+  gem.version       = Contracts::VERSION
+  gem.authors       = ["Abril Midia", "ThoughtWorks"]
+  gem.email         = ["vejasp-dev@abril.com.br", "abril_vejasp_dev@thoughtworks.com"]
+  gem.description   = %q{Consumer-Driven Contracts}
+  gem.summary       = %q{Consumer-Driven Contracts Gem}
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "webmock"
+  gem.add_dependency "json"
+  gem.add_dependency "json-schema"
+  gem.add_dependency "hash-deep-merge"
+  gem.add_dependency "httparty"
+  gem.add_dependency "addressable"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "guard-rspec"
+end

data/lib/contracts.rb

@@ -0,0 +1,46 @@
+require "contracts/version"
+
+require "httparty"
+require "hash_deep_merge"
+require "json"
+require "json-schema"
+require "json-generator"
+require "webmock"
+require "ostruct"
+
+require "contracts/extensions"
+require "contracts/request"
+require "contracts/response_adapter"
+require "contracts/response"
+require "contracts/instantiated_contract"
+require "contracts/contract"
+
+module Contracts
+  def self.build_from_file(contract_path, host)
+    definition = JSON.parse(File.read(contract_path))
+    request = Request.new(host, definition["request"])
+    response = Response.new(definition["response"])
+    Contract.new(request, response)
+  end
+
+  def self.register(name, contract)
+    raise ArgumentError, "contract \" #{name}\" has already been registered" if registered.has_key?(name)
+    registered[name] = contract
+  end
+
+  def self.use(contract_name, values = nil, path = nil)
+    raise ArgumentError, "contract \"#{contract_name}\" not found" unless registered.has_key?(contract_name)
+    instantiated_contract = registered[contract_name].instantiate(values)
+    instantiated_contract.request.path = path unless path.nil?
+    instantiated_contract.stub!
+    instantiated_contract
+  end
+
+  def self.registered
+    @registered ||= {}
+  end
+
+  def self.unregister_all!
+    @registered = {}
+  end
+end

data/lib/contracts/contract.rb

@@ -0,0 +1,18 @@
+module Contracts
+  class Contract
+    def initialize(request, response)
+      @request = request
+      @response = response
+    end
+
+    def instantiate(values = nil)
+      instantiated_contract = InstantiatedContract.new(@request, @response.instantiate)
+      instantiated_contract.replace!(values) unless values.nil?
+      instantiated_contract
+    end
+
+    def validate
+      @response.validate(@request.execute)
+    end
+  end
+end

data/lib/contracts/extensions.rb

@@ -0,0 +1,18 @@
+module Contracts
+  module Extensions
+    module HashSubsetOf
+      def subset_of?(other)
+        (self.to_a - other.to_a).empty?
+      end
+
+      def normalize_keys
+        self.inject({}) do |normalized, (key, value)|
+          normalized[key.to_s.downcase] = value
+          normalized
+        end
+      end
+    end
+  end
+end
+
+Hash.send(:include, Contracts::Extensions::HashSubsetOf)

data/lib/contracts/instantiated_contract.rb

@@ -0,0 +1,63 @@
+module Contracts
+  class InstantiatedContract
+    attr_accessor :request
+    attr_reader :response_body
+
+    def initialize(request, response)
+      @request = request
+      @response = response
+      @response_body = response.body
+    end
+
+    def request_path
+      @request.absolute_uri
+    end
+
+    def request_uri
+      @request.full_uri
+    end
+
+    def replace!(values)
+      if @response_body.respond_to?(:normalize_keys)
+        @response_body = @response_body.normalize_keys.deep_merge(values.normalize_keys)
+      else
+        @response_body = values
+      end
+    end
+
+    def stub!
+      WebMock.stub_request(@request.method, "#{@request.host}#{@request.path}").
+        with(request_details).
+        to_return({
+          :status => @response.status,
+          :headers => @response.headers,
+          :body => format_body(@response_body)
+        })
+    end
+
+    private
+
+    def format_body(body)
+      if body.is_a?(Hash) or body.is_a?(Array)
+        body.to_json
+      else
+        body
+      end
+    end
+
+    def request_details
+      details = {}
+      unless @request.params.empty?
+        details[webmock_params_key] = @request.params
+      end
+      unless @request.headers.empty?
+        details[:headers] = @request.headers
+      end
+      details
+    end
+
+    def webmock_params_key
+      @request.method == :get ? :query : :body
+    end
+  end
+end

data/lib/contracts/rake_task.rb

@@ -0,0 +1,75 @@
+require 'contracts'
+
+unless String.respond_to?(:colors)
+  class String
+    def colorize(*args)
+      self
+    end
+  end
+end
+
+module Contracts
+  class RakeTask
+    include Rake::DSL
+
+    def initialize
+      @exit_with_error = false
+    end
+
+    def install
+      desc "Tasks for contracts gem"
+      namespace :contracts do
+        validate_task
+      end
+    end
+
+    def validate_task
+      desc "Validates all contracts in a given directory against a given host"
+      task :validate, :host, :dir do |t, args|
+        if args.to_a.size < 2
+          fail "USAGE: rake contracts:validate[<host>, <contract_dir>]".colorize(:yellow)
+        end
+
+        validate_contracts(args[:host], args[:dir])
+      end
+    end
+
+    def validate_contracts(host, dir)
+      WebMock.allow_net_connect!
+
+      contracts = Dir[File.join(dir, '*.json')]
+      if contracts.empty?
+        fail "No contracts found in directory #{dir}".colorize(:yellow)
+      end
+
+      puts "Validating contracts in directory #{dir} against host #{host}\n\n"
+
+      total_failed = 0
+      contracts.each do |contract_file|
+        print "#{contract_file.split('/').last}:"
+        contract = Contracts.build_from_file(contract_file, host)
+        errors = contract.validate
+
+        if errors.empty?
+          puts " OK!".colorize(:green)
+        else
+          @exit_with_error = true
+          total_failed += 1
+          puts " FAILED!".colorize(:red)
+          errors.each do |error|
+            puts "\t* #{error}".colorize(:light_red)
+          end
+          puts ""
+        end
+      end
+
+      if @exit_with_error
+        fail "#{total_failed} of #{contracts.size} failed. Check output for detailed error messages.".colorize(:red)
+      else
+        puts "#{contracts.size} valid contract#{contracts.size > 1 ? 's' : nil}".colorize(:green)
+      end
+    end
+  end
+end
+
+Contracts::RakeTask.new.install