Add unordered array matcher

src/spectator/matchers/array_matcher.cr

@@ -1,4 +1,5 @@
 require "./value_matcher"
+require "./unordered_array_matcher"
 
 module Spectator::Matchers
   # Matcher for checking that the contents of one array (or similar type)
@@ -35,6 +36,17 @@ module Spectator::Matchers
       super
     end
 
+    # Returns a matcher that uses the same expected array, but allows unordered items.
+    def in_any_order
+      UnorderedArrayMatcher.new(@expected, @label)
+    end
+
+    # Returns self.
+    # Exists for syntax to ensure in-order matching is performed.
+    def in_order
+      self
+    end
+
     # Common functionality for all match data for this matcher.
     private abstract struct CommonMatchData(ExpectedType, ActualType) < MatchData
       # Creates the match data.

src/spectator/matchers/unordered_array_matcher.cr

@@ -0,0 +1,114 @@
+require "./value_matcher"
+
+module Spectator::Matchers
+  # Matcher for checking that the contents of one array (or similar type)
+  # has the exact same contents as another, but in any order.
+  struct UnorderedArrayMatcher(ExpectedType) < ValueMatcher(Array(ExpectedType))
+    # Determines whether the matcher is satisfied with the partial given to it.
+    # `MatchData` is returned that contains information about the match.
+    def match(partial)
+      actual = partial.actual.to_a
+      missing, extra = array_diff(expected, actual)
+
+      values = ExpectedActual.new(expected, label, actual, partial.label)
+      if missing.empty? && extra.empty?
+        IdenticalMatchData.new(values)
+      else
+        ContentMatchData.new(values, missing, extra)
+      end
+    end
+
+    # Finds the difference of two unordered arrays.
+    # Returns a tuple of arrays - missing from *actual* and extra in *actual*.
+    private def array_diff(expected, actual)
+      extra = actual.dup
+      missing = [] of ExpectedType
+
+      # TODO: OPTIMIZE
+      expected.each do |item|
+        index = extra.index(item)
+        if index
+          extra.delete_at(index)
+        else
+          missing << item
+        end
+      end
+
+      {missing, extra}
+    end
+
+    # Creates the value matcher.
+    # The label should be a string representation of the expectation.
+    # The expected value is stored for later use.
+    def initialize(expected : Array(ExpectedType), label : String)
+      super
+    end
+
+    # Creates the value matcher.
+    # The label is generated by calling `#to_s` on the expected value.
+    # The expected value is stored for later use.
+    def initialize(expected : Array(ExpectedType))
+      super
+    end
+
+    # Common functionality for all match data for this matcher.
+    private abstract struct CommonMatchData(ExpectedType, ActualType) < MatchData
+      # Creates the match data.
+      def initialize(matched, @values : ExpectedActual(Array(ExpectedType), Array(ActualType)))
+        super(matched)
+      end
+
+      # Basic information about the match.
+      def named_tuple
+        {
+          expected: NegatableMatchDataValue.new(@values.expected),
+          actual:   @values.actual,
+        }
+      end
+
+      # Describes the condition that satisfies the matcher.
+      # This is informational and displayed to the end-user.
+      def message
+        "#{@values.actual_label} contains #{@values.expected_label} (unordered)"
+      end
+    end
+
+    # Match data specific to this matcher.
+    # This type is used when the actual value matches the expected value.
+    private struct IdenticalMatchData(ExpectedType, ActualType) < CommonMatchData(ExpectedType, ActualType)
+      # Creates the match data.
+      def initialize(values : ExpectedActual(Array(ExpectedType), Array(ActualType)))
+        super(true, values)
+      end
+
+      # Describes the condition that won't satsify the matcher.
+      # This is informational and displayed to the end-user.
+      def negated_message
+        "#{@values.actual_label} does not contain #{@values.expected_label} (unordered)"
+      end
+    end
+
+    # Match data specific to this matcher.
+    # This type is used when the actual contents differs from the expected contents.
+    private struct ContentMatchData(ExpectedType, ActualType) < CommonMatchData(ExpectedType, ActualType)
+      # Creates the match data.
+      def initialize(values : ExpectedActual(Array(ExpectedType), Array(ActualType)), @missing : Array(ExpectedType), @extra : Array(ActualType))
+        super(false, values)
+      end
+
+      # Information about the match.
+      def named_tuple
+        super.merge({
+          missing: @missing,
+          extra:   @extra,
+        })
+      end
+
+      # Describes the condition that won't satsify the matcher.
+      # This is informational and displayed to the end-user.
+      def negated_message
+        "#{@values.actual_label} does not contain #{@values.expected_label} (content differs)"
+      end
+    end
+  end
+end