Add DocumentMatcher

This matcher allows expectations to be checked on the documentation
for an exposure.

Author: Tim Perkins

README.markdown

@@ -27,6 +27,9 @@ it { is_expected.to represent(:dog).using(PetEntity) }
 it { is_expected.to represent(:cat).as(:kitty).using(PetEntity) }
 
 it { is_expected.to represent(:name).with_documentation(type: String) }
+
+it { is_expected.to document(:name).with(type: String, desc: 'Name of the person') }
+it { is_expected.to document(:name).type(String).desc('Name of the person') }
 ```
 
 ## Support for Rspec 2.0.0

lib/grape_entity_matchers.rb

@@ -1,3 +1,4 @@
 require 'grape_entity_matchers/version'
 require 'grape_entity_matchers/represent_matcher'
+require 'grape_entity_matchers/document_matcher'
 require 'grape_entity_matchers/rspec_integration'

lib/grape_entity_matchers/document_matcher.rb

@@ -0,0 +1,104 @@
+module GrapeEntityMatchers
+  module DocumentMatcher
+    def document(documentable)
+      DocumentMatcher.new(documentable)
+    end
+
+    class DocumentMatcher
+      def initialize(documentable)
+        @expected_documentable = documentable
+      end
+
+      def description
+        "ensure that #{@subject} documents the #{@expected_documentable} exposure"
+      end
+
+      def matches?(subject)
+        @subject = subject
+
+        has_documentation? && verify_documentation
+      end
+
+      def type(type_value)
+        @type = type_value
+        self
+      end
+
+      def required(required_value)
+        @required = required_value
+        self
+      end
+
+      def desc(desc_value)
+        @desc = desc_value
+        self
+      end
+
+      def default(default_value)
+        @default = default_value
+        self
+      end
+
+      def values(values)
+        @values = values
+        self
+      end
+
+      def with(documentation)
+        @documentation = documentation
+        self
+      end
+
+      def failure_message
+        "#{@subject} didn't document #{@expected_documentable} "\
+        "as expected: #{expected_documentation}, got #{match_documentation}"
+      end
+
+      def failure_message_when_negated
+        message = "didn't expect #{@subject} to document #{@expected_documentable}"
+        message << " with: #{expected_documentation}" unless expected_documentation.empty?
+        message << ", got: #{actual_documentation}"
+      end
+
+      private
+
+      def expected_documentation
+        @documentation ||
+            {
+              type: @type,
+              desc: @desc,
+              required: @required,
+              default: @default,
+              values: @values
+            }.compact
+      end
+
+      def match_documentation
+        if has_documentation?
+          exposure[:documentation].slice(*expected_documentation.keys)
+        end
+      end
+
+      def actual_documentation
+        exposure.try(:[], :documentation)
+      end
+
+      def has_documentation?
+        @subject.exposures.has_key?(@expected_documentable) &&
+            exposure[:documentation]
+      end
+
+      def exposure
+        @subject.exposures[@expected_documentable]
+      end
+
+      def verify_documentation
+        if @documentation
+          @documentation == exposure[:documentation]
+        else
+          expected_documentation == match_documentation
+        end
+      end
+    end
+  end
+end

lib/grape_entity_matchers/rspec_integration.rb

@@ -3,4 +3,6 @@
 RSpec.configure do |config|
   require 'grape_entity_matchers/represent_matcher'
   config.include GrapeEntityMatchers::RepresentMatcher
-end
+  require 'grape_entity_matchers/document_matcher'
+  config.include GrapeEntityMatchers::DocumentMatcher
+end

spec/grape_entity_matchers/document_matcher_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+require 'grape_entity'
+
+describe GrapeEntityMatchers::DocumentMatcher do
+  let(:documentation) do
+    {
+      type: String,
+      desc: 'Some string',
+      default: 'xyz',
+      required: false,
+      values: ['abc', 'xyz']
+    }
+  end
+  before(:all) do
+    class TestEntity < Grape::Entity
+      expose :str, documentation: {
+        type: String,
+        desc: 'Some string',
+        default: 'xyz',
+        required: false,
+        values: ['abc', 'xyz']
+      }
+      expose :no_doc
+    end
+  end
+
+  subject(:entity) { TestEntity }
+
+  context "ensure that the exposure matches the documentation" do
+    it { is_expected.to document(:str).with(documentation) }
+  end
+
+  context "ensure individual keys of documentation" do
+    it { is_expected.to document(:str).type(String) }
+    it { is_expected.not_to document(:str).type(Fixnum) }
+
+    it { is_expected.to document(:str).desc('Some string') }
+    it { is_expected.not_to document(:str).desc('Some other string') }
+
+    it { is_expected.to document(:str).default('xyz') }
+    it { is_expected.not_to document(:str).default('abc') }
+
+    it { is_expected.to document(:str).required(false) }
+    it { is_expected.not_to document(:str).required(true) }
+
+    it { is_expected.to document(:str).values(['abc', 'xyz']) }
+    it { is_expected.not_to document(:str).values(['foo', 'bar']) }
+  end
+
+  context "ensure a combination of keys of documentation" do
+    it { is_expected.to document(:str).type(String).desc('Some string') }
+  end
+
+  context "ensure that an exposure is not documented" do
+    it { is_expected.to_not document(:no_doc) }
+  end
+
+  context "ensure that a specific documentation is not used" do
+    it { is_expected.to_not document(:str).with(type: String, required: false) }
+  end
+end