active_record_change_matchers 1.0.1 → 1.1.0

data/db/schema.rb

@@ -2,28 +2,36 @@
 # of editing this file, please use the migrations feature of Active Record to
 # incrementally modify your database, and then regenerate this schema definition.
 #
-# Note that this schema.rb definition is the authoritative source for your
-# database schema. If you need to create the application database on another
-# system, you should be using db:schema:load, not running all the migrations
-# from scratch. The latter is a flawed and unsustainable approach (the more migrations
-# you'll amass, the slower it'll run and the greater likelihood for issues).
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 20151017231107) do
-
+ActiveRecord::Schema[7.2].define(version: 2016_01_01_000000) do
   create_table "dogs", force: :cascade do |t|
-    t.string   "name"
-    t.string   "breed"
-    t.datetime "created_at"
-    t.datetime "updated_at"
+    t.string "name"
+    t.string "breed"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
   end
 
   create_table "people", force: :cascade do |t|
-    t.string   "first_name"
-    t.string   "last_name"
-    t.datetime "created_at"
-    t.datetime "updated_at"
+    t.string "first_name"
+    t.string "last_name"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
+  create_table "pets", force: :cascade do |t|
+    t.integer "person_id", null: false
+    t.string "name"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index ["person_id"], name: "index_pets_on_person_id"
   end
 
+  add_foreign_key "pets", "people"
 end

data/lib/active_record_change_matchers/hash_format.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Ruby 3.4 changed Hash#inspect (symbol keys use {key: val}, other keys use "key" => val with spaces).
+# This helper produces a stable format so error messages look the same on 3.3 and 3.4.
+module ActiveRecordChangeMatchers
+  def self.format_hash_for_message(hash)
+    "{#{hash.map { |k, v| "#{k.inspect}=>#{v.inspect}" }.join(', ')}}"
+  end
+end

data/lib/active_record_change_matchers/matchers/create_a_new_matcher.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module ActiveRecordChangeMatchers
+  class CreateANewMatcher
+    include RSpec::Matchers::Composable
+
+    def supports_block_expectations?
+      true
+    end
+
+    def initialize(klass, options = {})
+      @klass = klass
+      @strategy_key = options[:strategy]
+    end
+
+    def with_attributes(attributes)
+      @attributes = attributes
+      self
+    end
+
+    def which(&block)
+      @which_block = block
+      self
+    end
+
+    def which_is_expected_to(matcher)
+      @which_matcher = matcher
+      self
+    end
+
+    def and_return_it
+      @should_return_record = true
+      self
+    end
+
+    def matches?(block)
+      @block_return_value = nil
+      wrapped_block = proc { @block_return_value = block.call }
+      strategy = ActiveRecordChangeMatchers::Strategies.for_key(@strategy_key).new(wrapped_block)
+      @created_records = strategy.new_records([@klass])[@klass]
+
+      return false unless @created_records.count == 1
+
+      record = @created_records.first
+
+      @attribute_mismatches = []
+      @attributes&.each do |field, value|
+        unless values_match?(value, record.public_send(field))
+          @attribute_mismatches << [field, value, record.public_send(field)]
+        end
+      end
+
+      if @attribute_mismatches.none? && @which_block
+        begin
+          @which_block.call(record)
+        rescue RSpec::Expectations::ExpectationNotMetError => e
+          @which_failure = e
+        end
+      end
+
+      if @attribute_mismatches.none? && @which_matcher && !@which_matcher.matches?(record)
+        @matcher_failure = @which_matcher.failure_message
+      end
+
+      if @should_return_record && @attribute_mismatches.empty? && @which_failure.nil? && @matcher_failure.nil? &&
+         !values_match?(record, @block_return_value)
+        @return_value_mismatch = { expected: record, actual: @block_return_value }
+      end
+
+      @attribute_mismatches.empty? && @which_failure.nil? && @matcher_failure.nil? && @return_value_mismatch.nil?
+    end
+
+    def failure_message
+      if @created_records.count != 1
+        "the block should have created 1 #{@klass}, but created #{@created_records.count}"
+      elsif @attribute_mismatches&.any?
+        @attribute_mismatches.map do |field, expected, actual|
+          expected_description = composable_matcher?(expected) ? expected.description : expected.inspect
+          "Expected #{field.inspect} to be #{expected_description}, but was #{actual.inspect}"
+        end.join("\n")
+      elsif @which_failure
+        @which_failure.message
+      elsif @return_value_mismatch
+        expected = @return_value_mismatch[:expected]
+        actual = @return_value_mismatch[:actual]
+        "Expected the block to return the created #{@klass}, but it returned #{actual.inspect} instead of #{expected.inspect}"
+      else
+        @matcher_failure
+      end
+    end
+
+    def failure_message_when_negated
+      if @created_records.count == 1 && @attributes && @attribute_mismatches.none?
+        "the block should not have created a #{@klass} with attributes #{format_attributes_hash(@attributes)}, but did"
+      elsif @created_records.count == 1 && @which_block && !@which_failure
+        "the newly created #{@klass} should have failed an expectation in the given block, but didn't"
+      elsif @created_records.count == 1
+        "the block should not have created a #{@klass}, but created #{@created_records.count}: #{@created_records.inspect}"
+      else
+        "the block created a #{@klass} that matched all given criteria"
+      end
+    end
+
+    def description
+      "create a #{@klass}, optionally verifying attributes"
+    end
+
+    private
+
+    def composable_matcher?(value)
+      value.respond_to?(:failure_message_when_negated)
+    end
+
+    def format_attributes_hash(attributes)
+      hash = attributes.transform_values { |value| format_value(value) }
+      ActiveRecordChangeMatchers.format_hash_for_message(hash)
+    end
+
+    def format_value(value)
+      composable_matcher?(value) ? value.description : value
+    end
+  end
+end
+
+RSpec::Matchers.define :create_a_new do |klass, *strategy_arg|
+  supports_block_expectations
+  options = strategy_arg.first.is_a?(Hash) ? strategy_arg.first : {}
+  base = ActiveRecordChangeMatchers::CreateANewMatcher.new(klass, options)
+
+  match { |block| base.matches?(block) }
+  failure_message { base.failure_message }
+  failure_message_when_negated { base.failure_message_when_negated }
+  description { base.description }
+
+  chain(:with_attributes) { |*args| base.with_attributes(*args) }
+  chain(:which) { |&block| base.which(&block) }
+  chain(:which_is_expected_to) { |*args| base.which_is_expected_to(*args) }
+  chain(:and_return_it) { base.and_return_it }
+end
+
+RSpec::Matchers.alias_matcher :create_a, :create_a_new
+RSpec::Matchers.alias_matcher :create_an, :create_a_new

data/lib/active_record_change_matchers/matchers/create_associated_matcher.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module ActiveRecordChangeMatchers
+  class CreateAssociatedMatcher
+    include ActiveSupport::Inflector
+    include RSpec::Matchers::Composable
+
+    def supports_block_expectations?
+      true
+    end
+
+    def initialize(scope_or_counts)
+      @scope_or_counts = scope_or_counts
+    end
+
+    def with_attributes(attributes)
+      @expected_attributes = normalize_expected_attributes(attributes)
+      validate_attributes_count!
+      self
+    end
+
+    def which(&block)
+      @which_block = block
+      self
+    end
+
+    def and_return_it
+      raise ArgumentError, '`and_return_it` only applies when expecting exactly one record' unless single_record?
+
+      @should_return_records = true
+      self
+    end
+
+    def and_return_them
+      @should_return_records = true
+      self
+    end
+
+    def matches?(block)
+      @block_return_value = nil
+      wrapped_block = proc { @block_return_value = block.call }
+      strategy = ActiveRecordChangeMatchers::Strategies.for_key(@strategy_key).new(wrapped_block)
+      @new_records = strategy.new_records(scopes)
+
+      @incorrect_counts = @new_records.each_with_object({}) do |(scope, records), incorrect|
+        expected_count = scope_counts[scope]
+        actual_count = records.size
+        incorrect[scope] = { expected: expected_count, actual: actual_count } if actual_count != expected_count
+      end
+
+      return false if @incorrect_counts.any?
+
+      if @expected_attributes
+        return false unless match_expected_attributes
+      end
+
+      run_which_block
+      check_return_value if @should_return_records
+
+      @which_failure.nil? && @return_value_mismatch.nil?
+    end
+
+    def failure_message
+      if @incorrect_counts&.any?
+        @incorrect_counts.map do |scope, counts|
+          "The block should have created #{count_str(scope.klass, counts[:expected])} within the scope, but created #{counts[:actual]}."
+        end.join(' ')
+      elsif @incorrect_attributes&.any? { |_, list| list.any? }
+        format_attributes_failure_message
+      elsif @which_failure
+        @which_failure.message
+      elsif @return_value_mismatch
+        format_return_value_failure_message
+      else
+        'Unknown error'
+      end
+    end
+
+    def failure_message_when_negated
+      scope_counts.map do |scope, expected_count|
+        "The block should not have created #{count_str(scope.klass, expected_count)} within the scope, but created #{expected_count}."
+      end.join(' ')
+    end
+
+    def description
+      counts_strs = scope_counts.map { |scope, count| count_str(scope.klass, count) }
+      "create #{counts_strs.join(', ')} within the given scope(s)"
+    end
+
+    private
+
+    def scope_counts
+      @scope_counts ||= normalize_scope_counts(@scope_or_counts)
+    end
+
+    def normalize_scope_counts(value)
+      case value
+      when Hash
+        value
+      else
+        { value => 1 }
+      end
+    end
+
+    def scopes
+      scope_counts.keys
+    end
+
+    def single_scope?
+      scope_counts.size == 1
+    end
+
+    def single_record?
+      single_scope? && scope_counts.values.first == 1
+    end
+
+    def count_str(klass, count)
+      "#{count} #{klass.name.pluralize(count)}"
+    end
+
+    def normalize_expected_attributes(attributes)
+      return {} if attributes.nil?
+
+      if single_scope? && attributes.is_a?(Hash) && attributes.keys.all? { |k| k.is_a?(Symbol) || k.is_a?(String) }
+        { scopes.first => [attributes] }
+      elsif single_scope? && attributes.is_a?(Array)
+        { scopes.first => attributes }
+      else
+        attributes
+      end
+    end
+
+    def validate_attributes_count!
+      return unless @expected_attributes
+
+      @expected_attributes.each do |scope, hashes|
+        expected_count = scope_counts[scope]
+        next unless expected_count && hashes.size != expected_count
+
+        raise ArgumentError,
+              "Specified the block should create #{expected_count} #{scope.klass.name} within the scope, but provided #{hashes.size} attribute specifications"
+      end
+    end
+
+    def match_expected_attributes
+      @matched_records = Hash.new { |h, k| h[k] = [] }
+      @all_attributes = Hash.new { |h, k| h[k] = [] }
+      @incorrect_attributes = @expected_attributes.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(scope, expected_attrs_list), incorrect|
+        records = @new_records[scope]
+        @all_attributes[scope] = expected_attrs_list.map(&:keys).flatten.uniq
+        expected_attrs_list.each do |expected_attrs|
+          matched = (records - @matched_records[scope]).find do |record|
+            expected_attrs.all? { |k, v| values_match?(v, record.public_send(k)) }
+          end
+          if matched
+            @matched_records[scope] << matched
+          else
+            incorrect[scope] << expected_attrs
+          end
+        end
+      end
+      @unmatched_records = scopes.to_h do |scope|
+        [scope, @new_records[scope] - @matched_records[scope]]
+      end.reject { |_, records| records.empty? }
+      @incorrect_attributes.none? { |_, list| list.any? }
+    end
+
+    def run_which_block
+      @which_failure = nil
+      return unless @which_block
+
+      new_records_by_klass = @new_records.transform_keys(&:klass)
+      @which_block.call(new_records_by_klass)
+    rescue RSpec::Expectations::ExpectationNotMetError => e
+      @which_failure = e
+    end
+
+    def check_return_value
+      return unless @incorrect_counts.empty? &&
+                    (@incorrect_attributes.nil? || @incorrect_attributes.none? { |_, l| l.any? }) &&
+                    @which_failure.nil?
+
+      all_created = @new_records.values.flatten
+      returned = Array(@block_return_value)
+      missing = all_created.reject { |r| returned.any? { |o| values_match?(r, o) } }
+      if single_record? && missing.any?
+        @return_value_mismatch = { expected: all_created.first, actual: @block_return_value }
+      elsif missing.any?
+        @return_value_mismatch = { expected: all_created, actual: @block_return_value, missing: missing }
+      end
+    end
+
+    def format_attributes_failure_message
+      "The block should have created:\n" +
+        @expected_attributes.map do |scope, attrs|
+          "    #{attrs.count} #{scope.klass.name} with these attributes:\n" +
+            attrs.map { |a| "        #{ActiveRecordChangeMatchers.format_hash_for_message(a)}" }.join("\n")
+        end.join("\n") +
+        "\nDiff:" +
+        @incorrect_attributes.map do |scope, attrs|
+          next if attrs.empty?
+
+          "\n    Missing #{attrs.count} #{scope.klass.name} with these attributes:\n" +
+            attrs.map { |a| "        #{ActiveRecordChangeMatchers.format_hash_for_message(a)}" }.join("\n")
+        end.compact.join("\n") +
+        @unmatched_records.map do |scope, records|
+          "\n    Extra #{records.count} #{scope.klass.name} with these attributes:\n" +
+            records.map do |r|
+              attrs = @all_attributes[scope].each_with_object({}) { |attr, h| h[attr] = r.public_send(attr) }
+              "        #{ActiveRecordChangeMatchers.format_hash_for_message(attrs)}"
+            end.join("\n")
+        end.join("\n")
+    end
+
+    def format_return_value_failure_message
+      if single_record?
+        "Expected the block to return the created #{scopes.first.klass.name}, but it returned #{@return_value_mismatch[:actual].inspect} instead of #{@return_value_mismatch[:expected].inspect}"
+      else
+        missing = @return_value_mismatch[:missing]
+        'Expected the block to return the created records, but it did not return all of them. ' \
+          "Missing records: #{missing.map(&:inspect).join(', ')}. " \
+          "Expected all of: #{@return_value_mismatch[:expected].map(&:inspect).join(', ')}, " \
+          "but got: #{@return_value_mismatch[:actual].inspect}"
+      end
+    end
+  end
+end
+
+RSpec::Matchers.define :create_associated do |scope_or_counts|
+  supports_block_expectations
+  base = ActiveRecordChangeMatchers::CreateAssociatedMatcher.new(scope_or_counts)
+
+  match { |block| base.matches?(block) }
+  failure_message { base.failure_message }
+  failure_message_when_negated { base.failure_message_when_negated }
+  description { base.description }
+
+  chain(:with_attributes) { |*args| base.with_attributes(*args) }
+  chain(:which) { |&block| base.which(&block) }
+  chain(:and_return_it) { base.and_return_it }
+  chain(:and_return_them) { base.and_return_them }
+end

data/lib/active_record_change_matchers/matchers/create_records_matcher.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module ActiveRecordChangeMatchers
+  class CreateRecordsMatcher
+    include ActiveSupport::Inflector
+    include RSpec::Matchers::Composable
+
+    def supports_block_expectations?
+      true
+    end
+
+    def initialize(record_counts, options = {})
+      @record_counts = record_counts
+      @strategy_key = options[:strategy]
+    end
+
+    def with_attributes(attributes)
+      if (mismatch = attributes.find { |klass, hashes| hashes.size != @record_counts[klass] })
+        mismatched_class, hashes = mismatch
+        raise ArgumentError,
+              "Specified the block should create #{@record_counts[mismatched_class]} #{mismatched_class}, but provided #{hashes.size} #{mismatched_class} attribute specifications"
+      end
+      @expected_attributes = attributes
+      self
+    end
+
+    def which(&block)
+      @which_block = block
+      self
+    end
+
+    def and_return_them
+      @should_return_records = true
+      self
+    end
+
+    def matches?(block)
+      @block_return_value = nil
+      wrapped_block = proc { @block_return_value = block.call }
+      strategy = ActiveRecordChangeMatchers::Strategies.for_key(@strategy_key).new(wrapped_block)
+      @new_records = strategy.new_records(@record_counts.keys)
+
+      @incorrect_counts = @new_records.each_with_object({}) do |(klass, new_records), incorrect|
+        actual_count = new_records.count
+        expected_count = @record_counts[klass]
+        incorrect[klass] = { expected: expected_count, actual: actual_count } if actual_count != expected_count
+      end
+
+      return false if @incorrect_counts.any?
+
+      if @expected_attributes
+        return false unless match_expected_attributes
+      end
+
+      run_which_block
+      check_return_value if @should_return_records
+
+      @which_failure.nil? && @return_value_mismatch.nil?
+    end
+
+    def failure_message
+      if @incorrect_counts&.any?
+        @incorrect_counts.map do |klass, counts|
+          "The block should have created #{count_str(klass, counts[:expected])}, but created #{counts[:actual]}."
+        end.join(' ')
+      elsif @incorrect_attributes&.any?
+        format_attributes_failure_message
+      elsif @which_failure
+        @which_failure.message
+      elsif @return_value_mismatch
+        format_return_value_failure_message
+      else
+        'Unknown error'
+      end
+    end
+
+    def failure_message_when_negated
+      @record_counts.map do |klass, expected_count|
+        "The block should not have created #{count_str(klass, expected_count)}, but created #{expected_count}."
+      end.join(' ')
+    end
+
+    def description
+      counts_strs = @record_counts.map { |klass, count| count_str(klass, count) }
+      "create #{counts_strs.join(', ')}"
+    end
+
+    private
+
+    def count_str(klass, count)
+      "#{count} #{klass.name.pluralize(count)}"
+    end
+
+    def match_expected_attributes
+      @matched_records = Hash.new { |hash, key| hash[key] = [] }
+      @all_attributes = Hash.new { |hash, key| hash[key] = [] }
+      @incorrect_attributes = @expected_attributes.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(klass, expected_attributes), incorrect|
+        @all_attributes[klass] = expected_attributes.map(&:keys).flatten.uniq
+        expected_attributes.each do |expected_attrs|
+          matched_record = (@new_records.fetch(klass) - @matched_records[klass]).find do |record|
+            expected_attrs.all? { |k, v| values_match?(v, record.public_send(k)) }
+          end
+          if matched_record
+            @matched_records[klass] << matched_record
+          else
+            incorrect[klass] << expected_attrs
+          end
+        end
+      end
+      @unmatched_records = @matched_records.map do |klass, records|
+        [klass, @new_records[klass] - records]
+      end.to_h.reject { |_k, v| v.empty? }
+      @incorrect_attributes.none?
+    end
+
+    def run_which_block
+      @which_failure = nil
+      return unless @which_block
+
+      @which_block.call(@new_records)
+    rescue RSpec::Expectations::ExpectationNotMetError => e
+      @which_failure = e
+    end
+
+    def check_return_value
+      return unless @incorrect_counts.empty? &&
+                    (@incorrect_attributes.nil? || @incorrect_attributes.none?) &&
+                    @which_failure.nil?
+
+      all_created_records = @new_records.values.flatten
+      return_value_array = Array(@block_return_value)
+      missing_records = all_created_records.reject do |record|
+        return_value_array.any? { |returned| values_match?(record, returned) }
+      end
+      return unless missing_records.any?
+
+      @return_value_mismatch = {
+        expected: all_created_records,
+        actual: @block_return_value,
+        missing: missing_records
+      }
+    end
+
+    def format_attributes_failure_message
+      "The block should have created:\n" +
+        @expected_attributes.map do |klass, attrs|
+          "    #{attrs.count} #{klass} with these attributes:\n" +
+            attrs.map { |a| "        #{ActiveRecordChangeMatchers.format_hash_for_message(a)}" }.join("\n")
+        end.join("\n") +
+        "\nDiff:" +
+        @incorrect_attributes.map do |klass, attrs|
+          "\n    Missing #{attrs.count} #{klass} with these attributes:\n" +
+            attrs.map { |a| "        #{ActiveRecordChangeMatchers.format_hash_for_message(a)}" }.join("\n")
+        end.join("\n") +
+        @unmatched_records.map do |klass, records|
+          "\n    Extra #{records.count} #{klass} with these attributes:\n" +
+            records.map do |r|
+              attrs = @all_attributes[klass].each_with_object({}) { |attr, h| h[attr] = r.public_send(attr) }
+              "        #{ActiveRecordChangeMatchers.format_hash_for_message(attrs)}"
+            end.join("\n")
+        end.join("\n")
+    end
+
+    def format_return_value_failure_message
+      missing = @return_value_mismatch[:missing]
+      expected = @return_value_mismatch[:expected]
+      actual = @return_value_mismatch[:actual]
+      'Expected the block to return the created records, but it did not return all of them. ' \
+        "Missing records: #{missing.map(&:inspect).join(', ')}. " \
+        "Expected all of: #{expected.map(&:inspect).join(', ')}, " \
+        "but got: #{actual.inspect}"
+    end
+  end
+end
+
+RSpec::Matchers.define :create_records do |record_counts, *strategy_arg|
+  supports_block_expectations
+  options = strategy_arg.first.is_a?(Hash) ? strategy_arg.first : {}
+  base = ActiveRecordChangeMatchers::CreateRecordsMatcher.new(record_counts, options)
+
+  match { |block| base.matches?(block) }
+  failure_message { base.failure_message }
+  failure_message_when_negated { base.failure_message_when_negated }
+  description { base.description }
+
+  chain(:with_attributes) { |*args| base.with_attributes(*args) }
+  chain(:which) { |&block| base.which(&block) }
+  chain(:and_return_them) { base.and_return_them }
+end
+
+RSpec::Matchers.alias_matcher :create, :create_records

data/lib/active_record_change_matchers/version.rb

@@ -1,3 +1,3 @@
 module ActiveRecordChangeMatchers
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/active_record_change_matchers.rb

@@ -1,6 +1,7 @@
 require "rspec/expectations"
 require "active_record"
 
+require_relative "active_record_change_matchers/hash_format"
 Dir[File.dirname(__FILE__) + "/active_record_change_matchers/**/*.rb"].each {|file| require file }
 
 module ActiveRecordChangeMatchers