test_assistant 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bfe1610c486eff9f3ad4683799bcfc91c861c7f5
-  data.tar.gz: 8bc9686c28979433d3e17fed24f983dc72fc104c
+  metadata.gz: 9311d43bef33250abf4b13c6f10cfa03df96f8ed
+  data.tar.gz: 1fb3475a4bed626f4a5744724c340ac8702888b4
 SHA512:
-  metadata.gz: ca6bb85a6d11ebda0f0d5ac40695a7dee8fd3d2863b3c2d13f5f9c2667c05ec95d09d61efe9a08d3100f847e8ee73ef355dc0e7e0b83bc861cfb04a6dea085f0
-  data.tar.gz: dc90720582c1a364ad13a17e4aa65e578616e71e0a6dcae9ed9d00450d9aba8bc4b1a461880872a1fbdc24c489285c5afb34d15969387f2dc503346e196db9a0
+  metadata.gz: '00185e2575b08c763500c145db50601143a73da0fa669c40eb70f7cc4e9156905c9b49ab13b3d4c6db8c7fe27fb82b60d9bd1d7a87df21c9472034e83c893609'
+  data.tar.gz: e76955c99b919c852f83de86ebb6ee173ac41acc8dbff90b8100d5784f0847fc35f09c4f03a0b3d61ee672a479aa51ba2f1f37f5cf52d8ee05e4a3a723289eb9

data/.yardopts

@@ -0,0 +1 @@
+- README LICENSE

data/lib/test_assistant/configuration.rb

@@ -3,15 +3,56 @@ module TestAssistant
   autoload :Email, 'test_assistant/email/helpers'
   autoload :FailureReporter, 'test_assistant/failure_reporter'
 
+  # Class that provides configuration methods to control what parts of Test Assistant
+  # are included in an RSpec test suite. Instances of this class are managed internally
+  # by Test Assistant when using the TestAssistant#configure method.
+  #
+  # @see TestAssistant#configure
   class Configuration
+    # Creates a new TestAssistant::Configuration object - called internally by Test
+    # Assistant
+    #
+    # @param rspec_config RSpec configuration object, available in the block passed to
+    #   RSpec.configure
+    # @return [TestAssistant::Configuration] new configuration object
     def initialize(rspec_config)
       @rspec_config = rspec_config
     end
 
+    # Configures RSpec to include the JSON helpers provided by Test Assistant in the
+    # the test suite's scope
+    #
+    # @see TestAssistant::Json::Helpers
+    # @see RSpec::Core::Configuration#include
+    #
+    # @param [Hash] options RSpec::Core::Configuration#include options
+    # @return void
+    #
+    # @example Include JSON helpers in your RSpec test suite
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.include_json_helpers
+    #     end
+    #   end
     def include_json_helpers(options = {})
       @rspec_config.include Json::Helpers, options
     end
 
+    # Configures RSpec to include the email helpers provided by Test Assistant in the
+    # the test suite's scope and to clear the list of emails sent after each test
+    #
+    # @see TestAssistant::Email::Helpers
+    # @see RSpec::Core::Configuration#include
+    #
+    # @param [Hash] options RSpec::Core::Configuration#include options
+    # @return void
+    #
+    # @example Include Email helpers in your RSpec test suite
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.include_email_helpers
+    #     end
+    #   end
     def include_email_helpers(options = {})
       @rspec_config.include Email::Helpers, options
 
@@ -21,9 +62,45 @@ module TestAssistant
       end
     end
 
+    # Configures under what circumstances a failing test should open a failure report
+    # detailing the last HTTP request and response in a browser
+    #
+    # @param [Hash{Symbol => Symbol,String,Boolean}] options filters for when a test
+    #   failure should show a failure report
+    # @option options [Symbol, Boolean] :tag The tag tests must be given in order to
+    #   show a failure report. If false, no tag is needed and all tests that
+    #   fail (and meet any other filter options provided) will show a failure report.
+    # @option options [Symbol, Boolean] :type The RSpec test type for which a failure
+    #   will show a failure report. If false, tests of any type that fail (and
+    #   meet any other filter options provided) will show a failure report.
+    # @return void
+    #
+    # @example Show a failure report for failing tests tagged with :focus
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.render_failed_response(tag: :focus)
+    #     end
+    #   end
+    #
+    # @example Show a failure report for all failing tests
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.render_failed_response(tag: false)
+    #     end
+    #   end
+    #
+    # @example Show a failure report for all failing controller tests
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.render_failed_response(type: :controller)
+    #     end
+    #   end
+    #
+    # @see TestAssistant::FailureReporter#report
     def render_failed_responses(options = {})
       tag_filter = options[:tag]
       no_tag_filter = !tag_filter
+
       type_filter = options[:type]
       no_type_filter = !type_filter
 
@@ -38,6 +115,38 @@ module TestAssistant
       end
     end
 
+    # Configures under what circumstances a failing test should open an debugger session
+    #
+    # @param [Hash{Symbol => Symbol,String,Boolean}] options filters for when a test
+    #   failure should open a debugger session
+    # @option options [Symbol, Boolean] :tag The tag tests must be given in order to
+    #   open the debugger. If false, no tag is needed and any test that fails (and
+    #   meets any other filter options provided) will open the debugger.
+    # @option options [Symbol, Boolean] :type The type of test that should open the
+    #   debugger if it fails. If false, no tag is needed and any test that fails (and
+    #   meets any other filter options provided) will open the debugger.
+    # @return void
+    #
+    # @example Open the debugger for failing tests tagged with :focus
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.debug_failed_responses(tag: :focus)
+    #     end
+    #   end
+    #
+    # @example Open the debugger for all failing tests
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.debug_failed_responses(tag: false)
+    #     end
+    #   end
+    #
+    # @example Open the debugger for all failing controller tests
+    #   RSpec.configure do |config|
+    #     TestAssistant.configure(config) do |ta_config|
+    #       ta_config.debug_failed_responses(type: :controller)
+    #     end
+    #   end
     def debug_failed_responses(options = {})
       tag_filter = options.fetch(:tag, :debugger)
       type_filter = options[:type]

data/lib/test_assistant/email/expectation.rb

@@ -1,14 +1,22 @@
 require 'capybara/rspec'
 
 module TestAssistant::Email
+  # Backing class for have_been_sent declarative syntax for specifying email
+  # expectations. Provides ability to assert emails have been sent in a given test
+  # that match particular attribute values, such as sender, receiver or contents.
+  #
+  # Expected to be used as part of a RSpec test suite and with
+  # TestAssistant::Email::Helpers#email.
+  #
+  # Has two major components:
+  # - A Builder or chainable methods syntax for constructing arbitrarily specific
+  #   expectations
+  # - An implementation of the same interface as RSpec custom matcher classes to
+  #   allow evaluating those expectations those expectations
+  #
+  # @see TestAssistant::Email::Helpers#email
+  # @see TestAssistant::Email::Helpers#have_been_sent
   class Expectation
-
-    def initialize
-      @expectations = {}
-      @failure_message = 'Expected email to be sent'
-      @and_scope = nil
-    end
-
     MATCHERS = {
         to: :to,
         from: :from,
@@ -18,22 +26,46 @@ module TestAssistant::Email
             actual: ->(_, email){ email.text}
         },
         matching_selector: {
-            match: ->(_, email, value){ value.all?{|text| email.has_selector?(text) }},
+            match: ->(_, email, value){ value.all?{|selector| email.has_selector?(selector) }},
             actual: ->(_, email){ email.native },
             actual_name: :with_body
         },
         with_link: {
-            match: ->(_, email, value){ value.all?{|value| email.has_selector?("a[href='#{value}']") }},
+            match: ->(_, email, value){ value.all?{|url| email.has_selector?("a[href='#{url}']") }},
             actual: ->(_, email){ email.native },
             actual_name: :with_body
         },
         with_image: {
-            match: ->(_, email, value){ value.all?{|value| email.has_selector?("img[src='#{value}']") }},
+            match: ->(_, email, value){ value.all?{|url| email.has_selector?("img[src='#{url}']") }},
             actual: ->(_, email){ email.native },
             actual_name: :with_body
         }
     }
 
+    # Creates a new TestAssistant::Email::Expectation object
+    #
+    # @return [TestAssistant::Email::Expectation] new expectation object
+    def initialize
+      @expectations = {}
+      @failure_message = 'Expected email to be sent'
+      @and_scope = nil
+    end
+
+    #
+    # Expectation creation methods
+    #
+
+    # Allows chaining two assertions on the same email attribute together without having
+    # to repeat the same method. Intended as syntactical sugar only and is functionally
+    # equivalent to repeating the method.
+    #
+    # @example Asserting an email was sent to two email addresses
+    #   expect(email).to have_been_sent.to('user1@email.com').and('user2@email.com')
+    #
+    # @param [Array] arguments parameters to pass to whatever assertion is being
+    #   extended.
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def and(*arguments)
       if @and_scope
         self.send(@and_scope, *arguments)
@@ -42,9 +74,22 @@ module TestAssistant::Email
       end
     end
 
+    # For constructing an assertion that at least one email was sent to a particular
+    # email address
+    #
+    # @example Asserting an email was sent to user@email.com
+    #   expect(email).to have_been_sent.to('user@email.com')
+    #
+    # @param [String, Array<String>] email_address address email is expected to be
+    #   sent to. If an array of email addresses, the email is expected to have been
+    #   sent to all of them.
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def to(email_address)
+      @expectations[:to] ||= []
+
       if email_address.kind_of?(Array)
-        @expectations[:to] = email_address
+        @expectations[:to] = @expectations[:to].concat(email_address)
       else
         @expectations[:to] ||= []
         @expectations[:to] << email_address
@@ -55,6 +100,17 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent from a particular
+    # email address
+    #
+    # @example Asserting an email was sent from admin@site.com
+    #   expect(email).to have_been_sent.from('admin@site.com')
+    #
+    # @param [String] email_address address email is expected to be sent from.
+    # @raise ArgumentError when from is called more than once on the same expectation,
+    #   as an email can only ben sent from a single sender.
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def from(email_address)
       if @expectations[:from]
         raise ArgumentError('An email can only have one from address, but you tried to assert the presence of 2 or more values')
@@ -67,6 +123,17 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent with a particular
+    # subject line
+    #
+    # @example Asserting an email was sent with subject line 'Hello'
+    #   expect(email).to have_been_sent.with_subject('Hello')
+    #
+    # @param [String] subject Subject line an email is expected to have been sent with
+    # @raise ArgumentError when with_subject is called more than once on the same
+    #   expectation, as an email can only have one subject line.
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def with_subject(subject)
       if @expectations[:with_subject]
         raise ArgumentError('An email can only have one subject, but you tried to assert the presence of 2 or more values')
@@ -79,6 +146,15 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent with a particular
+    # string in the body of the email
+    #
+    # @example Asserting an email was sent with the text 'User 1'
+    #   expect(email).to have_been_sent.with_text('User 1')
+    #
+    # @param [String] text Text an email is expected to have been sent with in the body
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def with_text(text)
       @expectations[:with_text] ||= []
       @expectations[:with_text].push(text)
@@ -87,6 +163,16 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent with a body that
+    # matches a particular CSS selector
+    #
+    # @example Asserting an email was sent with a body matching selector '#imporant-div'
+    #   expect(email).to have_been_sent.matching_selector('#imporant-div')
+    #
+    # @param [String] selector CSS selector that should match at least one sent
+    #   email's body
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def matching_selector(selector)
       @expectations[:matching_selector] ||= []
       @expectations[:matching_selector].push(selector)
@@ -95,6 +181,15 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent with a link to
+    # a particular url in the body
+    #
+    # @example Asserting an email was sent with a link to http://www.example.com
+    #   expect(email).to have_been_sent.with_link('http://www.example.com')
+    #
+    # @param [String] href URL that should appear in at least one sent email's body
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def with_link(href)
       @expectations[:with_link] ||= []
       @expectations[:with_link].push(href)
@@ -103,6 +198,16 @@ module TestAssistant::Email
       self
     end
 
+    # For constructing an assertion that at least one email was sent with an image
+    # hosted at a particular URL
+    #
+    # @example Asserting an email was sent with the image http://www.example.com/image.png
+    #   expect(email).to have_been_sent.with_link('http://www.example.com/image.png')
+    #
+    # @param [String] src URL of the image that should appear in at least one sent
+    #   email's body
+    # @return [TestAssistant::Email::Expectation] reference to self, to allow for
+    #   further method chaining
     def with_image(src)
       @expectations[:with_image] ||= []
       @expectations[:with_image].push(src)
@@ -111,10 +216,21 @@ module TestAssistant::Email
       self
     end
 
+    #
+    # RSpec Matcher methods
+    #
+
+    # Declares that RSpec should not attempt to diff the actual and expected values
+    # to put in the failure message. This class takes care of diffing and presenting
+    # the differences, itself.
+    # @return [false] always returns false
     def diffable?
       false
     end
 
+    # Whether at least one email was sent during the current test that matches the
+    # constructed expectation
+    # @return [Boolean] whether a matching email was sent
     def matches?(emails)
       @emails = emails
 
@@ -141,6 +257,17 @@ module TestAssistant::Email
       end
     end
 
+    # Message to display to StdOut by RSpec if the equality check fails. Includes a
+    # complete a human-readable summary of the differences between what emails were
+    # expected to be sent, and what were actually sent (if any). Only used when the
+    # positive assertion is used, i.e. expect(email).to have_been_sent. For the
+    # failure message used for negative assertions, i.e.
+    # expect(email).to_not have_been_sent, see #failure_message_when_negated
+    #
+    # @see #failure_message_when_negated
+    #
+    # @return [String] message full failure message with explanation of the differences
+    #   between what emails were expected and what was actually sent
     def failure_message
       field_descs = attribute_descriptions
       value_descs = value_descriptions
@@ -164,20 +291,14 @@ module TestAssistant::Email
       end
     end
 
-    def result_description(field_descriptions, values)
-      to_sentence(
-        field_descriptions.map.with_index do |field_description, index|
-          value = values[index]
-
-          if [ 'matching selector', 'with link', 'with image' ].include?(field_description)
-            "with body #{value}"
-          else
-            "#{field_description} #{value}"
-          end
-        end
-      )
-    end
-
+    # Failure message to display for negative RSpec assertions, i.e.
+    # expect(email).to_not have_been_sent. For the failure message displayed for positive
+    # assertions, see #failure_message.
+    #
+    # @see #failure_message
+    #
+    # @return [String] message full failure message with explanation of the differences
+    #   between what emails were expected and what was actually sent
     def failure_message_when_negated
       field_descs = attribute_descriptions(negated: true)
       value_descs = value_descriptions(negated: true)
@@ -191,6 +312,20 @@ module TestAssistant::Email
 
     private
 
+    def result_description(field_descriptions, values)
+      to_sentence(
+          field_descriptions.map.with_index do |field_description, index|
+            value = values[index]
+
+            if [ 'matching selector', 'with link', 'with image' ].include?(field_description)
+              "with body #{value}"
+            else
+              "#{field_description} #{value}"
+            end
+          end
+      )
+    end
+
     def sent_email_values
       @emails.inject([]) do |memo, email|
 
@@ -295,7 +430,11 @@ module TestAssistant::Email
     end
 
     def email_body(email)
-      email.parts.first.body.decoded
+      if email.parts.first
+        email.parts.first.body.decoded
+      else
+        email.body.encoded
+      end
     end
 
     def email_matches?(email, assertion, expected)

data/lib/test_assistant/email/helpers.rb

@@ -1,15 +1,35 @@
 require 'test_assistant/email/expectation'
 
 module TestAssistant::Email
+  # Module containing email helper methods that can be mixed into RSpec the test scope
+  #
+  # @see TestAssistant::Configuration#include_email_helpers
   module Helpers
+    # Syntactic sugar for referencing the list of emails sent since the start of the test
+    #
+    # @return [Array<Mail::Message>] list of sent emails
+    #
+    # @example Asserting email has been sent
+    #   expect(email).to have_been_sent.to('test@email.com')
     def email
       ActionMailer::Base.deliveries
     end
 
+    # Clears the list of sent emails. Automatically called by Test Assistant at the
+    # end of every test.
+    #
+    # @return void
     def clear_emails
       ActionMailer::Base.deliveries = []
     end
 
+    # Creates a new email expectation that allows asserting emails should have specific
+    # attributes.
+    #
+    # @see TestAssistant::Email::Expectation
+    #
+    # @example Asserting email has been sent
+    #   expect(email).to have_been_sent.to('test@email.com')
     def have_been_sent
       TestAssistant::Email::Expectation.new
     end

data/lib/test_assistant/failure_reporter.rb

@@ -1,28 +1,56 @@
 module TestAssistant
+  # Factory class for generating a failure report summarising the last request and
+  # response sent in a particular test and opening it in a browser. Intended to
+  # aid in debugging and to be toggled on through the use of RSpec tags and configured
+  # using TestAssistant::Configuration#render_failed_responses
+  #
+  # @see TestAssistant::Configuration#render_failed_responses
   class FailureReporter
+    # Base class for generating, saving and opening failure reports. Those classes that
+    # inherit from it provide further customisations to better parse and format different
+    # request and response bodies, depending on their format.
     class SummaryReporter
       attr_accessor :next, :file_extension
 
+      # Creates a new SummaryReport object
+      #
+      # @param [ActionDispatch::Request] request the last request made before the test
+      #   failed
+      # @param [ActionDispatch::TestResponse] response the response to the last request
+      #    made before the test failed
+      # @param [String] extension what file extension should be used when saving the
+      #   failure report
+      # @return [SummaryReport] new summary report object
       def initialize(request, response, extension = file_extension)
         @request, @response, @extension = request, response, extension
       end
 
+      # Writes the failure report to the tmp directory in the root of your Rails
+      # project so that it may be opened for viewing in an appropriate application
+      # depending on the failure report's file extension
+      #
+      # @return void
       def write
         File.open(file_path, 'w') do |file|
           file.write(summary)
         end
       end
 
+      # Opens the failure report file using an application that depends on the failure
+      # report's file extension. Expects that #write has already been called and the
+      # file exists.
+      #
+      # @return void
       def open
         system "open #{file_path}"
       end
 
+      protected
+
       def summary
         @response.body
       end
 
-      protected
-
       def file_path
         @file_path ||= "#{Rails.root}/tmp/#{DateTime.now.to_i}.#{@extension}"
       end

data/lib/test_assistant/json/expectation.rb

@@ -2,22 +2,52 @@ require 'capybara/rspec'
 require 'hashdiff'
 
 module TestAssistant::Json
+  # Backing class for the eql_json RSpec matcher. Used for matching Ruby representations
+  # of JSON response bodies. Provides clear diff representations for simple and complex
+  # or nested JSON objects, highlighting only the values that are different, and where
+  # they are in the larger JSON object.
+  #
+  # Expected to be used as part of a RSpec test suite and with json_response.
+  #
+  # Implements the same interface as RSpec custom matcher classes
+  #
+  # @see TestAssistant::Json::Helpers#json_response
+  # @see TestAssistant::Json::Helpers#eql_json
   class Expectation
+    # Creates a new TestAssistant::Json::Expectation object.
+    #
+    # @see TestAssistant::Json::Helpers#eql_json
+    #
+    # @param expected the expected value that will be compared with the actual value
+    # @return [TestAssistant::Json::Expectation] new expectation object
     def initialize(expected)
       @expected = expected
       @message = ''
       @reported_differences = {}
     end
 
+    # Declares that RSpec should not attempt to diff the actual and expected values
+    # to put in the failure message. This class takes care of diffing and presenting
+    # the differences, itself.
+    # @return [false] always returns false
     def diffable?
       false
     end
 
+    # Whether the actual value and the expected value are considered equal.
+    # @param actual value to be compared to the expected value for equality
+    # @return [Boolean] whether actual is equal to expected
     def matches?(actual)
       @actual = actual
       @expected.eql?(@actual)
     end
 
+    # Message to display to StdOut by RSpec if the equality check fails. Includes a
+    # complete serialisation of the expected and actual values and is then followed
+    # by a description of only the (possibly deeply nested) attributes that are
+    # different
+    # @return [String] message full failure message with explanation of why actual
+    #   failed the equality check with expected
     def failure_message
       @message += "Expected: #{@expected}\n\n"
       @message += "Actual: #{@actual}\n\n"
@@ -30,49 +60,64 @@ module TestAssistant::Json
 
     private
 
-    def add_diff_to_message(original_actual, original_expected, parent_prefix = '')
-      differences = HashDiff
-                        .diff(original_actual, original_expected)
+    # Adds diff descriptions to the failure message until the all the nodes of the
+    # expected and actual values have been compared and all the differences (and the
+    # paths to them) have been included. For Hashes and Arrays, it recursively calls
+    # itself to compare all nodes and elements.
+    #
+    # @param actual_value current node of the actual value being compared to the
+    #   corresponding node of the expected value
+    # @param expected_value current node of the expected value being compared to
+    #   the corresponding node of the actual value
+    # @param [String] path path to the current nodes being compared,
+    #   relative to the root full objects
+    # @return void Diff descriptions are appended directly to message
+    def add_diff_to_message(actual_value, expected_value, path = '')
+      diffs_sorted_by_name = HashDiff
+                        .diff(actual_value, expected_value)
                         .sort{|diff1, diff2| diff1[1] <=> diff2[1]}
 
-      grouped_differences =
-          differences.inject({}) do |memo, diff|
-            operator, name, value = diff
-            memo[name] ||= {}
-            memo[name][operator] = value
-            memo
-          end
+      diffs_grouped_by_name =
+        diffs_sorted_by_name.inject({}) do |memo, diff|
+          operator, name, value = diff
+          memo[name] ||= {}
+          memo[name][operator] = value
+          memo
+        end
+
+      diffs_grouped_by_name.each do |name, difference|
 
-      grouped_differences.each do |name, difference|
-        removed_value = difference['-']
-        added_value = difference['+']
-        swapped_value = difference['~']
+        missing_value = difference['-'] || value_at_path(actual_value, name)
+        extra_value = difference['+'] || value_at_path(expected_value, name)
+        different_value = difference['~']
 
-        full_name = parent_prefix.length > 0 ? "#{parent_prefix}.#{name}" : name
+        full_path = path.length > 0 ? "#{path}.#{name}" : name
 
-        if non_empty_hash?(removed_value) && non_empty_hash?(added_value)
-          add_diff_to_message(removed_value, added_value, full_name)
+        if non_empty_hash?(missing_value) && non_empty_hash?(extra_value)
 
-        elsif non_empty_array?(removed_value) && non_empty_array?(added_value)
+          add_diff_to_message(missing_value, extra_value, full_path)
 
-          [removed_value.length, added_value.length].max.times do |i|
-            add_diff_to_message(removed_value[i], added_value[i], full_name)
+        elsif non_empty_array?(missing_value) && non_empty_array?(extra_value)
+
+          [ missing_value.length, extra_value.length ].max.times do |i|
+            add_diff_to_message(missing_value[i], extra_value[i], full_path)
           end
+
         else
           if difference.has_key?('~')
-            add_diff_description(full_name,
-                format_diff(
-                    full_name,
-                    attribute_value(original_expected, name),
-                    swapped_value
+            append_to_message(full_path,
+                get_diff(
+                    full_path,
+                    expected: value_at_path(expected_value, name),
+                    actual: different_value
                 )
             )
           else
-            add_diff_description(full_name,
-                format_diff(
-                  full_name,
-                  added_value || attribute_value(original_expected, name),
-                  removed_value || attribute_value(original_actual, name)
+            append_to_message(full_path,
+                get_diff(
+                  full_path,
+                  expected: extra_value,
+                  actual: missing_value
               )
             )
           end
@@ -89,7 +134,7 @@ module TestAssistant::Json
       target.kind_of?(Array) && target.any?
     end
 
-    def add_diff_description(attribute, difference_description)
+    def append_to_message(attribute, difference_description)
       unless already_reported_difference?(attribute)
         @message += difference_description
         @reported_differences[attribute] = true
@@ -100,7 +145,7 @@ module TestAssistant::Json
       !!@reported_differences[attribute]
     end
 
-    def attribute_value(target, attribute_path)
+    def value_at_path(target, attribute_path)
       keys = attribute_path.split(/\[|\]|\./)
 
       keys = keys.map do |key|
@@ -125,11 +170,11 @@ module TestAssistant::Json
       result
     end
 
-    def format_diff(attribute, expected, actual)
+    def get_diff(attribute, options = {})
       diff_description = ''
       diff_description += "#{attribute}\n"
-      diff_description += "Expected: #{format_value(expected)}\n"
-      diff_description += "Actual: #{format_value(actual)}\n\n"
+      diff_description += "Expected: #{format_value(options[:expected])}\n"
+      diff_description + "Actual: #{format_value(options[:actual])}\n\n"
     end
 
     def format_value(value)

data/lib/test_assistant/json/helpers.rb

@@ -1,7 +1,15 @@
 require 'test_assistant/json/expectation'
 
 module TestAssistant::Json
+  # Module containing JSON helper methods that can be mixed into RSpec the test scope
+  #
+  # @see TestAssistant::Configuration#include_json_helpers
   module Helpers
+    # Parses the last response body in a Rails RSpec controller or request test as JSON
+    #
+    # @return [Hash{String => String, Number, Hash, Array}] Ruby representation of
+    #   the JSON response body
+    # @raise []JSON::ParserError] when the response body is not valid JSON
     def json_response
       begin
         JSON.parse(response.body)
@@ -10,6 +18,19 @@ module TestAssistant::Json
       end
     end
 
+    # Creates a new TestAssistant::Json::Expectation instance so it can be passed
+    # to RSpec to match against an actual value.
+    #
+    # @see TestAssistant::Expectation
+    #
+    # @param expected the expected value the RSpec matcher should match against
+    # @return [TestAssistant::Json::Expectation] new expectation object
+    #
+    # @example Use the eql_json expectation
+    #   expect(actual).to eql_json(expected)
+    #
+    # @example Use the eql_json expectation with json_response
+    #   expect(json_response).to eql_json(expected)
     def eql_json(expected)
       TestAssistant::Json::Expectation.new(expected)
     end

data/lib/test_assistant/version.rb

@@ -1,3 +1,3 @@
 module TestAssistant
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/test_assistant.rb

@@ -1,8 +1,23 @@
 require "test_assistant/version"
 require 'test_assistant/configuration'
 
+# Utility module for working with RSpec test suites for Rails or similar applications
+#
+# Contains:
+# - Expressive syntax for asserting testing emails
+# - Sophisticated JSON matchers and diff failure reports
+# - Rendering and debugging tools for viewing test failures
+#
+# @see https://github.com/greena13/test_assistant Test Assistant Github page
 module TestAssistant
   class << self
+    # Configures what parts of TestAssistant are included in your test suite and how
+    # they behave.
+    #
+    # @see TestAssistant::Configuration
+    #
+    # @param rspec_config RSpec configuration object available in RSpec.configure block
+    # @return void
     def configure(rspec_config)
       configuration = Configuration.new(rspec_config)
 
@@ -13,5 +28,4 @@ module TestAssistant
 
     alias :config :configure
   end
-
 end

data/spec/eql_json_spec.rb

@@ -289,9 +289,126 @@ RSpec.describe "eql_json" do
       end
 
     end
-
   end
 
+  context "when comparing complicated objects" do
+
+    let(:expected ) { {
+        "a" => "aa",
+        "b" => "bb",
+        "c" => {
+            "d" => 2,
+            "e" => "ee",
+            "f" => [{
+                "g" => "gg",
+                "h" => "hh",
+            },
+                {
+                    "g" => "g1",
+                    "h" => "h1",
+                }
+            ],
+            "i" => {
+                "j" => "jj",
+                "k" => "kk",
+                "l" => [],
+                "m" => {
+                    "n" => 1,
+                    "o" => "oo",
+                    "p" => {
+                        "q" => "qq"
+                    },
+                    "r" => [],
+                },
+            },
+            "s" => [
+                {
+                    "t" => 179,
+                    "u" => "UU"
+                }
+            ]
+        }
+    } }
+
+    let(:actual) { {
+        "a" => "aa",
+        "b" => "bb",
+        "c" => {
+            "d" => 3,
+            "e" => "ee",
+            "f" => [{
+                "g" => "g1",
+                "h" => "hh",
+            },
+                {
+                    "g" => "g1",
+                    "h" => "h1",
+                    "h2" => "h2"
+                }
+            ],
+            "i" => {
+                "j" => "j2",
+                "k" => "kk",
+                "l" => [2],
+                "m" => {
+                    "o" => "oo",
+                    "p" => {
+                        "q" => "qq"
+                    },
+                    "r" => [],
+                },
+            },
+            "s" => [
+                {
+                    "t" => 179,
+                    "u" => "UU"
+                }
+            ]
+        }
+    } }
+
+    it "then correctly reports the elements that have changed" do
+
+      expect(actual).to eql(actual)
+
+      expect(actual).to_not eql(expected)
+
+      begin
+        expect(actual).to eql_json(expected)
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+
+        expect(e.message).to eql(error_message(expected, actual, {
+          'c.d' => {
+              expected: 2,
+              actual: 3
+          },
+          'c.f[0].g' => {
+              expected: "'gg'",
+              actual: "'g1'"
+          },
+          'c.f[1].h2' => {
+              expected: nil,
+              actual: "'h2'"
+          },
+          'c.i.j' => {
+              expected: "'jj'",
+              actual: "'j2'"
+          },
+          'c.i.l[0]' => {
+              expected: nil,
+              actual: 2
+          },
+          'c.i.m.n' => {
+              expected: 1,
+              actual: nil
+          }
+        }))
+
+      end
+
+    end
+
+  end
 
   private
 
@@ -308,7 +425,6 @@ RSpec.describe "eql_json" do
       message_lines.push("Actual: #{difference[:actual]}\n\n")
     end
 
-
     message_lines.join
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test_assistant
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Aleck Greenham
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-30 00:00:00.000000000 Z
+date: 2018-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -124,6 +124,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".yardopts"
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -162,7 +163,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2.1
 signing_key: 
 specification_version: 4
 summary: A toolbox for increased testing efficiency with RSpec