rspec_api_blueprint_matchers 0.1.2

data/lib/rspec_apib/parser.rb

@@ -0,0 +1,79 @@
+require "rspec_apib/transcluder"
+require "rspec_apib/extractors"
+require "rspec_apib/elements"
+require "open3"
+require "json"
+module RSpecApib
+  class Parser
+
+    def initialize(transcluder: Transcluder, base_element: Element::Base)
+      self.transcluder = transcluder
+      self.base_element = base_element
+    end
+
+    def parse_file(file)
+      self.parsed_file = call_parser(file)
+      document, index = parse_document
+      self.document = document
+      self.index = index
+      document
+    end
+
+    def resources
+      index[Element::Resource]
+    end
+
+    def categories
+      index[Element::Category]
+    end
+
+    def copies
+      index[Element::Copy]
+    end
+
+    def transitions
+      index[Element::Transition]
+    end
+
+    def http_transactions
+      index[Element::HttpTransaction]
+    end
+
+    def http_requests
+      index[Element::HttpRequest]
+    end
+
+    def http_responses
+      index[Element::HttpResponse]
+    end
+
+    def asset
+      index[Element::Asset]
+    end
+
+    private
+
+    attr_accessor :transcluder, :parsed_file, :document, :base_element, :index
+
+    def parse_document
+      base_element.parse_root(parsed_file)
+    end
+
+    def bin_path
+      "drafter"
+    end
+
+    def call_parser(file)
+      op = nil
+      Open3.popen3("#{bin_path} -f json") do |stdin, stdout, stderr, wait_thr|
+        transcluder.each_line(file) do |line|
+          stdin.write line
+        end
+        stdin.close
+        op = stdout.read
+        exit_status = wait_thr.value
+      end
+      JSON.parse op
+    end
+  end
+end

data/lib/rspec_apib/request.rb

@@ -0,0 +1,44 @@
+module RSpecApib
+  class Request
+    def initialize(request)
+      self.raw_request = request
+    end
+
+    def request_method
+      raw_request.method
+    end
+
+    def url
+      raw_request.url
+    end
+
+    def validate_body_with_json_schema?
+      request_method != :get && is_json?
+    end
+
+    # The request body
+    # @return [String] The request body - always as a string
+    def body
+      raw_request.body
+    end
+
+    def content_type
+      headers["Content-Type"]
+    end
+
+    def headers
+      raw_request.request_headers
+    end
+
+
+    private
+
+    attr_accessor :raw_request
+
+    def is_json?
+      content_type =~ /json/
+    end
+
+
+  end
+end

data/lib/rspec_apib/response.rb

@@ -0,0 +1,39 @@
+require "json"
+module RSpecApib
+  class Response
+    def initialize(response)
+      self.raw_response = response
+    end
+
+    def status
+      raw_response.status.to_s
+    end
+
+    # The response body
+    # @return [String] The response body - always as a string
+    def body
+      JSON.generate raw_response.body
+    end
+
+    def validate_body_with_json_schema?
+      is_json?
+    end
+
+    def content_type
+      headers["Content-Type"]
+    end
+
+    def headers
+      raw_response.response_headers
+    end
+
+
+    private
+
+    attr_accessor :raw_response
+
+    def is_json?
+      content_type=~/json/
+    end
+  end
+end

data/lib/rspec_apib/rspec.rb

@@ -0,0 +1,40 @@
+require "rspec/matchers"
+require "rspec_apib/transaction_validator"
+require "rspec_apib/transaction_coverage_validator"
+RSpec::Matchers.define :match_api_docs_for do |path:, request_method:, content_type:, parser: RSpecApib.config.default_parser|
+  error_messages = []
+  match do |actual|
+    if actual.nil?
+      error_messages << "Expected the transaction to match api docs for #{method}:#{path} but it was nil"
+      false
+    elsif !parser.is_a?(RSpecApib::Parser)
+      error_messages << "Expected the transaction to match api docs for #{method}:#{path} but the provided parser was invalid"
+      false
+    else
+      ::RSpecApib::TransactionValidator.new(path: path, request_method: request_method, content_type: content_type, parser: parser).validate(request: ::RSpecApib.normalize_request(actual.request), response: ::RSpecApib.normalize_response(actual.response), error_messages: error_messages)
+    end
+
+  end
+
+  failure_message do |actual|
+    error_messages.join("\n")
+  end
+end
+
+RSpec::Matchers.define :have_covered_all_api_documentation do | parser: RSpecApib.config.default_parser |
+  error_messages = []
+  Transaction = Struct.new(:request, :response)
+  match do |actual|
+    error_messages << "No API calls were made" if actual.empty?
+
+    normalized_transactions = actual.map do |tx|
+      Transaction.new(RSpecApib.normalize_request(tx.request), RSpecApib.normalize_response(tx.response))
+    end
+    ::RSpecApib::TransactionCoverageValidator.new(parser: parser).validate(transactions: normalized_transactions, error_messages: error_messages)
+
+  end
+
+  failure_message do |actual|
+    error_messages.join("\n")
+  end
+end

data/lib/rspec_apib/transaction_coverage_report.rb

@@ -0,0 +1,36 @@
+module RSpecApib
+  class TransactionCoverageReport
+    def initialize(transactions:, parser: RSpecApib.config.default_parser)
+      self.transactions = transactions
+      self.parser = parser
+    end
+
+    def uncovered_transactions
+      documented_transaction_tracker = parser.http_transactions.inject({}) do |acc, t|
+        acc[t]=false
+        acc
+      end
+      transactions.each do |requested_tx|
+        matching_transactions = documented_transaction_tracker.keys.each do |dtx|
+          documented_transaction_tracker[dtx] = true if dtx.matches?(requested_tx.request, requested_tx.response)
+        end
+      end
+      documented_transaction_tracker.reject {|k,v| v}.keys
+    end
+
+    def undocumented_transactions
+      results = []
+      transactions.each do |requested_tx|
+        match = parser.http_transactions.find do |doc_txn|
+          doc_txn.matches?(requested_tx.request, requested_tx.response)
+        end
+        results << requested_tx if match.nil?
+      end
+      results
+    end
+
+    private
+
+    attr_accessor :transactions, :parser
+  end
+end

data/lib/rspec_apib/transaction_coverage_validator.rb

@@ -0,0 +1,49 @@
+require "rspec_apib/transaction_coverage_report"
+module RSpecApib
+  class TransactionCoverageValidator
+    def initialize(parser: RSpecApib.config.default_parser)
+      self.parser = parser
+    end
+
+    def validate(transactions:, error_messages:)
+      errors = []
+      reporter = TransactionCoverageReport.new(transactions: transactions, parser: parser)
+      uncovered = reporter.uncovered_transactions
+      if uncovered.length > 0
+        uncovered.each do |tx|
+          errors << self.class.uncovered_tx_message(tx)
+        end
+      end
+      undocumented = reporter.undocumented_transactions
+      if undocumented.length > 0
+        undocumented.each do |tx|
+          errors << self.class.undocumented_tx_message(tx)
+        end
+      end
+      if errors.length > 0
+        error_messages.concat errors
+        error_messages << "Coverage Summary: #{uncovered.length} uncovered and #{undocumented.length} undocumented transactions"
+        false
+      else
+        true
+      end
+    end
+
+    private
+
+    attr_accessor :parser
+
+    def matched_transaction(request:, response:)
+      parser.http_transactions.find { |t| t.matches?(request, response, options: {validate_request_schema: :never, validate_response_schema: :never}) }
+    end
+
+    def self.uncovered_tx_message(tx)
+      "#{tx.request.request_method.to_s.upcase} #{tx.request.url} with response (#{tx.response.content_type}) status #{tx.response.status}- Not covered"
+    end
+
+    def self.undocumented_tx_message(tx)
+      "#{tx.request.request_method.upcase} #{tx.request.url} with response (#{tx.response.content_type}) status #{tx.response.status} - Not documented"
+    end
+
+  end
+end

data/lib/rspec_apib/transaction_validator.rb

@@ -0,0 +1,44 @@
+module RSpecApib
+  class TransactionValidator
+    # validate_request_schema can be :always, :never, :when_defined
+    def initialize(path:, request_method:, content_type:, validate_request_schema: :always, validate_response_schema: :always, parser: RSpecApib.config.default_parser)
+      self.path = path
+      self.request_method = request_method
+      self.content_type = content_type
+      self.parser = parser
+      self.validate_request_schema = validate_request_schema
+      self.validate_response_schema = validate_response_schema
+    end
+
+    def validate(request:, response:, error_messages:, options: {})
+      candidates = transaction_candidates(request: request, response: response, options: options)
+      results = candidates.map do |candidate|
+        candidate.validate_schema(request, response, validate_request_schema: validate_request_schema, validate_response_schema: validate_response_schema)
+      end
+
+      if results.empty?
+        error_messages << "No candidates for #{request.inspect} with response #{response.inspect}"
+        return false
+      end
+
+      return true unless results.flatten.find {|r| !r[:request_errors].empty? || !r[:response_errors].empty?}
+      results.each do |result|
+        error_messages << "The request validation failed - reasons #{result[:request_errors].join("\n")}" unless result[:request_errors].empty?
+        error_messages << "The response validation failed - reasons #{result[:response_errors].join("\n")}" unless result[:response_errors].empty?
+      end
+      false
+    end
+
+    private
+
+    def transaction_candidates(request:, response:, options: {})
+      transactions = parser.http_transactions.select do |t|
+        t.potential_match?(path: path, request_method: request_method, content_type: content_type)
+      end
+      transactions.select { |t| t.matches?(request, response, options: options) }
+    end
+
+    attr_accessor :path, :request_method, :content_type, :parser, :validate_request_schema, :validate_response_schema
+
+  end
+end

data/lib/rspec_apib/transcluder.rb

@@ -0,0 +1,30 @@
+module RSpecApib::Transcluder
+  REGEX = /:\[[^\]]*\]\(([^\)]*)\)/
+  def self.each_line(file, &block)
+    File.readlines(file, encoding: "UTF-8").each do |line|
+      if needs_transclude?(line)
+        transclude(file, line, &block)
+      else
+        yield line
+      end
+    end
+  end
+
+  def self.needs_transclude?(line)
+    line =~ REGEX
+  end
+
+  def self.transclude(file, line, &block)
+    line.gsub!(REGEX) do |match|
+      transclude_file = $1
+      unless transclude_file =~ /^\//
+        transclude_file = File.expand_path(transclude_file, File.dirname(file))
+      end
+      each_line(transclude_file, &block)
+      ""
+    end
+    yield line
+  end
+
+
+end

data/lib/rspec_apib/version.rb

@@ -0,0 +1,3 @@
+module RSpecApib
+  VERSION = "0.1.2"
+end

data/lib/transcluder.rb

@@ -0,0 +1,3 @@
+module RSpecApib::Transcluder
+
+end

data/rspec_api_blueprint_matchers.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rspec_apib/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rspec_api_blueprint_matchers"
+  spec.version       = RSpecApib::VERSION
+  spec.authors       = ["Shift Commerce Ltd"]
+  spec.email         = ["team@shiftcommerce.com"]
+
+  spec.summary       = %q{API Blueprint Tools For RSpec}
+  spec.description   = %q{API Blueprint Tools For RSpec - Matching http transactions against an API Blueprint document to ensure the API that you are implementing matches the API that is documented which your clients will expect to be the case.}
+  spec.homepage      = "https://github.com/shiftcommerce/rspec_api_blueprint_matchers"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  spec.add_dependency "addressable", ">= 2.5.0"
+  spec.add_dependency "json-schema", ">= 2.8.0"
+  spec.add_dependency "rspec", ">= 3.0"
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

metadata

@@ -0,0 +1,182 @@
+--- !ruby/object:Gem::Specification
+name: rspec_api_blueprint_matchers
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Shift Commerce Ltd
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: API Blueprint Tools For RSpec - Matching http transactions against an
+  API Blueprint document to ensure the API that you are implementing matches the API
+  that is documented which your clients will expect to be the case.
+email:
+- team@shiftcommerce.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Dockerfile
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- codeship-services.yml
+- codeship-steps.yml
+- lib/rspec_api_blueprint_matchers.rb
+- lib/rspec_apib.rb
+- lib/rspec_apib/config.rb
+- lib/rspec_apib/elements.rb
+- lib/rspec_apib/elements/annotation.rb
+- lib/rspec_apib/elements/array.rb
+- lib/rspec_apib/elements/asset.rb
+- lib/rspec_apib/elements/base.rb
+- lib/rspec_apib/elements/category.rb
+- lib/rspec_apib/elements/copy.rb
+- lib/rspec_apib/elements/data_structure.rb
+- lib/rspec_apib/elements/href_variables.rb
+- lib/rspec_apib/elements/http_headers.rb
+- lib/rspec_apib/elements/http_message_payload.rb
+- lib/rspec_apib/elements/http_request.rb
+- lib/rspec_apib/elements/http_response.rb
+- lib/rspec_apib/elements/http_transaction.rb
+- lib/rspec_apib/elements/member.rb
+- lib/rspec_apib/elements/object.rb
+- lib/rspec_apib/elements/parse_result.rb
+- lib/rspec_apib/elements/resource.rb
+- lib/rspec_apib/elements/source_map.rb
+- lib/rspec_apib/elements/string.rb
+- lib/rspec_apib/elements/templated_href.rb
+- lib/rspec_apib/elements/transition.rb
+- lib/rspec_apib/engine.rb
+- lib/rspec_apib/extractors.rb
+- lib/rspec_apib/extractors/http_transaction.rb
+- lib/rspec_apib/extractors/resource.rb
+- lib/rspec_apib/parser.rb
+- lib/rspec_apib/request.rb
+- lib/rspec_apib/response.rb
+- lib/rspec_apib/rspec.rb
+- lib/rspec_apib/transaction_coverage_report.rb
+- lib/rspec_apib/transaction_coverage_validator.rb
+- lib/rspec_apib/transaction_validator.rb
+- lib/rspec_apib/transcluder.rb
+- lib/rspec_apib/version.rb
+- lib/transcluder.rb
+- rspec_api_blueprint_matchers.gemspec
+homepage: https://github.com/shiftcommerce/rspec_api_blueprint_matchers
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: API Blueprint Tools For RSpec
+test_files: []